Print this page
Minor markup tweaks (Sy instead of Nm).
*** 391,451 ****
should support at least UTF-8 in addition to ASCII.
.It Em INTERFACE STABILITY
Indicates the level of commitment to the interface. Interfaces can be described
with in the following ways:
.Bl -tag -width Ds
! .It Nm Standard
Indicates that the interface is defined by one or more standards bodies.
Generally, changes to the interface will be carefully managed to conform
to the relevant standards. These interfaces are generally the most suitable
for use in portable programs.
! .It Nm Committed
Indicates that the interface is intended to be preserved for the long-haul, and
will rarely, if ever change, and never without notification (barring
extraordinary and extenuating circumstances). These interfaces are
preferred over other interfaces with the exeception of
! .Nm Standard
interfaces.
! .It Nm Uncommitted
Indicates that the interface may change. Generally, changes to these interfaces
should be infrequent, and some effort will be made to address compatibility
considerations when changing or removing such interfaces. However, there is
no firm commitment to the preservation of the interface. Most often this
is applied to interfaces where operational experience with the interface
is still limited and some need to change may be anticipated.
.Pp
Consumers should expect to revalidate any
! .Nm Uncommitted
interfaces when crossing release boundaries. Products intended for
use on many releases or intended to support compatibility with future
releases should avoid these interfaces.
! .It Nm Volatile
The interface can change at any time for any reason. Often this relates to
interfaces that are part of external software components that are still evolving
rapidly. Consumers should not expect that the interface (either binary or
source level) will be unchanged from one release to the next.
! .It Nm Not-an-Interface
Describes something that is specifically not intended for programmatic
consumption. For example, specific human-readable output, or the layout
of graphical items on a user interface, may be described this way. Generally
programmatic alternatives to these will be available, and should be used
when programmatic consumption is needed.
! .It Nm Private
This is an internal interface. Generally these interfaces should only be
used within the project, and should not be used by other programs or modules.
The interface can and will change without notice as the project needs, at
any time.
.Pp
Most often, Private interfaces will lack any documentation whatsoever, and
generally any undocumented interface can be assumed to be Private.
! .It Nm Obsolete
The interface is not intended for use in new projects or programs, and may
be removed at a future date. The
! .Nm Obsolete
word is a modifier that can
be applied to other commitment levels. For example an
! .Nm Obsolete Committed
interface is unlikely to be removed or changed, but nonetheless new use
is discouraged (perhaps a better newer alternative is present).
.El
.It Em MT-LEVEL
This section describes considerations for the interface when used within
--- 391,451 ----
should support at least UTF-8 in addition to ASCII.
.It Em INTERFACE STABILITY
Indicates the level of commitment to the interface. Interfaces can be described
with in the following ways:
.Bl -tag -width Ds
! .It Sy Standard
Indicates that the interface is defined by one or more standards bodies.
Generally, changes to the interface will be carefully managed to conform
to the relevant standards. These interfaces are generally the most suitable
for use in portable programs.
! .It Sy Committed
Indicates that the interface is intended to be preserved for the long-haul, and
will rarely, if ever change, and never without notification (barring
extraordinary and extenuating circumstances). These interfaces are
preferred over other interfaces with the exeception of
! .Sy Standard
interfaces.
! .It Sy Uncommitted
Indicates that the interface may change. Generally, changes to these interfaces
should be infrequent, and some effort will be made to address compatibility
considerations when changing or removing such interfaces. However, there is
no firm commitment to the preservation of the interface. Most often this
is applied to interfaces where operational experience with the interface
is still limited and some need to change may be anticipated.
.Pp
Consumers should expect to revalidate any
! .Sy Uncommitted
interfaces when crossing release boundaries. Products intended for
use on many releases or intended to support compatibility with future
releases should avoid these interfaces.
! .It Sy Volatile
The interface can change at any time for any reason. Often this relates to
interfaces that are part of external software components that are still evolving
rapidly. Consumers should not expect that the interface (either binary or
source level) will be unchanged from one release to the next.
! .It Sy Not-an-Interface
Describes something that is specifically not intended for programmatic
consumption. For example, specific human-readable output, or the layout
of graphical items on a user interface, may be described this way. Generally
programmatic alternatives to these will be available, and should be used
when programmatic consumption is needed.
! .It Sy Private
This is an internal interface. Generally these interfaces should only be
used within the project, and should not be used by other programs or modules.
The interface can and will change without notice as the project needs, at
any time.
.Pp
Most often, Private interfaces will lack any documentation whatsoever, and
generally any undocumented interface can be assumed to be Private.
! .It Sy Obsolete
The interface is not intended for use in new projects or programs, and may
be removed at a future date. The
! .Sy Obsolete
word is a modifier that can
be applied to other commitment levels. For example an
! .Sy Obsolete Committed
interface is unlikely to be removed or changed, but nonetheless new use
is discouraged (perhaps a better newer alternative is present).
.El
.It Em MT-LEVEL
This section describes considerations for the interface when used within
*** 452,494 ****
programs that use multiple threads. More discussion of these considerations
is made in the MT-Level section of
.Xr attributes 5 .
The interface can be described in the following ways.
.Bl -tag -width Ds
! .It Nm Safe
Indicates the interface is safe for use within multiple threads. There
may be additional caveats that apply, in which case those will be
described. Note that some interfaces have semantics which may affect
other threads, but these should be an intrinsic part of the interface
rather than an unexpected side effect. For example, closing a file in
one thread will cause that file to be closed in all threads.
! .It Nm Unsafe
Indicates the interface is unsuitable for concurrent use within multiple
threads. A threaded application may still make use of the interface, but
will be required to provide external synchronization means to ensure that
only a single thread calls the interface at a time.
! .It Nm MT-Safe
Indicates that the interface is not only safe for concurrent use, but is
designed for such use. For example, a
! .Nm Safe
interface may make use of a global lock to provide safety, but at reduced
internal concurrency, whereas an
! .Nm MT-Safe
interface will be designed to be efficient even when used concurrently.
! .It Nm Async-Signal-Safe
Indicates that the library is safe for use within a signal handler. An
! .Nm MT-Safe
interface can be made
! .Nm Async-Signal-Safe
by ensuring that it blocks signals when acquiring locks.
! .It Nm Safe with Exections
As for
! .Nm Safe
but with specific exceptions noted.
! .It Nm MT-Safe with Exections
As for
! .Nm MT-Safe
but with specific exceptions noted.
.El
.It Em SECURITY
Documents any security precautions that operators should consider.
.It Em SEE ALSO
--- 452,494 ----
programs that use multiple threads. More discussion of these considerations
is made in the MT-Level section of
.Xr attributes 5 .
The interface can be described in the following ways.
.Bl -tag -width Ds
! .It Sy Safe
Indicates the interface is safe for use within multiple threads. There
may be additional caveats that apply, in which case those will be
described. Note that some interfaces have semantics which may affect
other threads, but these should be an intrinsic part of the interface
rather than an unexpected side effect. For example, closing a file in
one thread will cause that file to be closed in all threads.
! .It Sy Unsafe
Indicates the interface is unsuitable for concurrent use within multiple
threads. A threaded application may still make use of the interface, but
will be required to provide external synchronization means to ensure that
only a single thread calls the interface at a time.
! .It Sy MT-Safe
Indicates that the interface is not only safe for concurrent use, but is
designed for such use. For example, a
! .Sy Safe
interface may make use of a global lock to provide safety, but at reduced
internal concurrency, whereas an
! .Sy MT-Safe
interface will be designed to be efficient even when used concurrently.
! .It Sy Async-Signal-Safe
Indicates that the library is safe for use within a signal handler. An
! .Sy MT-Safe
interface can be made
! .Sy Async-Signal-Safe
by ensuring that it blocks signals when acquiring locks.
! .It Sy Safe with Exections
As for
! .Sy Safe
but with specific exceptions noted.
! .It Sy MT-Safe with Exections
As for
! .Sy MT-Safe
but with specific exceptions noted.
.El
.It Em SECURITY
Documents any security precautions that operators should consider.
.It Em SEE ALSO