376 Documents error handling in sections 2, 3, and 9.
 377 .Pp
 378 See
 379 .Sx \&Er .
 380 .It Em ARCHITECTURE
 381 This section is usually absent, but will be present when the
 382 interface is specific to one or more architectures.
 383 .It Em CODE SET INDEPENDENCE
 384 Indicates whether the interface operates correctly with various different
 385 code sets.  True independent code sets will support not only ASCII and
 386 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 387 UTF-8 and GB2312.
 388 .Pp
 389 Generally there will be some limitations that are fairly standard.  See
 390 .Xr standards 5 for more information about some of these.  Most interfaces
 391 should support at least UTF-8 in addition to ASCII.
 392 .It Em INTERFACE STABILITY
 393 Indicates the level of commitment to the interface. Interfaces can be described
 394 with in the following ways:
 395 .Bl -tag -width Ds
 396 .It Nm Standard
 397 Indicates that the interface is defined by one or more standards bodies.
 398 Generally, changes to the interface will be carefully managed to conform
 399 to the relevant standards.  These interfaces are generally the most suitable
 400 for use in portable programs.
 401 .It Nm Committed
 402 Indicates that the interface is intended to be preserved for the long-haul, and
 403 will rarely, if ever change, and never without notification (barring
 404 extraordinary and extenuating circumstances). These interfaces are
 405 preferred over other interfaces with the exeception of
 406 .Nm Standard
 407 interfaces.
 408 .It Nm Uncommitted
 409 Indicates that the interface may change.  Generally, changes to these interfaces
 410 should be infrequent, and some effort will be made to address compatibility
 411 considerations when changing or removing such interfaces.  However, there is
 412 no firm commitment to the preservation of the interface.  Most often this
 413 is applied to interfaces where operational experience with the interface
 414 is still limited and some need to change may be anticipated.
 415 .Pp
 416 Consumers should expect to revalidate any
 417 .Nm Uncommitted
 418 interfaces when crossing release boundaries.  Products intended for
 419 use on many releases or intended to support compatibility with future
 420 releases should avoid these interfaces.
 421 .It Nm Volatile
 422 The interface can change at any time for any reason. Often this relates to
 423 interfaces that are part of external software components that are still evolving
 424 rapidly.  Consumers should not expect that the interface (either binary or
 425 source level) will be unchanged from one release to the next.
 426 .It Nm Not-an-Interface
 427 Describes something that is specifically not intended for programmatic
 428 consumption.  For example, specific human-readable output, or the layout
 429 of graphical items on a user interface, may be described this way.  Generally
 430 programmatic alternatives to these will be available, and should be used
 431 when programmatic consumption is needed.
 432 .It Nm Private
 433 This is an internal interface.  Generally these interfaces should only be
 434 used within the project, and should not be used by other programs or modules.
 435 The interface can and will change without notice as the project needs, at
 436 any time.
 437 .Pp
 438 Most often, Private interfaces will lack any documentation whatsoever, and
 439 generally any undocumented interface can be assumed to be Private.
 440 .It Nm Obsolete
 441 The interface is not intended for use in new projects or programs, and may
 442 be removed at a future date.  The
 443 .Nm Obsolete
 444 word is a modifier that can
 445 be applied to other commitment levels. For example an
 446 .Nm Obsolete Committed
 447 interface is unlikely to be removed or changed, but nonetheless new use
 448 is discouraged (perhaps a better newer alternative is present).
 449 .El
 450 .It Em MT-LEVEL
 451 This section describes considerations for the interface when used within
 452 programs that use multiple threads.  More discussion of these considerations
 453 is made in the MT-Level section of
 454 .Xr attributes 5 .
 455 The interface can be described in the following ways.
 456 .Bl -tag -width Ds
 457 .It Nm Safe
 458 Indicates the interface is safe for use within multiple threads.  There
 459 may be additional caveats that apply, in which case those will be
 460 described.  Note that some interfaces have semantics which may affect
 461 other threads, but these should be an intrinsic part of the interface
 462 rather than an unexpected side effect.  For example, closing a file in
 463 one thread will cause that file to be closed in all threads.
 464 .It Nm Unsafe
 465 Indicates the interface is unsuitable for concurrent use within multiple
 466 threads.  A threaded application may still make use of the interface, but
 467 will be required to provide external synchronization means to ensure that
 468 only a single thread calls the interface at a time.
 469 .It Nm MT-Safe
 470 Indicates that the interface is not only safe for concurrent use, but is
 471 designed for such use.  For example, a
 472 .Nm Safe
 473 interface may make use of a global lock to provide safety, but at reduced
 474 internal concurrency, whereas an
 475 .Nm MT-Safe
 476 interface will be designed to be efficient even when used concurrently.
 477 .It Nm Async-Signal-Safe
 478 Indicates that the library is safe for use within a signal handler.  An
 479 .Nm MT-Safe
 480 interface can be made
 481 .Nm Async-Signal-Safe
 482 by ensuring that it blocks signals when acquiring locks.
 483 .It Nm Safe with Exections
 484 As for
 485 .Nm Safe
 486 but with specific exceptions noted.
 487 .It Nm MT-Safe with Exections
 488 As for
 489 .Nm MT-Safe
 490 but with specific exceptions noted.
 491 .El
 492 .It Em SECURITY
 493 Documents any security precautions that operators should consider.
 494 .It Em SEE ALSO
 495 References other manuals with related topics.
 496 This section should exist for most manuals.
 497 Cross-references should conventionally be ordered first by section, then
 498 alphabetically.
 499 .Pp
 500 References to other documentation concerning the topic of the manual page,
 501 for example authoritative books or journal articles, may also be
 502 provided in this section.
 503 .Pp
 504 See
 505 .Sx \&Rs
 506 and
 507 .Sx \&Xr .
 508 .It Em STANDARDS
 509 References any standards implemented or used.

 376 Documents error handling in sections 2, 3, and 9.
 377 .Pp
 378 See
 379 .Sx \&Er .
 380 .It Em ARCHITECTURE
 381 This section is usually absent, but will be present when the
 382 interface is specific to one or more architectures.
 383 .It Em CODE SET INDEPENDENCE
 384 Indicates whether the interface operates correctly with various different
 385 code sets.  True independent code sets will support not only ASCII and
 386 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 387 UTF-8 and GB2312.
 388 .Pp
 389 Generally there will be some limitations that are fairly standard.  See
 390 .Xr standards 5 for more information about some of these.  Most interfaces
 391 should support at least UTF-8 in addition to ASCII.
 392 .It Em INTERFACE STABILITY
 393 Indicates the level of commitment to the interface. Interfaces can be described
 394 with in the following ways:
 395 .Bl -tag -width Ds
 396 .It Sy Standard
 397 Indicates that the interface is defined by one or more standards bodies.
 398 Generally, changes to the interface will be carefully managed to conform
 399 to the relevant standards.  These interfaces are generally the most suitable
 400 for use in portable programs.
 401 .It Sy Committed
 402 Indicates that the interface is intended to be preserved for the long-haul, and
 403 will rarely, if ever change, and never without notification (barring
 404 extraordinary and extenuating circumstances). These interfaces are
 405 preferred over other interfaces with the exeception of
 406 .Sy Standard
 407 interfaces.
 408 .It Sy Uncommitted
 409 Indicates that the interface may change.  Generally, changes to these interfaces
 410 should be infrequent, and some effort will be made to address compatibility
 411 considerations when changing or removing such interfaces.  However, there is
 412 no firm commitment to the preservation of the interface.  Most often this
 413 is applied to interfaces where operational experience with the interface
 414 is still limited and some need to change may be anticipated.
 415 .Pp
 416 Consumers should expect to revalidate any
 417 .Sy Uncommitted
 418 interfaces when crossing release boundaries.  Products intended for
 419 use on many releases or intended to support compatibility with future
 420 releases should avoid these interfaces.
 421 .It Sy Volatile
 422 The interface can change at any time for any reason. Often this relates to
 423 interfaces that are part of external software components that are still evolving
 424 rapidly.  Consumers should not expect that the interface (either binary or
 425 source level) will be unchanged from one release to the next.
 426 .It Sy Not-an-Interface
 427 Describes something that is specifically not intended for programmatic
 428 consumption.  For example, specific human-readable output, or the layout
 429 of graphical items on a user interface, may be described this way.  Generally
 430 programmatic alternatives to these will be available, and should be used
 431 when programmatic consumption is needed.
 432 .It Sy Private
 433 This is an internal interface.  Generally these interfaces should only be
 434 used within the project, and should not be used by other programs or modules.
 435 The interface can and will change without notice as the project needs, at
 436 any time.
 437 .Pp
 438 Most often, Private interfaces will lack any documentation whatsoever, and
 439 generally any undocumented interface can be assumed to be Private.
 440 .It Sy Obsolete
 441 The interface is not intended for use in new projects or programs, and may
 442 be removed at a future date.  The
 443 .Sy Obsolete
 444 word is a modifier that can
 445 be applied to other commitment levels. For example an
 446 .Sy Obsolete Committed
 447 interface is unlikely to be removed or changed, but nonetheless new use
 448 is discouraged (perhaps a better newer alternative is present).
 449 .El
 450 .It Em MT-LEVEL
 451 This section describes considerations for the interface when used within
 452 programs that use multiple threads.  More discussion of these considerations
 453 is made in the MT-Level section of
 454 .Xr attributes 5 .
 455 The interface can be described in the following ways.
 456 .Bl -tag -width Ds
 457 .It Sy Safe
 458 Indicates the interface is safe for use within multiple threads.  There
 459 may be additional caveats that apply, in which case those will be
 460 described.  Note that some interfaces have semantics which may affect
 461 other threads, but these should be an intrinsic part of the interface
 462 rather than an unexpected side effect.  For example, closing a file in
 463 one thread will cause that file to be closed in all threads.
 464 .It Sy Unsafe
 465 Indicates the interface is unsuitable for concurrent use within multiple
 466 threads.  A threaded application may still make use of the interface, but
 467 will be required to provide external synchronization means to ensure that
 468 only a single thread calls the interface at a time.
 469 .It Sy MT-Safe
 470 Indicates that the interface is not only safe for concurrent use, but is
 471 designed for such use.  For example, a
 472 .Sy Safe
 473 interface may make use of a global lock to provide safety, but at reduced
 474 internal concurrency, whereas an
 475 .Sy MT-Safe
 476 interface will be designed to be efficient even when used concurrently.
 477 .It Sy Async-Signal-Safe
 478 Indicates that the library is safe for use within a signal handler.  An
 479 .Sy MT-Safe
 480 interface can be made
 481 .Sy Async-Signal-Safe
 482 by ensuring that it blocks signals when acquiring locks.
 483 .It Sy Safe with Exections
 484 As for
 485 .Sy Safe
 486 but with specific exceptions noted.
 487 .It Sy MT-Safe with Exections
 488 As for
 489 .Sy MT-Safe
 490 but with specific exceptions noted.
 491 .El
 492 .It Em SECURITY
 493 Documents any security precautions that operators should consider.
 494 .It Em SEE ALSO
 495 References other manuals with related topics.
 496 This section should exist for most manuals.
 497 Cross-references should conventionally be ordered first by section, then
 498 alphabetically.
 499 .Pp
 500 References to other documentation concerning the topic of the manual page,
 501 for example authoritative books or journal articles, may also be
 502 provided in this section.
 503 .Pp
 504 See
 505 .Sx \&Rs
 506 and
 507 .Sx \&Xr .
 508 .It Em STANDARDS
 509 References any standards implemented or used.