attributes
Standards, Environments, and Macros attributes(5)NAME
attributes, architecture, availability, CSI, stability, MT- Level - characteristics of commands, utilities, and device driversDESCRIPTION
The ATTRIBUTES man page section 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: + File code is a superset of ASCII. SunOS 5.8 Last change: 3 June 1997 1 Standards, Environments, and Macros attributes(5) + In order to support multi-byte characters and NULL- terminated UNIX file names, the NULL and / (slash) characters cannot be part of any multi-byte charac- ters. + 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. + Process code (wchar_t values) is implementation depen- dent and can change over time or between implementa- tions or between locales. + 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: + 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 characters: + 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 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.8 Last change: 3 June 1997 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 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 SunOS 5.8 Last change: 3 June 1997 3 Standards, Environments, and Macros attributes(5) Major x.0 Likely to contain major feature addi- tions; 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. Minor x.y Compared to an x.0 or earlier release (y!=0), it's likely to contain: minor feature additions, compatible Standard and Stable interfaces, possibly incompa- tible Evolving interfaces, or likely incompatible Unstable interfaces. Micro x.y.z Intended to be interface compatible with the previous release (z!=0), but likely to add bug fixes, performance enhance- ments, and support for additional 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: incompati- bilities 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 command or function complies with the standard listed. Most of these interfaces are defined by a formal standard, and controlled by a standards organization. Changes will usually be made in accor- dance with approved changes to that standard. his sta- bility level can also apply to interfaces that have been adopted (without a formal standard) by an "industry convention." SunOS 5.8 Last change: 3 June 1997 4 Standards, Environments, and Macros attributes(5) Support is provided for only the specified version(s) of a standard; support of later versions is not guaranteed. If the standards organization approves a non-upwards-compatible change to a Standard interface that Sun decides to support, we will announce a compa- tibility and migration strategy. 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 effected release, and when feasible, Sun will provide migration aids for binary compatibility and continued source development. 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 SunOS 5.8 Last change: 3 June 1997 5 Standards, Environments, and Macros attributes(5) 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 SunOS 5.8 Last change: 3 June 1997 6 Standards, Environments, and Macros attributes(5) 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 SunOS 5.8 Last change: 3 June 1997 7 Standards, Environments, and Macros attributes(5) 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(3THR)). 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 SunOS 5.8 Last change: 3 June 1997 8 Standards, Environments, and Macros attributes(5) 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) SunOS 5.8 Last change: 3 June 1997 9