Tribblix: 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).