Standards, Environments, and Macros attributes(5)
NAME
attributes, architecture, availability, CSI, stability, MT-
Level, standard - attributes of interfaces
DESCRIPTION
The ATRIBUTES 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.
ATRIBUTE TYPE ATRIBUTE 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 peripherals.
Availability
This refers to the software package which contains the com-
mand 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).
Code Set Independence (CSI)
OS utilities and libraries free of dependencies on the pro-
perties of any code sets are said to have Code Set Indepen-
dence (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.
SunOS 5.11 Last change: 29 Jul 2007 1
Standards, Environments, and Macros attributes(5)
For practical reasons, however, this independence is not
absolute. Certain assumptions are still applied to the
current CSI implementation:
o File code is a superset of ASCI.
o To support multi-byte characters and null-
terminated UNIX file names, the NUL and / (slash)
characters cannot be part of any multi-byte charac-
ters.
o Only "stateless" file code encodings are supported.
Stateless encoding avoids shift, locking shift,
designation, invocation, and so forth, although
single shift is not excluded.
o Process code (wchart values) is implementation
dependent and can change over time or between
implementations or between locales.
o Not every object can have names composed of arbi-
trary characters. The names of the following
objects must be composed of ASCI 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
SunOS 5.11 Last change: 29 Jul 2007 2
Standards, Environments, and Macros attributes(5)
o The names of NFS shared files should be composed of
ASCI characters. Although files and directories
may have names and contents composed of characters
from non-ASCI code sets, using only the ASCI
codeset allows NFS mounting across any machine,
regardless of localization. For the commands 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 interna-
tionalization 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 tech-
nologies, 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 sta-
bility 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 proto-
typing, 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 inter-
faces are not only subject to incompatible change or remo-
val, 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
compatibility discussions. Each release level may also
SunOS 5.11 Last change: 29 Jul 2007 3
Standards, Environments, and Macros attributes(5)
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
hardware. Incompatible changes to
Volatile interfaces are possible.
In the context of interface stability, update releases
(occasionally referred to as patch releases) should be con-
sidered equivalent to Micro Releases.
Classifications
The following table summarizes how stability level classif-
ications 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 classifi-
cations, see the appropriate subsection below.
Stability Release Comments
Committed Major (x.0) Incompatibilities are exceptional.
Uncommitted Minor (x.y) Incompatibilities are common.
SunOS 5.11 Last change: 29 Jul 2007 4
Standards, Environments, and Macros attributes(5)
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 exception of the Private classifica-
tion. 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 stabil-
ity level information is Solaris manual pages.
Committed
The intention of a Committed interface is to enable
third parties to develop applications to these inter-
faces, 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 jus-
tifications.
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 notif-
ication and the stability level will be marked Obsolete.
Uncommitted
No commitment is made about either source or binary com-
patibility of these interfaces from one Minor release to
the next. Even the drastic incompatible change of remo-
val of the interface in a Minor release is possible.
SunOS 5.11 Last change: 29 Jul 2007 5
Standards, Environments, and Macros attributes(5)
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 expec-
tation 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 miti-
gation plan.
Uncommitted interfaces generally fall into one of the
following subcategorizes:
1. Interfaces that are experimental or transi-
tional. They are typically used to give outside
developers early access to new or rapidly
changing technology, or to provide an interim
solution to a problem where a more general
solution is anticipated.
2. Interfaces whose specification is controlled by
an outside body yet Sun expects to make a rea-
sonable effort to maintain compatibility with
previous releases until the next Minor release
at which time Sun expects to synchronize with
the external specification.
3. Interfaces whose target audience values innova-
tion (and possibly ease of use) over stability.
This attribute is often associated with admin-
istrative interfaces for higher tier com-
ponents.
For Uncommitted interfaces, Sun makes no claims about
either source or binary compatibility from one minor
release to another. Applications 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 pro-
ducts to quickly track a fluid, rapidly evolving specif-
ication. 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,
SunOS 5.11 Last change: 29 Jul 2007 6
Standards, Environments, and Macros attributes(5)
but unlike specifications controlled by standards bodies
or Free or Open Source Software (FOS) communities which
value interface compatibility, it can not be asserted
that an incompatible change to the interface specifica-
tion would be exceedingly rare. It may also be applied
to FOS 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.
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 identi-
fied 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 com-
ponent (or product) intended only for the use of that
component. A Private interface might still be visible to
or accessible by other components. Because the use of
interfaces private to another component carries great
stability risks, such use is explicitly not supported.
Components not supplied by Sun Microsystems should not
use Private interfaces.
SunOS 5.11 Last change: 29 Jul 2007 7
Standards, Environments, and Macros attributes(5)
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.
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
Obsolete 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 inter-
face 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 following 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
SunOS 5.11 Last change: 29 Jul 2007 8
Standards, Environments, and Macros attributes(5)
this would to have not incompatibly changed pcfs
when the DOS 8.3 naming restrictions were aban-
doned.
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.
Compatibility with Earlier Interface Classification Schemes
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 clas-
sification 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 conflicted with the common use
of the term in FOS communities.
Ambiguity in the definition of Evolving was causing diffi-
culty 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 section.
SunOS 5.11 Last change: 29 Jul 2007 9
Standards, Environments, and Macros attributes(5)
Safe
Safe is an attribute of code that can be called from a
multithreaded 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 mul-
tithreaded application has the responsibility for using
these interfaces in a safe manner, which is different
from whether or not the interface is Safe. For example,
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 protected. It is not safe to use unless the
application arranges for only one thread at time to exe-
cute 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 con-
currency. A library can be safe to use, but not MT-Safe.
For example, surrounding an entire library with a moni-
tor makes the library Safe, but it supports no con-
currency so it is not considered MT-Safe. An MT-Safe
library must permit a reasonable amount of concurrency.
(This definition's purpose is to give precision to what
is meant when a library is described as Safe. The defin-
ition of a Safe library does not specify if the library
supports concurrency. The MT-Safe definition makes it
clear that the library is Safe, and supports some con-
currency. This clarifies the Safe definition, which can
mean anything from being single threaded to being any
degree of multithreaded.)
SunOS 5.11 Last change: 29 Jul 2007 10
Standards, Environments, and Macros attributes(5)
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 sig-
nal. 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 signals 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
pthreadatfork(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 pthreadatfork()
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
SunOS 5.11 Last change: 29 Jul 2007 11
Standards, Environments, and Macros attributes(5)
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 appli-
cation 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 pthreadcancel(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 memory. If the thread has
not installed the appropriate cancellation cleanup
handlers to release the resources appropriately (see
pthreadcancel(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
pthreadcancel(3C) should ensure that they operate in a
Cancel-Safe environment. Libraries that have cancella-
tion points and which acquire resources such as locks or
allocate memory dynamically, also contribute 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 Asynchronous-Cancel-Safety.
An application is considered to be Deferred-Cancel-Safe
when it is Cancel-Safe for threads whose cancellation
type is PTHREADCANCELDEFERED. An application is con-
sidered to be Asynchronous-Cancel-Safe when it is
Cancel-Safe for threads whose cancellation type is
PTHREADCANCELASYNCHRONOUS. Deferred-Cancel-Safety is
easier to achieve than Asynchronous-Cancel-Safety, since
a thread with the deferred cancellation type can be can-
celled 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
SunOS 5.11 Last change: 29 Jul 2007 12
Standards, Environments, and Macros attributes(5)
always be Asynchronous-Cancel-Unsafe. An application
which is Asynchronous-Cancel-Safe is also, by defini-
tion, Deferred-Cancel-Safe.
Standard
Many interfaces are defined and controlled as industry stan-
dards. 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 con-
form, rather than the manual page descriptions of interfaces
based upon a public standard. When the standard or specifi-
cation allows alternative implementation choices, the manual
page usually only describes the alternative implemented by
Sun. The manual page also describes any compatible exten-
sions to the base definition of Standard interfaces provided
by Sun.
No endorsement of the referenced controlling body or docu-
ment should be inferred by its presence as a "Standard"
entry. The controlling body may be a very formal organiza-
tion, as in ISO or ANSI, a less formal, but generally
accepted organization such as IETF, or as informal as the
sole contributor in the case of FOS (Free or Open Source
Software).
SEE ALSO
uname(1), pkgadd(1M), Intro(3), standards(5)
SunOS 5.11 Last change: 29 Jul 2007 13
|
