attributes(5) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨페이지이름
검색(S)

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.



     tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i)  ATTRI-
     BUTE    TYPEATTRIBUTE    VALUE    _    ArchitectureSPARC   _
     Availabilitysystem/kernel   _   CSIEnabled    _    Interface
     StabilityCommitted   _   MT-LevelSafe  _  StandardSee  stan-
     dards(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
     pkg(1).

  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.


     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

                 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
     Oracle Solaris often provides developers with  early  access
     to  new  technologies,  which  allows developers to evaluate
     with them as soon as possible. Unfortunately, new  technolo-
     gies  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 Oracle Solaris will endeavor to ensure
     that these continue to work in future minor releases. Appli-
     cations  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 Oracle  Solaris  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.



     tab(); cw(1.1i) cw(1.1i) cw(3.3i) lw(1.1i) lw(1.1i) lw(3.3i)
     ReleaseVersionSignificance  _  Majorx.0T{  Likely to contain
     major feature  additions;  adhere  to  different,   possibly
     incompatible  standard revisions; and though unlikely, could
     change, drop, or replace Committed interfaces. Initial  pro-
     duct  releases are usually 1.0.  T} _ Minorx.yT{ Compared to
     an x.0 or earlier release (y!=0), it is likely  to  contain:
     feature  additions,  compatible  changes to Committed inter-
     faces, or likely  incompatible  changes  to  Uncommitted  or
     Volatile  interfaces.   T}  _  Microx.y.zT{  Intended  to be
     interface compatible with the previous release  (z!=0),  but
     likely  to add bug fixes, performance enhancements, and sup-
     port for additional hardware. Incompatible changes to  Vola-
     tile interfaces are possible.  T}



     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.



     tab(); cw(1.1i) cw(1.1i) cw(3.3i) lw(1.1i) lw(1.1i) lw(3.3i)
     StabilityReleaseComments           _          CommittedMajor
     (x.0)Incompatibilities are exceptional.  _  UncommittedMinor
     (x.y)Incompatibilities    are   common.    _   VolatileMicro
     (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 Oracle Solaris product should not
     be construed to imply any level of stability for  interfaces
     provided  by  the Oracle Solaris product. The only source of
     stability level information is the reference 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 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,  Oracle  Solaris will attempt to
         provide notification and the  stability  level  will  be
         marked Obsolete.


     Uncommitted
         No commitment is made about either source or binary com-
         patibility of these interfaces from one Minor release to
         the next.  Even the drastic incompatible change of remo-
         val  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 Oracle Solaris expects to
                  make   a   reasonable   effort   to    maintain
                  compatibility  with previous releases until the
                  next Minor release at which time Oracle Solaris
                  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,  Oracle  Solaris  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  Oracle
         Solaris  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 Ora-
         cle Solaris, 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 specification 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 custo-
         mers.

         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
         confusion 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 Oracle Solaris 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
         discontinued,  Oracle  Solaris  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  Oracle Solaris and the customer to break the interface
     stability commitment. The following list contains  the  com-
     mon,  known reasons for the interface provider to violate an
     interface stability commitment, but does not  preclude  oth-
     ers.

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



     tab(); cw(1.1i) cw(1.1i) cw(3.3i) lw(1.1i) lw(1.1i) lw(3.3i)
     OldNewComments  _ StandardCommittedT{ An entry in the attri-
     butes table for the Standard attribute type  should  appear.
     T}  StableCommittedName  change.   EvolvingUncommittedActual
     commitments    match.     UnstableUncommittedName    change.
     ExternalVolatileT{  Name  change  with  expansion of allowed
     usage.  T} 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.

     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 defin-
         ition 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  con-
         currency.  This clarifies the Safe definition, which can
         mean anything from being single threaded  to  being  any
         degree of multithreaded.)


     Async-Signal-Safe
         Async-Signal-Safe refers to particular library functions
         that  can  be  safely  called  from  a signal handler. A
         thread that is executing an  Async-Signal-Safe  function
         will  not  deadlock with itself if interrupted by a sig-
         nal. Signals are only a problem  for  MT-Safe  functions
         that acquire locks.

         Async-Signal-Safe functions are  also  MT-Safe.  Signals
         are  disabled  when  locks are acquired in Async-Signal-
         Safe functions. These signals prevent a  signal  handler
         that might acquire the same lock from being called.


     MT-Safe with Exceptions
         See the NOTES or USAGE sections of  these  pages  for  a
         description of the exceptions.


     Safe with Exceptions
         See the NOTES or USAGE sections of  these  pages  for  a
         description of the exceptions.


     Fork-Safe
         The fork(2) function replicates only the calling  thread
         in  the  child process. The fork1(2) function exists for
         compatibility with  the  past  and  is  synonymous  with
         fork().  If  a  thread other than the one performing the
         fork holds a lock when fork() is called, the  lock  will
         still  be held in the child process but there will be no
         lock owner since the owning thread was not replicated. A
         child  calling  a  function that attempts to acquire the
         lock will deadlock itself.

         When fork() is called, a Fork-Safe library  arranges  to
         have  all  of its internal locks held only by the thread
         performing the fork. This is usually  accomplished  with
         pthread_atfork(3C),  which is called when the library is
         initialized.

         The forkall(2) function provides the capability for  the
         rare  case  when a process needs to replicate all of its
         threads when  performing  a  fork.  No  pthread_atfork()
         actions  are  performed  when forkall() is called. There
         are dangers associated with calling forkall().  If  some
         threads  in a process are performing I/O operations when
         another thread calls forkall(), they will continue  per-
         forming  the  same I/O operations in both the parent and
         child processes, possibly causing data  corruption.  For
         this  and  other race-condition reasons, the use of for-
         kall() is discouraged.

         In  all  Solaris  releases  prior  to  Solaris  10,  the
         behavior of fork() depended on whether or not the appli-
         cation was linked with  -lpthread  (POSIX  threads,  see
         standards(5)).  If linked with -lpthread, fork() behaved
         like fork1(); otherwise it behaved  like  forkall().  To
         avoid  any  confusion concerning the behavior of fork(),
         applications can specifically call fork1() or  forkall()
         as appropriate.


     Cancel-Safety
         If a multithreaded application  uses  pthread_cancel(3C)
         to  cancel (that is, kill) a thread, it is possible that
         the target thread is killed while  holding  a  resource,
         such  as  a  lock or allocated memory. If the thread has
         not  installed  the  appropriate  cancellation   cleanup
         handlers  to  release  the  resources appropriately (see
         pthread_cancel(3C)), the application is "cancel-unsafe",
         that  is,  it  is not safe with respect to cancellation.
         This unsafety could result in deadlocks due to locks not
         released  by  a  thread that gets cancelled, or resource
         leaks; for example, memory not  being  freed  on  thread
         cancellation.      All     applications     that     use
         pthread_cancel(3C) should ensure that they operate in  a
         Cancel-Safe  environment.  Libraries that have cancella-
         tion points and which acquire resources such as locks or
         allocate  memory  dynamically,  also  contribute  to the
         cancel-unsafety of applications  that  are  linked  with
         these libraries. This introduces another level of safety
         for libraries in a multithreaded program: Cancel-Safety.
         There   are   two   sub-categories   of   Cancel-Safety:
         Deferred-Cancel-Safety, and  Asynchronous-Cancel-Safety.
         An  application is considered to be Deferred-Cancel-Safe
         when it is Cancel-Safe for  threads  whose  cancellation
         type  is PTHREAD_CANCEL_DEFERRED. An application is con-
         sidered  to  be  Asynchronous-Cancel-Safe  when  it   is
         Cancel-Safe  for  threads  whose  cancellation  type  is
         PTHREAD_CANCEL_ASYNCHRONOUS.  Deferred-Cancel-Safety  is
         easier to achieve than Asynchronous-Cancel-Safety, since
         a thread with the deferred cancellation type can be can-
         celled only at well-defined cancellation points, whereas
         a thread with the asynchronous cancellation type can  be
         cancelled  anywhere.  Since  all  threads are created by
         default to have the deferred cancellation type, it might
         never  be  necessary  to worry about asynchronous cancel
         safety. Most applications and libraries are expected  to
         always  be  Asynchronous-Cancel-Unsafe.  An  application
         which is Asynchronous-Cancel-Safe is  also,  by  defini-
         tion, Deferred-Cancel-Safe.


  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
     Oracle  Solaris. The manual page also describes any compati-
     ble extensions to the base definition of Standard interfaces
     provided by Oracle Solaris.


     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), Intro(3), standards(5)


     pkg(1)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3