|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
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.
____________________________________________________________
| 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,
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.
SunOS 5.10 Last change: 19 Dec 2003 1
Standards, Environments, and Macros attributes(5)
o To support multi-byte characters and null-terminated
UNIX file names, the NULL and / (slash) characters can-
not 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 can have names composed of arbitrary
characters. 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
SunOS 5.10 Last change: 19 Dec 2003 2
Standards, Environments, and Macros attributes(5)
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 bind-
ing 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 reli-
ably 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
SunOS 5.10 Last change: 19 Dec 2003 3
Standards, Environments, and Macros attributes(5)
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.
SunOS 5.10 Last change: 19 Dec 2003 4
Standards, Environments, and Macros attributes(5)
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 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 Private classifica-
tion. 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 undocu-
mented interface 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 stabil-
ity 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 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 organi-
zation. 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.
SunOS 5.10 Last change: 19 Dec 2003 5
Standards, Environments, and Macros attributes(5)
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 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 interfaces, especially in minor or
micro releases.
If support of a Stable interface must be discontinued,
Sun will attempt to provide notification and the stabil-
ity 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 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 con-
tinued 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 availability
from the controlling entity. This classification is typ-
ically applied to publicly available "freeware" and
similar objects.
SunOS 5.10 Last change: 19 Dec 2003 6
Standards, Environments, and Macros attributes(5)
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 con-
tain 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. 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 notification
before discontinuing support. Use of an Obsolete inter-
face may produce warning messages.
Private
A Private interface is an interface provided by a com-
ponent (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.
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.
SunOS 5.10 Last change: 19 Dec 2003 7
Standards, Environments, and Macros attributes(5)
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 section.
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 process. A mul-
tithreaded 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 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 exe-
cute 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 con-
currency. A library can be safe to use, but not MT-Safe.
For example, surrounding an entire library with a moni-
tor makes the library Safe, but it supports no con-
currency 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
SunOS 5.10 Last change: 19 Dec 2003 8
Standards, Environments, and Macros attributes(5)
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 sig-
nal. 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 signals 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.
SunOS 5.10 Last change: 19 Dec 2003 9
Standards, Environments, and Macros attributes(5)
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 performing 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 operations when
another thread calls forkall(), they will continue per-
forming 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 for-
kall() is discouraged.
In all Solaris releases prior to Solaris 10, the
behavior of fork() depended on whether or not the appli-
cation 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 memory. 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_cancel(3C) should ensure that they operate in a
Cancel-Safe environment. Libraries that have cancella-
tion 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.
SunOS 5.10 Last change: 19 Dec 2003 10
Standards, Environments, and Macros attributes(5)
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 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-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 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 defini-
tion, Deferred-Cancel-Safe.
SEE ALSO
uname(1), pkgadd(1M), Intro(3), standards(5)
SunOS 5.10 Last change: 19 Dec 2003 11
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Wed Sep 12 11:27:39 GMT 2007
|
Your favourite pages:
No pages logged yet... Top 10 most popular pages:
svn man page (22049 hits)
(FreeBSD 6.2)
netcat man page (8898 hits)
(Suse Linux 10.1)
prstat man page (7960 hits)
(Solaris 10 11_06)
ssh-socks5-proxy-connect man page (7907 hits)
(Solaris 10 11_06)
sqlite3 man page (7640 hits)
(openSUSE 10.2)
signal man page (7128 hits)
(Suse Linux 10.1)
adv_cap_autoneg man page (6826 hits)
(Solaris 10 11_06)
startproc man page (6483 hits)
(Suse Linux 10.1)
CPAN man page (6457 hits)
(Suse Linux 10.1)
ssh man page (5476 hits)
(Suse Linux 10.1)
|
Man Pages 
