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 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 free of dependencies on the  pro-
     perties  of any code sets are said to have Code Set Indepen-
     dence (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.

SunOS 5.11          Last change: 29 Jul 2007                    1


Standards, Environments, and Macros                 attributes(5)

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

         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  arbi-
              trary   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

SunOS 5.11          Last change: 29 Jul 2007                    2


Standards, Environments, and Macros                 attributes(5)

                 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  interna-
              tionalization  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 com-
     mands, 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  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.

SunOS 5.11          Last change: 29 Jul 2007                    3


Standards, Environments, and Macros                 attributes(5)

  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
                                 hardware. Incompatible changes to
                                 Volatile interfaces are possible.

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

  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  Incompatible  Changes, and the third column lists other
     comments. For a complete discussion of individual  classifi-
     cations, see the appropriate subsection below.

      Stability       Release                   Comments
     ________________________________________________________________
     Committed     Major (x.0)     Incompatibilities are exceptional.

SunOS 5.11          Last change: 29 Jul 2007                    4


Standards, Environments, and Macros                 attributes(5)

     ________________________________________________________________
     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 classifica-
     tion. 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 stabil-
     ity level information is Solaris manual pages.

     Committed

         The intention of a  Committed  interface  is  to  enable
         third  parties  to  develop applications to these inter-
         faces, 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 jus-
         tifications.

         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 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 support of a Committed  interface
         must be discontinued, Sun will attempt to provide notif-
         ication and the stability level will be marked Obsolete.

     Uncommitted

         No commitment is made  about  either  source  or  binary

SunOS 5.11          Last change: 29 Jul 2007                    5


Standards, Environments, and Macros                 attributes(5)

         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  expec-
         tation  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 miti-
         gation plan.

         Uncommitted interfaces generally fall into  one  of  the
         following subcategorizes:

             1.   Interfaces that  are  experimental  or  transi-
                  tional. 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 rea-
                  sonable effort to maintain  compatibility  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 innova-
                  tion (and possibly ease of use) over stability.
                  This attribute is often associated with  admin-
                  istrative   interfaces  for  higher  tier  com-
                  ponents.
         For Uncommitted 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.

     Volatile

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

         The Volatile interface stability level allows  Sun  pro-
         ducts to quickly track a fluid, rapidly evolving specif-
         ication. In many cases, this is preferred  to  providing
         additional  stability to the interface, as it may better
         meet the expectations of the consumer.

SunOS 5.11          Last change: 29 Jul 2007                    6


Standards, Environments, and Macros                 attributes(5)

         The most common application of this taxonomy level is to
         interfaces that are controlled by a body other than Sun,
         but unlike specifications 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 specifica-
         tion 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 identi-
         fied 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 con-
         fusion was not identified.

     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

SunOS 5.11          Last change: 29 Jul 2007                    7


Standards, Environments, and Macros                 attributes(5)

         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
         discontinued,  Sun  will attempt to provide notification
         before discontinuing support. Use of an Obsolete  inter-
         face 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.

SunOS 5.11          Last change: 29 Jul 2007                    8


Standards, Environments, and Macros                 attributes(5)

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

     Incompatible changes allowed by  exception  will  always  be
     delivered  in  the  "most  major"  release vehicle possible.
     However, often the consequences 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 mapping between the old and  new  clas-
     sification 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  diffi-
     culty 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.

SunOS 5.11          Last change: 29 Jul 2007                    9


Standards, Environments, and Macros                 attributes(5)

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

SunOS 5.11          Last change: 29 Jul 2007                   10


Standards, Environments, and Macros                 attributes(5)

     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.

         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

SunOS 5.11          Last change: 29 Jul 2007                   11


Standards, Environments, and Macros                 attributes(5)

         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 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.   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 cancella-
         tion  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 asyn-
         chronous cancel safety. Most applications and  libraries

SunOS 5.11          Last change: 29 Jul 2007                   12


Standards, Environments, and Macros                 attributes(5)

         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 stan-
     dards.  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  con-
     form, rather than the manual page descriptions of interfaces
     based upon a public standard. When the standard or  specifi-
     cation allows alternative implementation choices, the manual
     page usually only describes the alternative  implemented  by
     Sun.  The  manual  page also describes any compatible exten-
     sions to the base definition of Standard interfaces provided
     by Sun.

     No endorsement of the referenced controlling body  or  docu-
     ment  should  be  inferred  by  its presence as a "Standard"
     entry. The controlling body may be a very  formal  organiza-
     tion,  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          Last change: 29 Jul 2007                   13


Man(1) output converted with man2html


FhG Schily's Home VED powered