attributes(5) Standards, Environments, and Macros attributes(5)NAME
attributes, architecture, availability, CSI, stability, MT-Level, stan‐
dard - attributes of interfaces
DESCRIPTION
The ATTRIBUTES section of a manual page contains a table defining
attribute types and their corresponding values. The following is an
example of an attributes table. Not all attribute types are appropriate
for all types of interfaces.
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │SPARC │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcsu │
├─────────────────────────────┼─────────────────────────────┤
│CSI │Enabled │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Safe │
├─────────────────────────────┼─────────────────────────────┤
│Standard │See standards(5). │
└─────────────────────────────┴─────────────────────────────┘
Architecture
Architecture defines processor or specific hardware. See -p option of
uname(1). In some cases, it may indicate required adapters or peripher‐
als.
Availability
This refers to the software package which contains the command or com‐
ponent being described on the man page. To be able to use the command,
the indicated package must have been installed. For information on how
to add a package see pkgadd(1M).
Code Set Independence (CSI)
OS utilities and libraries free of dependencies on the properties of
any code sets are said to have Code Set Independence (CSI). They have
the attribute of being CSI enabled. This is in contrast to many com‐
mands and utilities, for example, that work only with Extended Unix
Codesets (EUC), an encoding method that allows concurrent support for
up to four code sets and is commonly used to represent Asian character
sets.
For practical reasons, however, this independence is not absolute. Cer‐
tain assumptions are still applied to the current CSI implementation:
o File code is a superset of ASCII.
o To support multi-byte characters and null-terminated UNIX
file names, the NULL and / (slash) characters cannot be part
of any multi-byte characters.
o Only "stateless" file code encodings are supported. State‐
less encoding avoids shift, locking shift, designation,
invocation, and so forth, although single shift is not
excluded.
o Process code (wchar_t values) is implementation dependent
and can change over time or between implementations or
between locales.
o Not every object can have names composed of arbitrary char‐
acters. The names of the following objects must be composed
of ASCII characters:
o User names, group name, and passwords
o System name
o Names of printers and special devices
o Names of terminals (/dev/tty*)
o Process ID numbers
o Message queues, semaphores, and shared memory labels.
o The following may be composed of ISO Latin-1 or EUC
characters:
o File names
o Directory names
o Command names
o Shell variables and environmental variable names
o Mount points for file systems
o NIS key names and domain names
o The names of NFS shared files should be composed of ASCII
characters. Although files and directories may have names
and contents composed of characters from non-ASCII code
sets, using only the ASCII codeset allows NFS mounting
across any machine, regardless of localization. For the com‐
mands and utilities that are CSI enabled, all can handle
single-byte and multi-byte locales released in 2.6. For
applications to get full support of internationalization
services, dynamic binding has to be applied. Statically
bound programs will only get support for C and POSIX
locales.
Interface Stability
Sun often provides developers with early access to new technologies,
which allows developers to evaluate with them as soon as possible.
Unfortunately, new technologies are prone to changes and standardiza‐
tion often results in interface incompatibility from previous versions.
To make reasonable risk assessments, developers need to know how likely
an interface is to change in future releases. To aid developers in mak‐
ing these assessments, interface stability information is included on
some manual pages for commands, entry-points, and file formats.
The more stable interfaces can safely be used by nearly all applica‐
tions, because Sun will endeavor to ensure that these continue to work
in future minor releases. Applications that depend only on Committed
interfaces should reliably continue to function correctly on future
minor releases (but not necessarily on earlier major releases).
The less stable interfaces allow experimentation and prototyping, but
should be used only with the understanding that they might change
incompatibly or even be dropped or replaced with alternatives in future
minor releases.
"Interfaces" that Sun does not document (for example, most kernel data
structures and some symbols in system header files) may be implementa‐
tion artifacts. Such internal interfaces are not only subject to incom‐
patible change or removal, but we are unlikely to mention such a change
in release notes.
Release Levels
Products are given release levels, as well as names, to aid compatibil‐
ity discussions. Each release level may also include changes suitable
for lower levels.
Release Version Significance
──────────────────────────────────────────────────────────────
Major x.0 Likely to contain major feature
additions; adhere to different,
possibly incompatible standard
revisions; and though unlikely,
could change, drop, or replace
Committed interfaces. Initial
product releases are usually 1.0.
──────────────────────────────────────────────────────────────
Minor x.y Compared to an x.0 or earlier
release (y!=0), it is likely to
contain: feature additions, com‐
patible changes to Committed
interfaces, or likely incompati‐
ble changes to Uncommitted or
Volatile interfaces.
──────────────────────────────────────────────────────────────
Micro x.y.z Intended to be interface compati‐
ble with the previous release
(z!=0), but likely to add bug
fixes, performance enhancements,
and support for additional hard‐
ware. Incompatible changes to
Volatile interfaces are possible.
In the context of interface stability, update releases (occasionally
referred to as patch releases) should be considered equivalent to Micro
Releases.
Classifications
The following table summarizes how stability level classifications
relate to release level. The first column lists the Stability Level.
The second column lists the Release Level for Incompatible Changes, and
the third column lists other comments. For a complete discussion of
individual classifications, see the appropriate subsection below.
Stability Release Comments
─────────────────────────────────────────────────────────────────
Committed Major (x.0) Incompatibilities are exceptional.
─────────────────────────────────────────────────────────────────
Uncommitted Minor (x.y) Incompatibilities are common.
─────────────────────────────────────────────────────────────────
Volatile Micro (x.y.z) Incompatibilities are common.
The interface stability level classifications described on this manual
page apply to both source and binary interfaces unless otherwise
stated. All stability level classifications are public, with the excep‐
tion of the Private classification. The precise stability level of a
public interface (one that is documented in the manual pages) is
unspecified unless explicitly stated. The stability level of an undocu‐
mented interface is implicitly Private.
The existence of documentation other than the documentation that is a
component of the Solaris product should not be construed to imply any
level of stability for interfaces provided by the Solaris product. The
only source of stability level information is Solaris manual pages.
Committed
The intention of a Committed interface is to enable third parties
to develop applications to these interfaces, release them, and have
confidence that they will run on all releases of the product after
the one in which the interface was introduced, and within the same
Major release. Even at a Major release, incompatible changes are
expected to be rare, and to have strong justifications.
Interfaces defined and controlled as industry standards are most
often treated as Committed interfaces. In this case, the control‐
ling body and/or public, versioned document is typically noted in a
"Standard" entry in the Attributes table or elsewhere in the docu‐
mentation.
Although a truly exceptional event, incompatible changes are possi‐
ble in any release if the associated defect is serious enough as
outlined in the Exceptions section of this document or in a Minor
release by following the End of Feature process. If support of a
Committed interface must be discontinued, Sun will attempt to pro‐
vide notification and the stability level will be marked Obsolete.
Uncommitted
No commitment is made about either source or binary compatibility
of these interfaces from one Minor release to the next. Even the
drastic incompatible change of removal of the interface in a Minor
release is possible. Uncommitted interfaces are generally not
appropriate for use by release-independent products.
Incompatible changes to the interface are intended to be motivated
by true improvement to the interface which may include ease of use
considerations. The general expectation should be that Uncommitted
interfaces are not likely to change incompatibly and if such
changes occur they will be small in impact and may often have a
mitigation plan.
Uncommitted interfaces generally fall into one of the following
subcategorizes:
1. Interfaces that are experimental or transitional. They
are typically used to give outside developers early
access to new or rapidly changing technology, or to pro‐
vide an interim solution to a problem where a more gen‐
eral solution is anticipated.
2. Interfaces whose specification is controlled by an out‐
side body yet Sun expects to make a reasonable effort to
maintain compatibility with previous releases until the
next Minor release at which time Sun expects to synchro‐
nize with the external specification.
3. Interfaces whose target audience values innovation (and
possibly ease of use) over stability. This attribute is
often associated with administrative interfaces for
higher tier components.
For Uncommitted interfaces, Sun makes no claims about either source
or binary compatibility from one minor release to another. Applica‐
tions developed based on these interfaces may not work in future
minor releases.
Volatile
Volatile interfaces can change at any time and for any reason.
The Volatile interface stability level allows Sun products to
quickly track a fluid, rapidly evolving specification. In many
cases, this is preferred to providing additional stability to the
interface, as it may better meet the expectations of the consumer.
The most common application of this taxonomy level is to interfaces
that are controlled by a body other than Sun, but unlike specifica‐
tions controlled by standards bodies or Free or Open Source Soft‐
ware (FOSS) communities which value interface compatibility, it can
not be asserted that an incompatible change to the interface speci‐
fication would be exceedingly rare. It may also be applied to FOSS
controlled software where it is deemed more important to track the
community with minimal latency than to provide stability to our
customers.
It also common to apply the Volatile classification level to inter‐
faces in the process of being defined by trusted or widely accepted
organization. These are generically referred to as draft stan‐
dards. An "IETF Internet draft" is a well understood example of a
specification under development.
Volatile can also be applied to experimental interfaces.
No assertion is made regarding either source or binary compatibil‐
ity of Volatile interfaces between any two releases, including
patches. Applications containing these interfaces might fail to
function properly in any future release.
Not-an-Interface
The situation occasionally occurs where there exists an entity that
could be inferred to be an interface, but actually is not. Common
examples are output from CLIs intended only for human consumption
and the exact layout of a GUI.
This classification is a convenience term to be used to clarify
such situations where such confusion is identified as likely.
Failure to apply this term to an entity is not an indication that
the entity is some form of interface. It only indicates that the
potential for confusion was not identified.
Private
A Private interface is an interface provided by a component (or
product) intended only for the use of that component. A Private
interface might still be visible to or accessible by other compo‐
nents. Because the use of interfaces private to another component
carries great stability risks, such use is explicitly not sup‐
ported. Components not supplied by Sun Microsystems should not use
Private interfaces.
Most Private interfaces are not documented. It is an exceptional
case when a Private interface is documented. Reasons for document‐
ing a Private interface include, but are not limited to, the inten‐
tion that the interface might be reclassified to one of the public
stability level classifications in the future or the fact that the
interface is inordinately visible.
Obsolete
Obsolete is a modifier that can appear in conjunction with the
above classification levels. The Obsolete modifier indicates an
interface that is "deprecated" and/or no longer advised for general
use. An existing interface may be downgraded from some other status
(such as Committed or Uncommitted) by the application of the Obso‐
lete modifier to encourage customers to migrate from that interface
before it may be removed (or incompatibly changed).
An Obsolete interface is supported in the current release, but is
scheduled to be removed in a future (minor) release. When support
of an interface is to be discontinued, Sun will attempt to provide
notification before discontinuing support. Use of an Obsolete
interface may produce warning messages.
Exceptions
There are rare instances when it is in the best interest of both Sun
and the customer to break the interface stability commitment. The fol‐
lowing list contains the common, known reasons for the interface
provider to violate an interface stability commitment, but does not
preclude others.
1. Security holes where the vulnerability is inherent in the
interface.
2. Data corruption where the vulnerability is inherent in the
interface.
3. Standards violations uncovered by a change in interpretation
or enhancement of conformance tests.
4. An interface specification which isn't controlled by Sun has
been changed incompatibly and the vast majority of interface
consumers expect the newer interface.
5. Not making the incompatible change would be incomprehensible
to our customers. One example of this would to have not
incompatibly changed pcfs when the DOS 8.3 naming restric‐
tions were abandoned.
Incompatible changes allowed by exception will always be delivered in
the "most major" release vehicle possible. However, often the conse‐
quences of the vulnerabilities or contractual branding requirements
will force delivery in a patch.
Compatibility with Earlier Interface Classification Schemes
In releases up to and including Solaris 10, a different interface clas‐
sification scheme was used. The following table summarizes the mapping
between the old and new classification schemes.
Old New Comments
──────────────────────────────────────────────────────────────────
Standard Committed An entry in the attributes table for
the Standard attribute type should
appear.
Stable Committed Name change.
Evolving Uncommitted Actual commitments match.
Unstable Uncommitted Name change.
External Volatile Name change with expansion of allowed
usage.
Obsolete (Obsolete) Was a classification, now a modifier.
The increased importance of Free or Open Source Software motivated the
name change from Stable/Unstable to Committed/Uncommitted. Stable con‐
flicted with the common use of the term in FOSS communities.
Ambiguity in the definition of Evolving was causing difficulty in
interpretation. As part of the migration to the new classification
scheme, many formerly Evolving interfaces were upgraded to Committed.
However, upon encountering the term Evolving, Uncommitted should be
inferred.
MT-Level
Libraries are classified into categories that define their ability to
support multiple threads. Manual pages containing functions that are of
multiple or differing levels describe this in their NOTES or USAGE sec‐
tion.
Safe
Safe is an attribute of code that can be called from a multi‐
threaded application. The effect of calling into a Safe interface
or a safe code segment is that the results are valid even when
called by multiple threads. Often overlooked is the fact that the
result of this Safe interface or safe code segment can have global
consequences that affect all threads. For example, the action of
opening or closing a file from one thread is visible by all the
threads within a process. A multithreaded application has the
responsibility for using these interfaces in a safe manner, which
is different from whether or not the interface is Safe. For exam‐
ple, a multithreaded application that closes a file that is still
in use by other threads within the application is not using the
close(2) interface safely.
Unsafe
An Unsafe library contains global and static data that is not pro‐
tected. It is not safe to use unless the application arranges for
only one thread at time to execute within the library. Unsafe
libraries might contain functions that are Safe; however, most of
the library's functions are unsafe to call. Some functions that are
Unsafe have reentrant counterparts that are MT-Safe. Reentrant
functions are designated by the _r suffix appended to the function
name.
MT-Safe
An MT-Safe library is fully prepared for multithreaded access. It
protects its global and static data with locks, and can provide a
reasonable amount of concurrency. A library can be safe to use, but
not MT-Safe. For example, surrounding an entire library with a mon‐
itor makes the library Safe, but it supports no concurrency so it
is not considered MT-Safe. An MT-Safe library must permit a reason‐
able amount of concurrency. (This definition's purpose is to give
precision to what is meant when a library is described as Safe. The
definition of a Safe library does not specify if the library sup‐
ports concurrency. The MT-Safe definition makes it clear that the
library is Safe, and supports some concurrency. This clarifies the
Safe definition, which can mean anything from being single threaded
to being any degree of multithreaded.)
Async-Signal-Safe
Async-Signal-Safe refers to particular library functions that can
be safely called from a signal handler. A thread that is executing
an Async-Signal-Safe function will not deadlock with itself if
interrupted by a signal. Signals are only a problem for MT-Safe
functions that acquire locks.
Async-Signal-Safe functions are also MT-Safe. Signals are disabled
when locks are acquired in Async-Signal-Safe functions. These sig‐
nals prevent a signal handler that might acquire the same lock from
being called.
MT-Safe with Exceptions
See the NOTES or USAGE sections of these pages for a description of
the exceptions.
Safe with Exceptions
See the NOTES or USAGE sections of these pages for a description of
the exceptions.
Fork-Safe
The fork(2) function replicates only the calling thread in the
child process. The fork1(2) function exists for compatibility with
the past and is synonymous with fork(). If a thread other than the
one performing the fork holds a lock when fork() is called, the
lock will still be held in the child process but there will be no
lock owner since the owning thread was not replicated. A child
calling a function that attempts to acquire the lock will deadlock
itself.
When fork() is called, a Fork-Safe library arranges to have all of
its internal locks held only by the thread performing the fork.
This is usually accomplished with pthread_atfork(3C), which is
called when the library is initialized.
The forkall(2) function provides the capability for the rare case
when a process needs to replicate all of its threads when perform‐
ing a fork. No pthread_atfork() actions are performed when
forkall() is called. There are dangers associated with calling
forkall(). If some threads in a process are performing I/O opera‐
tions when another thread calls forkall(), they will continue per‐
forming the same I/O operations in both the parent and child pro‐
cesses, possibly causing data corruption. For this and other race-
condition reasons, the use of forkall() is discouraged.
In all Solaris releases prior to Solaris 10, the behavior of fork()
depended on whether or not the application was linked with
-lpthread (POSIX threads, see standards(5)). If linked with
-lpthread, fork() behaved like fork1(); otherwise it behaved like
forkall(). To avoid any confusion concerning the behavior of
fork(), applications can specifically call fork1() or forkall() as
appropriate.
Cancel-Safety
If a multithreaded application uses pthread_cancel(3C) to cancel
(that is, kill) a thread, it is possible that the target thread is
killed while holding a resource, such as a lock or allocated mem‐
ory. If the thread has not installed the appropriate cancellation
cleanup handlers to release the resources appropriately (see
pthread_cancel(3C)), the application is "cancel-unsafe", that is,
it is not safe with respect to cancellation. This unsafety could
result in deadlocks due to locks not released by a thread that gets
cancelled, or resource leaks; for example, memory not being freed
on thread cancellation. All applications that use pthread_can‐
cel(3C) should ensure that they operate in a Cancel-Safe environ‐
ment. Libraries that have cancellation points and which acquire
resources such as locks or allocate memory dynamically, also con‐
tribute to the cancel-unsafety of applications that are linked with
these libraries. This introduces another level of safety for
libraries in a multithreaded program: Cancel-Safety. There are two
sub-categories of Cancel-Safety: Deferred-Cancel-Safety, and Asyn‐
chronous-Cancel-Safety. An application is considered to be
Deferred-Cancel-Safe when it is Cancel-Safe for threads whose can‐
cellation type is PTHREAD_CANCEL_DEFERRED. An application is con‐
sidered to be Asynchronous-Cancel-Safe when it is Cancel-Safe for
threads whose cancellation type is PTHREAD_CANCEL_ASYNCHRONOUS.
Deferred-Cancel-Safety is easier to achieve than Asynchronous-Can‐
cel-Safety, since a thread with the deferred cancellation type can
be cancelled only at well-defined cancellation points, whereas a
thread with the asynchronous cancellation type can be cancelled
anywhere. Since all threads are created by default to have the
deferred cancellation type, it might never be necessary to worry
about asynchronous cancel safety. Most applications and libraries
are expected to always be Asynchronous-Cancel-Unsafe. An applica‐
tion which is Asynchronous-Cancel-Safe is also, by definition,
Deferred-Cancel-Safe.
Standard
Many interfaces are defined and controlled as industry standards. When
this is the case, the controlling body and/or public, versioned docu‐
ment is noted in this section.
Programmers producing portable applications should rely on the inter‐
face descriptions present in the standard or specification to which the
application is intended to conform, rather than the manual page
descriptions of interfaces based upon a public standard. When the stan‐
dard or specification allows alternative implementation choices, the
manual page usually only describes the alternative implemented by Sun.
The manual page also describes any compatible extensions to the base
definition of Standard interfaces provided by Sun.
No endorsement of the referenced controlling body or document should be
inferred by its presence as a "Standard" entry. The controlling body
may be a very formal organization, as in ISO or ANSII, a less formal,
but generally accepted organization such as IETF, or as informal as the
sole contributor in the case of FOSS (Free or Open Source Software).
SEE ALSOuname(1), pkgadd(1M), Intro(3), standards(5)SunOS 5.10 29 Jul 2007 attributes(5)