architecture(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.
____________________________________________________________
| 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 peripherals.
Availability
This refers to the software package which contains the com-
mand or component 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 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
in Solaris, 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.
However, for practical reasons, 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, desig-
nation, invocation, and so forth, although single
shift is not excluded.
o Process code (wchar_t values) is implementation depen-
dent and can change over time or between implementa-
tions or between locales.
o Not every object in Solaris 2 and Solaris 7can 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 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 tech-
nologies, 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 sta-
bility 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 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 proto-
typing, 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 inter-
faces are not only subject to incompatible change or remo-
val, 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 incompa-
tible 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, compa-
tible Standard and
Stable interfaces,
possibly incompa-
tible 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 classif-
ications 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 classifi-
cations, 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 oth-
erwise stated. The stability 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 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 standards(5) for a complete
list of these standards.
Most of these interfaces are defined by a formal stan-
dard, and controlled by a standards development organ-
ization. Changes will usually 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 standard; support for later versions is not
guaranteed. If the standards 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 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 defin-
ition 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 interfaces, 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 compatibil-
ity 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 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 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 ver-
sions of such interfaces, subject to their availabil-
ity 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. Applications 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 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.
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 notifica-
tion before discontinuing support. Use of an Obsolete
interface may produce warning messages.
MT-Level
Libraries are classified into four categories which define
their ability to support multiple threads. Manual pages con-
taining 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
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 pro-
cess. A multi-threaded application has the responsi-
bility for using these interfaces in a safe manner,
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 con-
tain 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 con-
currency. 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 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 clari-
fies the Safe definition, which can mean anything from
being single threaded to being any degree of mul-
tithreaded.)
Async-Signal-Safe
Async-Signal-Safe refers to particular library rou-
tines that can be safely called from a signal handler.
A thread that is executing an Async-Signal-Safe rou-
tine will not deadlock with itself if interrupted by a
signal. Signals are only a problem for MT-Safe rou-
tines 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 functions
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 pro-
gram, 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 lib-
thread are Fork1-Safe. Otherwise, you should handle
the locking clean-up yourself (see
pthread_atfork(3C)).
Cancel-Safety
If a multi-threaded application uses
pthread_cancel(3THR) 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(3THR)), the application is "cancel-
unsafe", that is, it is not safe with respect to can-
cellation. 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 can-
cellation 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 multi-threaded program:
Cancel-Safety. There are two sub-categories of
Cancel-Safety: Deferred-Cancel-Safety, and
Asynchronous-Cancel-Safety. An application is con-
sidered 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 may never be necessary to worry about asyn-
chronous 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 definition, Deferred-Cancel-
Safe.
SEE ALSO
uname(1), pkgadd(1M), Intro(3), standards(5)
Man(1) output converted with
man2html