Merge branch 'master' of git://github.com/illumos/illumos-gate

[unleashed.git] / usr / src / man / man5 / attributes.5

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ATTRIBUTES 5 "Jul 29, 2007"
.SH NAME
attributes, architecture, availability, CSI, stability, MT-Level, standard \-
attributes of interfaces
.SH DESCRIPTION
.sp
.LP
The \fBATTRIBUTES\fR 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.
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Architecture    SPARC
_
CSI     Enabled
_
Interface Stability     Committed
_
MT-Level        Safe
_
Standard        See \fBstandards\fR(5).
.TE

.SS "Architecture"
.sp
.LP
Architecture defines processor or specific hardware. See \fB-p\fR option of
\fBuname\fR(1). In some cases, it may indicate required adapters or
peripherals.
.SS "Code Set Independence (CSI)"
.sp
.LP
\fBOS\fR 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 \fBCSI\fR 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.
.sp
.LP
For practical reasons, however, this independence is not absolute. Certain
assumptions are still applied to the current \fBCSI\fR implementation:
.RS +4
.TP
.ie t \(bu
.el o
File code is a superset of \fBASCII\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
To support multi-byte characters and null-terminated  \fBUNIX\fR file names,
the \fINULL\fR and \fB/\fR (slash) characters cannot be part of any multi-byte
characters.
.RE
.RS +4
.TP
.ie t \(bu
.el 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.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Process code (\fBwchar_t\fR values) is implementation dependent and can change
over time or between implementations or between locales.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Not every object can have names composed of arbitrary characters. The names of
the following objects must be composed of \fBASCII\fR characters:
.RS +4
.TP
.ie t \(bu
.el o
User names, group name, and passwords
.RE
.RS +4
.TP
.ie t \(bu
.el o
System name
.RE
.RS +4
.TP
.ie t \(bu
.el o
Names of printers and special devices
.RE
.RS +4
.TP
.ie t \(bu
.el o
Names of terminals (/\fBdev/tty*\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
Process \fBID\fR numbers
.RE
.RS +4
.TP
.ie t \(bu
.el o
Message queues, semaphores, and shared memory labels.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The following may be composed of \fBISO\fR Latin-1 or \fBEUC\fR characters:
.RS +4
.TP
.ie t \(bu
.el o
File names
.RE
.RS +4
.TP
.ie t \(bu
.el o
Directory names
.RE
.RS +4
.TP
.ie t \(bu
.el o
Command names
.RE
.RS +4
.TP
.ie t \(bu
.el o
Shell variables and environmental variable names
.RE
.RS +4
.TP
.ie t \(bu
.el o
Mount points for file systems
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBNIS\fR key names and domain names
.RE
.RE
.RE
.RS +4
.TP
.ie t \(bu
.el o
The names of \fBNFS\fR shared files should be composed of \fBASCII\fR
characters. Although files and directories may have names and contents composed
of characters from non-\fBASCII\fR code sets, using only the \fBASCII\fR
codeset allows \fBNFS\fR mounting across any machine, regardless of
localization. For the commands and utilities that are \fBCSI\fR 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.
.RE
.SS "Interface Stability"
.sp
.LP
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.
.sp
.LP
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.
.sp
.LP
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).
.sp
.LP
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.
.sp
.LP
"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.
.SS "Release Levels"
.sp
.LP
Products are given release levels, as well as names, to aid compatibility
discussions. Each release level may also include changes suitable for lower
levels.
.sp

.sp
.TS
c c c
l l l .
Release Version Significance
_
Major   x.0     T{
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.
T}
_
Minor   x.y     T{
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.
T}
_
Micro   x.y.z   T{
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.
T}
.TE

.sp
.LP
In the context of interface stability, update releases (occasionally referred
to as patch releases) should be considered equivalent to Micro Releases.
.SS "Classifications"
.sp
.LP
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.
.sp

.sp
.TS
c c c
l l l .
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.
.TE

.sp
.LP
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
\fBPrivate\fR 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
\fBPrivate\fR.
.sp
.LP
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.
.sp
.ne 2
.na
\fB\fBCommitted\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
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.
.sp
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.
.RE

.sp
.ne 2
.na
\fB\fBUncommitted\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
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.
.sp
Uncommitted interfaces generally fall into one of the following subcategorizes:
.RS +4
.TP
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.
.RE
.RS +4
.TP
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.
.RE
.RS +4
.TP
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.
.RE
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.
.RE

.sp
.ne 2
.na
\fB\fBVolatile\fR\fR
.ad
.sp .6
.RS 4n
Volatile interfaces can change at any time and for any reason.
.sp
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.
.sp
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.
.sp
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.
.sp
Volatile can also be applied to experimental interfaces.
.sp
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.
.RE

.sp
.ne 2
.na
\fB\fBNot-an-Interface\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
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.
.RE

.sp
.ne 2
.na
\fB\fBPrivate\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
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.
.RE

.sp
.ne 2
.na
\fB\fBObsolete\fR\fR
.ad
.sp .6
.RS 4n
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).
.sp
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.
.RE

.SS "Exceptions"
.sp
.LP
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.
.RS +4
.TP
1.
Security holes where the vulnerability is inherent in the interface.
.RE
.RS +4
.TP
2.
Data corruption where the vulnerability is inherent in the interface.
.RE
.RS +4
.TP
3.
Standards violations uncovered by a change in interpretation or enhancement
of conformance tests.
.RE
.RS +4
.TP
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.
.RE
.RS +4
.TP
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.
.RE
.sp
.LP
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.
.SS "Compatibility with Earlier Interface Classification Schemes"
.sp
.LP
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.
.sp

.sp
.TS
c c c
l l l .
Old     New     Comments
_
Standard        Committed       T{
An entry in the attributes table for the Standard attribute type should appear.
T}
Stable  Committed       Name change.
Evolving        Uncommitted     Actual commitments match.
Unstable        Uncommitted     Name change.
External        Volatile        T{
Name change with expansion of allowed usage.
T}
Obsolete        (Obsolete)      Was a classification, now a modifier.
.TE

.sp
.LP
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.
.sp
.LP
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.
.SS "MT-Level"
.sp
.LP
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 \fBNOTES\fR or \fBUSAGE\fR section.
.sp
.ne 2
.na
\fB\fBSafe\fR\fR
.ad
.sp .6
.RS 4n
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 \fBclose\fR(2) interface safely.
.RE

.sp
.ne 2
.na
\fB\fBUnsafe\fR\fR
.ad
.sp .6
.RS 4n
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 \fB_r\fR suffix appended to the
function name.
.RE

.sp
.ne 2
.na
\fB\fBMT-Safe\fR\fR
.ad
.sp .6
.RS 4n
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.)
.RE

.sp
.ne 2
.na
\fB\fBAsync-Signal-Safe\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
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.
.RE

.sp
.ne 2
.na
\fB\fBMT-Safe with Exceptions\fR\fR
.ad
.sp .6
.RS 4n
See the \fBNOTES\fR or \fBUSAGE\fR sections of these pages for a description of
the exceptions.
.RE

.sp
.ne 2
.na
\fB\fBSafe with Exceptions\fR\fR
.ad
.sp .6
.RS 4n
See the \fBNOTES\fR or \fBUSAGE\fR sections of these pages for a description of
the exceptions.
.RE

.sp
.ne 2
.na
\fB\fBFork-Safe\fR\fR
.ad
.sp .6
.RS 4n
The \fBfork\fR(2) function replicates only the calling thread in the child
process. The \fBfork1\fR(2) function exists for compatibility with the past and
is synonymous with \fBfork()\fR. If a thread other than the one performing the
fork holds a lock when \fBfork()\fR 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.
.sp
When \fBfork()\fR 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 \fBpthread_atfork\fR(3C), which is called when the library is
initialized.
.sp
The \fBforkall\fR(2) function provides the capability for the rare case when a
process needs to replicate all of its threads when performing a fork. No
\fBpthread_atfork()\fR actions are performed when \fBforkall()\fR is called.
There are dangers associated with calling \fBforkall()\fR. If some threads in a
process are performing I/O operations when another thread calls
\fBforkall()\fR, 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 \fBforkall()\fR is discouraged.
.sp
In all Solaris releases prior to Solaris 10, the behavior of \fBfork()\fR
depended on whether or not the application was linked with \fB-lpthread\fR
(POSIX threads, see \fBstandards\fR(5)). If linked with \fB-lpthread\fR,
\fBfork()\fR behaved like \fBfork1()\fR; otherwise it behaved like
\fBforkall()\fR. To avoid any confusion concerning the behavior of
\fBfork()\fR, applications can specifically call \fBfork1()\fR or
\fBforkall()\fR as appropriate.
.RE

.sp
.ne 2
.na
\fB\fBCancel-Safety\fR\fR
.ad
.sp .6
.RS 4n
If a multithreaded application uses \fBpthread_cancel\fR(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 \fBpthread_cancel\fR(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 \fBpthread_cancel\fR(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 \fBPTHREAD_CANCEL_DEFERRED\fR. An application is considered to be
Asynchronous-Cancel-Safe when it is Cancel-Safe for threads whose cancellation
type is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR. 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.
.RE

.SS "Standard"
.sp
.LP
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.
.sp
.LP
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.
.sp
.LP
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).
.SH SEE ALSO
.sp
.LP
\fBuname\fR(1), \fBpkgadd\fR(1M), \fBIntro\fR(3), \fBstandards\fR(5)