illumos: manual page: attributes.7

ATTRIBUTES(7) Standards, Environments, and Macros ATTRIBUTES(7)

NAME

attributes, architecture, availability, CSI, stability, MT-Level,
standard - attributes of interfaces

DESCRIPTION

Architecture

Architecture defines processor or specific hardware. See -p option of
uname(1). In some cases, it may indicate required adapters or
peripherals.

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 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:

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. Stateless
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
characters. 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 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 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 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.

Release Levels

Products are given release levels, as well as names, to aid compatibility
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,
compatible changes
to Committed
interfaces, or
likely incompatible
changes to
Uncommitted or
Volatile interfaces.
-----------------------------------------
Micro x.y.z Intended to be
interface compatible
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 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 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.

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 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.

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
subcategories:

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 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 reasonable 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 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.
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 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.

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
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.

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
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 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 this would to have not
incompatibly changed pcfs when the DOS 8.3 naming restrictions
were abandoned.

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 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
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.

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.

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 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 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 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
monitor makes the library Safe, but it supports no concurrency 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 definition 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 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 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 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(7)). 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 memory.
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_cancel(3C)
should ensure that they operate in a Cancel-Safe environment.
Libraries that have cancellation 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
PTHREAD_CANCEL_DEFERRED. An application is considered 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-Cancel-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 application 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 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).