attributes(5) Standards, Environments, and Macros attributes(5)
attributes, architecture, availability, CSI, stability, MT-Level -
attributes of interfaces
The ATTRIBUTES section of a manual page contains a table (see below)
defining attribute types and their corresponding values.
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Architecture |SPARC |
+-----------------------------+-----------------------------+
|Availability |SUNWcsu |
+-----------------------------+-----------------------------+
|CSI |Enabled |
+-----------------------------+-----------------------------+
|Interface Stability |Unstable |
+-----------------------------+-----------------------------+
|MT-Level |Safe |
+-----------------------------+-----------------------------+
Architecture
Architecture defines processor or specific hardware. (See -p option of
uname(1)). In some cases, it may indicate required adapters or periph‐
erals.
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 in Solaris, for example, that work only
with Extended Unix Codesets (EUC), an encoding method that allows con‐
current support for up to four code sets and is commonly used to rep‐
resent Asian character sets.
However, for practical reasons, this independence is not absolute. Cer‐
tain assumptions are still applied to the current CSI implementation:
· File code is a superset of ASCII.
· To support multi-byte characters and null-terminated UNIX file
names, the NULL and / (slash) characters cannot be part of any
multi-byte characters.
· Only "stateless" file code encodings are supported. Stateless
encoding avoids shift, locking shift, designation, invocation,
and so forth, although single shift is not excluded.
· Process code (wchar_t values) is implementation dependent and can
change over time or between implementations or between locales.
· Not every object in Solaris 2 and Solaris 7can have names com‐
posed of arbitrary characters. The names of the following objects
must be composed of ASCII characters:
· User names, group name, and passwords
· System name
· Names of printers and special devices
· Names of terminals (/dev/tty*)
· Process ID numbers
· Message queues, semaphores, and shared memory labels.
· The following may be composed of ISO Latin-1 or EUC charac‐
ters:
· File names
· Directory names
· Command names
· Shell variables and environmental variable names
· Mount points for file systems
· NIS key names and domain names
· 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
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 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.
Release Version Significance
Major x.0 Likely to contain
major feature
additions; adhere
to different,
possibly incompat‐
ible Standard
revisions; and
though unlikely,
could change,
drop, or replace
Standard or Stable
interfaces. Ini‐
tial product
releases are usu‐
ally 1.0.
Minor x.y Compared to an x.0
or earlier release
(y!=0), it’s
likely to contain:
minor feature
additions, compat‐
ible Standard and
Stable interfaces,
possibly incompat‐
ible Evolving
interfaces, or
likely incompati‐
ble Unstable
interfaces.
Micro x.y.z Intended to be
interface compati‐
ble with the pre‐
vious release
(z!=0), but likely
to add bug fixes,
performance
enhancements, and
support for addi‐
tional hardware.
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.
Stability Release Comments
Standard Major (x.0) Actual or de facto.
Stable Major (x.0) Incompatibilities are exceptional.
Evolving Minor (x.y) Migration advice might accompany
an incompatibility.
Unstable Minor (x.y) Experimental or transitional:
incompatibilities are common.
External Micro (x.y.z) Not controlled by Sun:
intrarelease incompatibilities are
common.
Obsolete Minor (x.y) Deprecated interface: likely to be
removed in a future minor release.
The interface stability levels described in this manual page apply to
both source and binary interfaces unless otherwise stated. The sta‐
bility level of each interface is unknown unless explicitly stated.
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
standards. This is usually the hierarchy built up from the C Lan‐
guage (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 standards(5) for a complete list of these standards.
Most of these interfaces are defined by a formal standard, and
controlled by a standards development organization. Changes will
usually be made in accordance with approved changes to that stan‐
dard. This stability level can also apply to interfaces that have
been adopted (without a formal standard) by an "industry conven‐
tion."
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
manual page descriptions of Standard interfaces. When the stan‐
dard or specification allows alternative implementation choices,
the manual page usually only describes the alternative imple‐
mented 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
previous 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 when‐
ever possible. If such a change is necessary, it will be docu‐
mented in the release notes for the affected release, and when
feasible, Sun will provide migration aids for binary compatibil‐
ity and continued source development.
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 "free‐
ware" 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 antici‐
pated in the future.
For Unstable interfaces, Sun 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 sup‐
port 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.
MT-Level
Libraries are classified into four categories which define their abil‐
ity to support multiple threads. Manual pages containing routines that
are of multiple or differing levels show this within their NOTES or
USAGEsection.
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 multi-threaded application
has the responsibility for using these interfaces in a safe man‐
ner, which is different from whether or not the interface is
Safe. For example, a multi-threaded 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 may contain routines that are Safe; however, most of
the library’s routines are unsafe to call.
The following table contains reentrant counterparts for Unsafe
functions. This table is subject to change by Sun.
Reentrant functions for libc:
Unsafe Function Reentrant counterpart
ctime ctime_r
localtime localtime_r
asctime asctime_r
gmtime gmtime_r
ctermid ctermid_r
getlogin getlogin_r
rand rand_r
readdir readdir_r
strtok strtok_r
tmpnam tmpnam_r
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. Note that 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 defini‐
tion’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 sup‐
ports 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 routines that can
be safely called from a signal handler. A thread that is execut‐
ing an Async-Signal-Safe routine will not deadlock with itself if
interrupted by a signal. Signals are only a problem for MT-Safe
routines that acquire locks.
Signals are disabled when locks are acquired in Async-Signal-Safe
routines. This prevents a signal handler that might acquire the
same lock from being called. The list of Async-Signal-Safe func‐
tions includes:
_exit access aio_error
aio_return aio_suspend alarm
cfgetispeed cfgetospeed cfsetispeed
cfsetospeed chdir chmod
chown clock_gettime close
creat dup dup2
execle execve fcntl
fdatasync fork fstat
fsync getegid geteuid
getgid getgroups getpgrp
getpid getppid getuid
kill link lseek
mkdir mkfifo open
pathconf pause pipe
read rename rmdir
sem_post sema_post setgid
setpgid setsid setuid
sigaction sigaddset sigdelset
sigemptyset sigfillset sigismember
sigpending sigprocmask sigqueue
sigsuspend sleep stat
sysconf tcdrain tcflow
tcflush tcgetattr tcgetpgrp
tcsendbreak tcsetattr tcsetpgrp
thr_kill thr_sigsetmask time
timer_getoverrun timer_gettime timer_settime
times umask uname
unlink utime wait
waitpid write
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.
Fork1-Safe
A Fork1-Safe library releases the locks it had held whenever
fork1(2) is called in a Solaris thread program, or fork(2) in a
POSIX (see standards(5)) thread program. Calling fork(2) in a
POSIX thread program has the same semantic as calling fork1(2) in
a Solaris thread program. All system calls, libpthread, and
libthread are Fork1-Safe. Otherwise, you should handle the lock‐
ing clean-up yourself (see pthread_atfork(3THR)).
Cancel-Safety
If a multi-threaded application uses pthread_cancel(3THR) to can‐
cel (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 appropri‐
ately (see pthread_cancel(3THR)), 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(3THR) should ensure that they operate in
a Cancel-Safe environment. Libraries that have cancellation
points and which acquire resources such as locks or allocate mem‐
ory dynamically, also contribute to the cancel-unsafety of appli‐
cations that are linked with these libraries. This introduces
another level of safety for libraries in a multi-threaded pro‐
gram: 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 Asyn‐
chronous-Cancel-Safe when it is Cancel-Safe for threads whose
cancellation type is PTHREAD_CANCEL_ASYNCHRONOUS. Deferred-Can‐
cel-Safety is easier to achieve than Asynchronous-Cancel-Safety,
since a thread with the deferred cancellation type can be can‐
celled only at well-defined cancellation points, whereas a thread
with the asynchronous cancellation type can be cancelled any‐
where. Since all threads are created by default to have the
deferred cancellation type, it may never be necessary to worry
about asynchronous cancel safety. Indeed, most applications and
libraries are expected to always be Asynchronous-Cancel-Unsafe.
An application which is Asynchronous-Cancel-Safe is also, by def‐
inition, Deferred-Cancel-Safe.
uname(1), pkgadd(1M), Intro(3), standards(5)
SunOS 5.9 15 Aug 2001 attributes(5)