Unix/Linux Go Back    


OpenSolaris 2009.06 - man page for attributes (opensolaris section 5)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 example 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 peripherals.

   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 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  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.

       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 sup-
		  port for C and POSIX locales.

   Interface Stability
       Sun often provides developers with early access to new technologies, which allows develop-
       ers  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 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 implementation 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 undocumented 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  applica-
	   tions 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 Com-
	   mitted  interfaces.	In this case, the controlling body and/or public, versioned docu-
	   ment is typically noted in a "Standard" entry in the Attributes table or elsewhere  in
	   the documentation.

	   Although  a	truly exceptional event, incompatible changes are possible in any release
	   if the associated defect is serious enough as outlined in the  Exceptions  section  of
	   this  document  or in a Minor release by following the End of Feature process. If sup-
	   port of a Committed interface must be discontinued, Sun will attempt to provide  noti-
	   fication 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 expecta-
	   tion 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 technol-
		      ogy, 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 compatibility with previous
		      releases until the next Minor release at which time Sun expects to synchro-
		      nize with the external specification.

	       3.     Interfaces whose target audience values innovation (and  possibly  ease  of
		      use)  over  stability.  This attribute is often associated with administra-
		      tive interfaces for higher tier components.
	   For Uncommitted interfaces, Sun makes no claims about either source or binary compati-
	   bility from one minor release to another. Applications developed based on these inter-
	   faces 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 addi-
	   tional stability to the interface, as it may better meet the expectations of the  con-
	   sumer.

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

	   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 specification 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 interface might still be visible to or acces-
	   sible  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.

       Obsolete

	   Obsolete  is  a  modifier that can appear in conjunction with the above classification
	   levels. The Obsolete modifier indicates an interface 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 discontin-
	   ued, 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 following list contains  the  common,  known
       reasons	for the interface provider to violate an interface stability commitment, but does
       not preclude 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  consumers  expect  the  newer
		  interface.

	   5.	  Not  making the incompatible change would be incomprehensible to our customers.
		  One example of this would to have not incompatibly 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 consequences of the vulnerabilities or  con-
       tractual 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 mapping between the old and  new  classifica-
       tion 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  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 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  concurrency.	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 concur-
	   rency. (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 any-
	   thing 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 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.

	   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 stan-
	   dards(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 cancel-
	   lation  cleanup  handlers  to  release  the	resources appropriately (see pthread_can-
	   cel(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 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  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 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 definition, 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 document 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)
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 08:13 AM.