svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
attributes(7)
Standards, Environments, Macros, Character Sets, and miscellany
attributes(7)
NAME
attributes, architecture, availability, CSI, stability, MT-Level, stan‐
dard - attributes of interfaces
DESCRIPTION
The ATTRIBUTES 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.
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ ArchitectureSPARC _ Availabilitysystem/kernel _ CSIEn‐
abled _ Interface StabilityCommitted _ MT-LevelSafe _ StandardSee stan‐
dards(7).
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.
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 com‐
mands 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. Cer‐
tain assumptions are still applied to the current CSI implementation:
o File code is a superset of ASCII.
o To support multibyte characters and null-terminated UNIX
file names, the NULL and / (slash) characters cannot be part
of any multibyte characters.
o Only "stateless" file code encodings are supported. State‐
less 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 char‐
acters. 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 com‐
mands and utilities that are CSI enabled, all can handle
single-byte and multibyte 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
Oracle Solaris often provides developers with early access to new tech‐
nologies, which allows developers to evaluate with them as soon as pos‐
sible. Unfortunately, new technologies are prone to changes and stan‐
dardization 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 Oracle Solaris will endeavor to ensure that these con‐
tinue 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 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 Oracle Solaris 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 compatibil‐
ity discussions. Each release level may also include changes suitable
for lower levels.
tab(); lw(1i)lw(1i) lw(3.5i) lw(1i)lw(1i) lw(3.5i) 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 Committed interfaces.
Initial product releases are usually 1.0. T} _ Minorx.yT{ Compared to
an x.0 or earlier release (y!=0), it is likely to contain: feature
additions, compatible changes to Committed interfaces, or incompatible
changes to Uncommitted or Volatile interfaces. Interfaces previously
declared Obsolete may be removed via the End of Feature process. T} _
Microx.y.zT{ 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}
For example, compared to Oracle Solaris 10, the Oracle Solaris 11.0
release was a major release due to the switch from the SVR4 packaging
format to the Image Packaging System (IPS), even though binary compati‐
bility was maintained for applications which called only Committed
interfaces in the Oracle Solaris ABI.
Oracle Solaris 11.2 was a minor release, despite adding significant
features such as Kernel Zones and Unified Archives, since it did not
have such incompatible changes when compared to the Oracle Solaris 11.0
or 11.1 releases.
Release levels of software included with Oracle Solaris may not always
reflect the release level of Oracle Solaris itself. For instance, a
Micro release of Oracle Solaris (such as a Support Repository Update)
may include a Major release of a bundled software package, such as the
Oracle Java Runtime Environment or a FOSS language interpreter.
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.
tab(); lw(1i)lw(1i) lw(3.5i) lw(1i)lw(1i) lw(3.5i) StabilityReleaseC‐
omments _ CommittedMajor (x.0)Incompatibilities are exceptional. _
UncommittedMinor (x.y)Incompatibilities are possible. _ VolatileMicro
(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 excep‐
tion 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 undocu‐
mented interface is implicitly Private.
The existence of documentation other than the documentation that is a
component of the Oracle Solaris product should not be construed to
imply any level of stability for interfaces provided by the Oracle
Solaris product. The only source of stability level information is the
reference 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 control‐
ling body and/or public, versioned document is typically noted in a
"Standard" entry in the Attributes table or elsewhere in the docu‐
mentation.
Although a truly exceptional event, incompatible changes are possi‐
ble 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, Oracle Solaris 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
subcategorizes:
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 pro‐
vide an interim solution to a problem where a more gen‐
eral solution is anticipated.
2. Interfaces whose specification is controlled by an out‐
side body yet Oracle Solaris expects to make a reason‐
able effort to maintain compatibility with previous
releases until the next Minor release at which time Ora‐
cle Solaris 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, Oracle Solaris 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 Oracle Solaris prod‐
ucts 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 con‐
sumer.
The most common application of this taxonomy level is to interfaces
that are controlled by a body other than Oracle Solaris, but unlike
specifications controlled by standards bodies or Free or Open
Source Software (FOSS) communities which value interface compati‐
bility, 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 impor‐
tant to track the community with minimal latency than to provide
stability to our customers.
It also common to apply the Volatile classification level to inter‐
faces 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 specifi‐
cation under development.
Volatile can also be applied to experimental interfaces.
No assertion is made regarding either source or binary compatibil‐
ity 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. Fail‐
ure to apply this term to an entity is not an indication that the
entity is some form of interface. It only indicates that the poten‐
tial for confusion was not identified.
Private
A Private interface is 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. Compo‐
nents not supplied by Oracle Solaris should not use Private inter‐
faces.
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.
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 Obso‐
lete 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, Oracle Solaris will attempt
to provide notification before discontinuing support. Use of an
Obsolete interface may produce warning messages.
Pass-through
Pass-through is a modifier that can appear in conjunction with the
above classification levels. The Pass-through modifier indicates an
interface whose specification is controlled by any body outside of
Oracle Solaris (typically a Free/Open Source Software community)
and "passed through" with minimal modification (typically only what
is needed to make the component work well on Oracle Solaris).
The risk of using Pass-through interfaces in release-independent
products will vary based on where the outside body that governs
each such interface falls on the spectrum of stability (low, slow
change) versus flexibility (high, fast change). Oracle will not
commit to insulating any consumers of these interfaces from incom‐
patibilities introduced by those outside bodies. In particular,
when outside bodies drop support for a given version of their com‐
ponents, Oracle Solaris will generally follow suit and drop support
for that version shortly thereafter, generally in favor of a later
version. Note that "drop support" may mean removal, even in a Micro
release. For how to freeze a component to allow its continued use
in an unsupported fashion, see pkg(1) man page.
Exceptions
There are rare instances when it is in the best interest of both Oracle
Solaris 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 Oracle
Solaris 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 restric‐
tions were abandoned.
6. An outside body drops support for a particular version of a
Pass-through component. One example of this is when the
Python community dropped support for version 2.6 in favor of
versions 2.7 and 3.x.
Incompatible changes allowed by exception will always be delivered in
the "most major" release vehicle possible. However, often the conse‐
quences 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 clas‐
sification scheme was used. The following table summarizes the mapping
between the old and new classification schemes.
tab(); lw(1i)lw(1i) lw(3.5i) lw(1i)lw(1i) lw(3.5i) OldNewComments _
StandardCommittedT{ An entry in the attributes table for the Standard
attribute type should appear. T} StableCommittedName change. Evolvin‐
gUncommittedActual commitments match. UnstableUncommittedName change.
ExternalVolatileT{ Name change with expansion of allowed usage. T}
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 con‐
flicted 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 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 sup‐
ports 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(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 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.
Standard
Many interfaces are defined and controlled as industry standards. When
this is the case, the controlling body and/or public, versioned docu‐
ment is noted in this section.
Programmers producing portable applications should rely on the inter‐
face 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 stan‐
dard or specification allows alternative implementation choices, the
manual page usually only describes the alternative implemented by Ora‐
cle Solaris. The manual page also describes any compatible extensions
to the base definition of Standard interfaces provided by Oracle
Solaris.
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 ANSI, 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).
SEE ALSO
uname(1), intro(3), standards(7)
End of Feature Notices for Oracle Solaris 11
https://www.oracle.com/solaris/technologies/end-of-feature-notices-
solaris11.html
Oracle Solaris 11.4 11 May 2021 attributes(7)