Print this page
manpage lint.


 377 .It Em ERRORS
 378 Documents error handling in sections 2, 3, and 9.
 379 .Pp
 380 See
 381 .Sx \&Er .
 382 .It Em ARCHITECTURE
 383 This section is usually absent, but will be present when the
 384 interface is specific to one or more architectures.
 385 .It Em CODE SET INDEPENDENCE
 386 Indicates whether the interface operates correctly with various different
 387 code sets.  True independent code sets will support not only ASCII and
 388 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 389 UTF-8 and GB2312.
 390 .Pp
 391 Generally there will be some limitations that are fairly standard.  See
 392 .Xr standards 5 for more information about some of these.  Most interfaces
 393 should support at least UTF-8 in addition to ASCII.
 394 .It Em INTERFACE STABILITY
 395 Indicates the level of commitment to the interface. Interfaces can be described
 396 with in the following ways:
 397 .Bl -tag
 398 .It Nm Standard
 399 Indicates that the interface is defined by one or more standards bodies.
 400 Generally, changes to the interface will be carefully managed to conform
 401 to the relevant standards.  These interfaces are generally the most suitable
 402 for use in portable programs.
 403 .It Nm Committed
 404 Indicates that the interface is intended to be preserved for the long-haul, and
 405 will rarely, if ever change, and never without notification (barring
 406 extraordinary and extenuating circumstances). These interfaces are 
 407 preferred over other interfaces with the exeception of
 408 .Nm Standard
 409 interfaces.
 410 .It Nm Uncommitted
 411 Indicates that the interface may change.  Generally, changes to these interfaces
 412 should be infrequent, and some effort will be made to address compatibility
 413 considerations when changing or removing such interfaces.  However, there is
 414 no firm commitment to the preservation of the interface.  Most often this
 415 is applied to interfaces where operational experience with the interface
 416 is still limited and some need to change may be anticipated.
 417 .Pp


 438 any time.
 439 .Pp
 440 Most often, Private interfaces will lack any documentation whatsoever, and
 441 generally any undocumented interface can be assumed to be Private.
 442 .It Nm Obsolete
 443 The interface is not intended for use in new projects or programs, and may
 444 be removed at a future date.  The
 445 .Nm Obsolete
 446 word is a modifier that can
 447 be applied to other commitment levels. For example an
 448 .Nm Obsolete Committed
 449 interface is unlikely to be removed or changed, but nonetheless new use
 450 is discouraged (perhaps a better newer alternative is present).
 451 .El
 452 .It Em MT-LEVEL
 453 This section describes considerations for the interface when used within
 454 programs that use multiple threads.  More discussion of these considerations
 455 is made in the MT-Level section of
 456 .Xr attributes 5 .
 457 The interface can be described in the following ways.
 458 .Bl -tag
 459 .It Nm Safe
 460 Indicates the interface is safe for use within multiple threads.  There
 461 may be additional caveats that apply, in which case those will be
 462 described.  Note that some interfaces have semantics which may affect
 463 other threads, but these should be an intrinsic part of the interface
 464 rather than an unexpected side effect.  For example, closing a file in
 465 one thread will cause that file to be closed in all threads.
 466 .It Nm Unsafe
 467 Indicates the interface is unsuitable for concurrent use within multiple
 468 threads.  A threaded application may still make use of the interface, but
 469 will be required to provide external synchronization means to ensure that
 470 only a single thread calls the interface at a time.
 471 .It Nm MT-Safe
 472 Indicates that the interface is not only safe for concurrent use, but is
 473 designed for such use.  For example, a
 474 .Nm Safe
 475 interface may make use of a global lock to provide safety, but at reduced
 476 internal concurrency, whereas an
 477 .Nm MT-Safe
 478 interface will be designed to be efficient even when used concurrently.




 377 .It Em ERRORS
 378 Documents error handling in sections 2, 3, and 9.
 379 .Pp
 380 See
 381 .Sx \&Er .
 382 .It Em ARCHITECTURE
 383 This section is usually absent, but will be present when the
 384 interface is specific to one or more architectures.
 385 .It Em CODE SET INDEPENDENCE
 386 Indicates whether the interface operates correctly with various different
 387 code sets.  True independent code sets will support not only ASCII and
 388 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 389 UTF-8 and GB2312.
 390 .Pp
 391 Generally there will be some limitations that are fairly standard.  See
 392 .Xr standards 5 for more information about some of these.  Most interfaces
 393 should support at least UTF-8 in addition to ASCII.
 394 .It Em INTERFACE STABILITY
 395 Indicates the level of commitment to the interface. Interfaces can be described
 396 with in the following ways:
 397 .Bl -tag -width Ds
 398 .It Nm Standard
 399 Indicates that the interface is defined by one or more standards bodies.
 400 Generally, changes to the interface will be carefully managed to conform
 401 to the relevant standards.  These interfaces are generally the most suitable
 402 for use in portable programs.
 403 .It Nm Committed
 404 Indicates that the interface is intended to be preserved for the long-haul, and
 405 will rarely, if ever change, and never without notification (barring
 406 extraordinary and extenuating circumstances). These interfaces are
 407 preferred over other interfaces with the exeception of
 408 .Nm Standard
 409 interfaces.
 410 .It Nm Uncommitted
 411 Indicates that the interface may change.  Generally, changes to these interfaces
 412 should be infrequent, and some effort will be made to address compatibility
 413 considerations when changing or removing such interfaces.  However, there is
 414 no firm commitment to the preservation of the interface.  Most often this
 415 is applied to interfaces where operational experience with the interface
 416 is still limited and some need to change may be anticipated.
 417 .Pp


 438 any time.
 439 .Pp
 440 Most often, Private interfaces will lack any documentation whatsoever, and
 441 generally any undocumented interface can be assumed to be Private.
 442 .It Nm Obsolete
 443 The interface is not intended for use in new projects or programs, and may
 444 be removed at a future date.  The
 445 .Nm Obsolete
 446 word is a modifier that can
 447 be applied to other commitment levels. For example an
 448 .Nm Obsolete Committed
 449 interface is unlikely to be removed or changed, but nonetheless new use
 450 is discouraged (perhaps a better newer alternative is present).
 451 .El
 452 .It Em MT-LEVEL
 453 This section describes considerations for the interface when used within
 454 programs that use multiple threads.  More discussion of these considerations
 455 is made in the MT-Level section of
 456 .Xr attributes 5 .
 457 The interface can be described in the following ways.
 458 .Bl -tag -width Ds
 459 .It Nm Safe
 460 Indicates the interface is safe for use within multiple threads.  There
 461 may be additional caveats that apply, in which case those will be
 462 described.  Note that some interfaces have semantics which may affect
 463 other threads, but these should be an intrinsic part of the interface
 464 rather than an unexpected side effect.  For example, closing a file in
 465 one thread will cause that file to be closed in all threads.
 466 .It Nm Unsafe
 467 Indicates the interface is unsuitable for concurrent use within multiple
 468 threads.  A threaded application may still make use of the interface, but
 469 will be required to provide external synchronization means to ensure that
 470 only a single thread calls the interface at a time.
 471 .It Nm MT-Safe
 472 Indicates that the interface is not only safe for concurrent use, but is
 473 designed for such use.  For example, a
 474 .Nm Safe
 475 interface may make use of a global lock to provide safety, but at reduced
 476 internal concurrency, whereas an
 477 .Nm MT-Safe
 478 interface will be designed to be efficient even when used concurrently.