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.
Architecture defines processor or specific hardware. See -p option of uname(1). In some cases, it may indicate required adapters or peripherals.
This refers to the software package which contains the command or component 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).
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 commands 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. Certain assumptions are still applied to the current CSI implementation:
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 standardization 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 making 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 applications, 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 implementation artifacts. Such internal interfaces are not only subject to incompatible change or removal, but we are unlikely to mention such a change in release notes.
Products are given release levels, as well as names, to aid compatibility discussions. Each release level may also include changes suitable for lower levels.
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.
In the context of interface stability, update releases (occasionally referred to as patch releases) should be considered equivalent to Micro Releases.
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.
|Committed||Major (x.0)||Incompatibilities are exceptional.|
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 exception 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 undocumented 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.
Interfaces defined and controlled as industry standards are most often treated as Committed interfaces. In this case, the controlling body and/or public, versioned document is typically noted in a "Standard" entry in the Attributes table or elsewhere in the documentation.
Although a truly exceptional event, incompatible changes are possible 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 provide notification and the stability level will be marked Obsolete.
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:
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 specifications controlled by standards bodies or Free or Open Source Software (FOSS) communities which value interface compatibility, it can not be asserted that an incompatible change to the interface specification 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 interfaces in the process of being defined by trusted or widely accepted organization. These are generically referred to as draft standards. 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 compatibility of Volatile interfaces between any two releases, including patches. Applications containing these interfaces might fail to function properly in any future release.
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.
Most Private interfaces are not documented. It is an exceptional case when a Private interface is documented. Reasons for documenting a Private interface include, but are not limited to, the intention 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.
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.
There are rare instances when it is in the best interest of both Sun and the customer to break the interface stability commitment. The following list contains the common, known reasons for the interface provider to violate an interface stability commitment, but does not preclude others.
Incompatible changes allowed by exception will always be delivered in the "most major" release vehicle possible. However, often the consequences of the vulnerabilities or contractual branding requirements will force delivery in a patch.
In releases up to and including Solaris 10, a different interface classification scheme was used. The following table summarizes the mapping between the old and new classification schemes.
An entry in the attributes table for the Standard attribute type should appear.
The increased importance of Free or Open Source Software motivated the name change from Stable/Unstable to Committed/Uncommitted. Stable conflicted 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.
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 section.
Async-Signal-Safe functions are also MT-Safe. Signals are disabled when locks are acquired in Async-Signal-Safe functions. These signals prevent a signal handler that might acquire the same lock from being called.
MT-Safe with Exceptions
Safe with Exceptions
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 performing 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 operations when another thread calls forkall(), they will continue performing the same I/O operations in both the parent and child processes, 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.
Many interfaces are defined and controlled as industry standards. When this is the case, the controlling body and/or public, versioned document is noted in this section.
Programmers producing portable applications should rely on the interface 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 standard 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).
uname(1), pkgadd(1M), Intro(3), standards(5)