attributes(5)						Standards, Environments, and Macros					     attributes(5)

NAME

       attributes, architecture, availability, CSI, stability, MT-Level, standard - 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 exam-
       ple of an attributes table. Not all attribute types are appropriate for all types of interfaces.

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Architecture		     |SPARC			   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+
       |Standard		     |See standards(5). 	   |
       +-----------------------------+-----------------------------+

   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 component being described on the man page. To be able to use the com-
       mand, 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 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 charac-
       ter sets.

       For practical reasons, however, 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, 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 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 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 technologies, 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 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 applications, because Sun will endeavor to ensure that these continue 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 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 implemen-
       tation  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 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   incompatible  standard
				   revisions; and  though  unlikely,
				   could  change,  drop,  or replace
				   Committed   interfaces.   Initial
				   product releases are usually 1.0.
       --------------------------------------------------------------

       Minor	     x.y	   Compared  to  an  x.0  or earlier
				   release (y!=0), it is  likely  to
				   contain:  feature additions, com-
				   patible  changes   to   Committed
				   interfaces,	or likely incompati-
				   ble	changes  to  Uncommitted  or
				   Volatile interfaces.
       --------------------------------------------------------------
       Micro	     x.y.z	   Intended to be interface compati-
				   ble	with  the  previous  release
				   (z!=0),  but  likely  to  add bug
				   fixes, performance  enhancements,
				   and	support for additional hard-
				   ware.  Incompatible	changes   to
				   Volatile interfaces are possible.

       In  the	context  of  interface	stability, update releases (occasionally referred to as patch releases) should be considered equivalent to
       Micro Releases.

   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.

	Stability	Release 		  Comments
       -----------------------------------------------------------------
       Committed     Major (x.0)     Incompatibilities are exceptional.
       -----------------------------------------------------------------
       Uncommitted   Minor (x.y)     Incompatibilities are common.
       -----------------------------------------------------------------
       Volatile      Micro (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 exception 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 Solaris product should not be construed to imply any
       level of stability for interfaces provided by the Solaris product. The only source of stability level information is Solaris 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  controlling
	   body  and/or public, versioned document is typically noted in a "Standard" entry in the Attributes table or elsewhere in the documenta-
	   tion.

	   Although a truly exceptional event, incompatible changes are possible in any release if the associated defect is serious enough as out-
	   lined in the Exceptions section of this document or in a Minor release by following the End of Feature process. If support of a Commit-
	   ted interface must be discontinued, Sun 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 provide an interim solution to a problem where a more general solution is anticipated.

	       2.     Interfaces whose specification is controlled by an outside body yet Sun expects to make a reasonable effort to maintain com-
		      patibility with previous releases until the next Minor release at which time Sun 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 asso-
		      ciated with administrative interfaces for higher tier components.
	   For Uncommitted interfaces, Sun makes 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.

       Volatile

	   Volatile interfaces can change at any time and for any reason.

	   The	Volatile  interface  stability	level allows Sun products 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 consumer.

	   The most common application of this taxonomy level is to interfaces that are controlled by a body other than Sun, but unlike specifica-
	   tions controlled by standards bodies or Free or Open Source Software (FOSS) communities which value interface compatibility, it can not
	   be asserted that an incompatible change to the interface specification would be exceedingly rare. It may also be applied to	FOSS  con-
	   trolled  software  where  it is deemed more important to track the community with minimal latency than to provide stability to our cus-
	   tomers.

	   It also common to apply the Volatile classification level to interfaces 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 speci-
	   fication under development.

	   Volatile can also be applied to experimental interfaces.

	   No assertion is made regarding either source or binary compatibility  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.   Failure
	   to  apply  this term to an entity is not an indication that the entity is some form of interface.  It only indicates that the potential
	   for confusion was not identified.

       Private

	   A Private interface is an interface provided by a component (or product) intended only for the use of that component. A Private  inter-
	   face  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  inter-
	   faces.

	   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  stabil-
	   ity 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 inter-
	   face 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 Obsolete 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, Sun will attempt to provide notification before discontinuing support. Use of an Obsolete interface
	   may produce warning messages.

   Exceptions
       There are rare instances when it is in the best interest of both Sun and the customer to break the interface stability commitment. The fol-
       lowing  list  contains the common, known reasons for the interface provider to violate an interface stability commitment, but does not pre-
       clude 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 Sun has been changed incompatibly and the vast majority of  interface  con-
		  sumers expect the newer interface.

	   5.	  Not making the incompatible change would be incomprehensible to our customers.  One example of this would to have not incompati-
		  bly changed pcfs when the DOS 8.3 naming restrictions were abandoned.

       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 classification scheme was used. The following table summarizes the map-
       ping between the old and new classification schemes.

	   Old		 New			 Comments
       ------------------------------------------------------------------
       Standard      Committed	   An entry in the attributes table  for
				   the	Standard  attribute  type should
				   appear.
       Stable	     Committed	   Name change.
       Evolving      Uncommitted   Actual commitments match.
       Unstable      Uncommitted   Name change.
       External      Volatile	   Name change with expansion of allowed
				   usage.
       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
       conflicted 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 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 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 example, a multithreaded applica-
	   tion 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 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  func-
	   tions 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 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 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	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 performing 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 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(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  appro-
	   priate.

       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  can-
	   celled,  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 cancellation 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  Can-
	   cel-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 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 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.

   Standard
       Many interfaces are defined and controlled as industry standards. When this is the case, the controlling body and/or public, versioned doc-
       ument is noted in this section.

       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 interfaces based upon a public standard. 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.

       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 ANSII, 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), pkgadd(1M), Intro(3), standards(5)

SunOS 5.11							    29 Jul 2007 						     attributes(5)