attributes(5) Standards, Environments, and Macros attributes(5)
NAME
attributes, architecture, availability, CSI, stability, MT-Level -
attributes of interfaces
DESCRIPTION
The ATTRIBUTES section of a manual page contains a table (see below)
defining attribute types and their corresponding values.
tab() allbox; cw(2.750000i)| cw(2.750000i) lw(2.750000i)|
lw(2.750000i). ATTRIBUTE TYPEATTRIBUTE VALUE ArchitectureSPARC Avail-
abilitySUNWcsu CSIEnabled Interface StabilityUnstable MT-LevelSafe
Architecture
Architecture defines processor or specific hardware. See -p option of
uname(1). In some cases, it may indicate required adapters or peripher-
als.
Availability
This refers to the software package which contains the command or com-
ponent 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 which are free of dependencies on the prop-
erties 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 char-
acter sets.
However, for practical reasons, this independence is not absolute. Cer-
tain 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 char-
acters:
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 charac-
ters:
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 charac-
ters. 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 interna-
tionalization services, dynamic binding has to be applied. Stati-
cally 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 standardiza-
tion 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 mak-
ing 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 applica-
tions, because Sun will endeavor to ensure that these continue to work
in future minor releases. Applications that depend only on Standard and
Stable 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 implementa-
tion artifacts. Such internal interfaces are not only subject to incom-
patible 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 compatibil-
ity discussions. Each release level may also include changes suitable
for lower levels.
tab(); lw(1.833333i) lw(1.833333i) lw(1.833333i). ReleaseVersion-
Significance Majorx.0T{ Likely to contain major feature additions;
adhere to different, possibly incompatible Standard revisions; and
though unlikely, could change, drop, or replace Standard or Stable
interfaces. Initial product releases are usually 1.0. T} Minorx.yT{
Compared to an x.0 or earlier release (y!=0), it's likely to contain:
minor feature additions, compatible Standard and Stable interfaces,
possibly incompatible Evolving interfaces, or likely incompatible
Unstable interfaces. T} Microx.y.zT{ Intended to be interface compati-
ble with the previous release (z!=0), but likely to add bug fixes, per-
formance enhancements, and support for additional hardware. T}
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 Incompatable Changes, and
the third column lists other comments. For a complete discussion of
individual classifications, see the appropriate subsection below.
tab(); lw(1.306020i) lw(1.637124i) lw(2.556856i). StabilityReleaseCom-
ments StandardMajor (x.0)Actual or de facto. StableMajor (x.0)Incom-
patibilities are exceptional. EvolvingMinor (x.y)T{ Migration advice
might accompany an incompatibility. T} UnstableMinor (x.y)T{ Experi-
mental or transitional: incompatibilities are common. T} ExternalMicro
(x.y.z)T{ Not controlled by Sun: intrarelease incompatibilities are
common. T} ObsoleteMinor (x.y)T{ Deprecated interface: likely to be
removed in a future minor release. T}
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 excep-
tion of the Private classification. The stability level of a documented
interface (one that is documented in the manual pages) is unspecified
unless explicitly stated. The stability level of an undocumented inter-
face 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.
Standard[: [organization_name,] standard_name, version]
The documented interface complies with the standard listed. If a
standard is not specified the interface is defined by several stan-
dards. This is usually the hierarchy built up from the C Language
(defined by ISO/IEC or K&R), SVID 3 and associated ABIs (defined by
AT&T), the POSIX standards (defined by IEEE and ISO/IEC), and the
Single UNIX Specifications (defined by The Open Group). See stan-
dards(5) for a complete list of these standards.
Most of these interfaces are defined by a formal standard, and con-
trolled by a standards development organization. Changes will usu-
ally be made in accordance with approved changes to that standard.
This stability level can also apply to interfaces that have been
adopted (without a formal standard) by an "industry convention."
Support is provided for only the specified version(s) of a stan-
dard; support for later versions is not guaranteed. If the stan-
dards development organization approves a non-upward-compatible
change to a Standard interface that Sun decides to support, Sun
will announce a compatibility and migration strategy.
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 man-
ual page descriptions of Standard interfaces. 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.
Stable
A Stable interface is a mature interface under Sun's control. Sun
will try to avoid non-upwards-compatible changes to these inter-
faces, especially in minor or micro releases.
If support of a Stable interface must be discontinued, Sun will
attempt to provide notification and the stability level changes to
Obsolete.
Evolving
An Evolving interface may eventually become Standard or Stable but
is still in transition.
Sun will make reasonable efforts to ensure compatibility with pre-
vious releases as it evolves. When non-upwards compatible changes
become necessary, they will occur in minor and major releases; such
changes will be avoided in micro releases whenever possible. If
such a change is necessary, it will be documented in the release
notes for the affected release, and when feasible, Sun will provide
migration aids for binary compatibility and continued source devel-
opment.
External
An External interface is controlled by an entity other than Sun. At
Sun's discretion, Sun can deliver as part of any release updated
and possibly incompatible versions of such interfaces, subject to
their availability from the controlling entity. This classification
is typically applied to publicly available "freeware" and similar
objects.
For External interfaces, Sun makes no claims regarding either
source or binary compatibility between any two releases. Applica-
tions based on these interfaces might not work in future releases,
including patches that contain External interfaces.
Unstable
An Unstable interface is provided to give developers early access
to new or rapidly changing technology or as an interim solution to
a problem for which a more stable solution is anticipated in the
future.
For Unstable interfaces, Sun makes no claims about either source or
binary compatibility from one minor release to another. Applica-
tions developed based on these interfaces may not work in future
minor releases.
Obsolete: Scheduled for removal after event
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.
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 compo-
nents. Because the use of interfaces private to another component
carries great stability risks, such use is explicitly not sup-
ported. 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 document-
ing a Private interface include, but are not limited to, the inten-
tion 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.
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 sec-
tion.
Safe
Safe is an attribute of code that can be called from a multi-
threaded 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 exam-
ple, 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 pro-
tected. 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 mon-
itor makes the library Safe, but it supports no concurrency so it
is not considered MT-Safe. An MT-Safe library must permit a reason-
able 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 sig-
nals 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 perform-
ing 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 opera-
tions when another thread calls forkall(), they will continue per-
forming the same I/O operations in both the parent and child pro-
cesses, possibly causing data corruption. For this and other race-
condition reasons, the use of forkall() is discouraged.
In all Solaris releases prior to Solaris 10, the behavior of fork()
depended on whether or not the application was linked with
-lpthread (POSIX threads, see standards(5)). If linked with
-lpthread, fork() behaved like fork1(); otherwise it behaved like
forkall(). To avoid any confusion concerning the behavior of
fork(), applications can specifically call fork1() or forkall() as
appropriate.
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 mem-
ory. 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_can-
cel(3C) should ensure that they operate in a Cancel-Safe environ-
ment. Libraries that have cancellation points and which acquire
resources such as locks or allocate memory dynamically, also con-
tribute 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 Asyn-
chronous-Cancel-Safety. An application is considered to be
Deferred-Cancel-Safe when it is Cancel-Safe for threads whose can-
cellation type is PTHREAD_CANCEL_DEFERRED. An application is con-
sidered 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-Can-
cel-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 applica-
tion which is Asynchronous-Cancel-Safe is also, by definition,
Deferred-Cancel-Safe.
SEE ALSO
uname(1), pkgadd(1M), Intro(3), standards(5)
SunOS 5.10 19 Dec 2003 attributes(5)
|
