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

개요

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

attributes(5)

Standards, Environments, and Macros                              attributes(5)



NAME
       attributes, architecture, availability, CSI, stability, MT-Level, stan‐
       dard - 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)  ATTRIBUTE
       TYPEATTRIBUTE VALUE _ ArchitectureSPARC _  Availabilitysystem/kernel
       _  CSIEnabled  _ Interface StabilityCommitted _ MT-LevelSafe _ Stan‐
       dardSee standards(5).


   Architecture
       Architecture defines processor or specific hardware. See -p  option  of
       uname(1). In some cases, it may indicate required adapters or peripher‐
       als.

   Availability
       This refers to the software package which contains the command or  com‐
       ponent  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 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 com‐
       mands 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. Cer‐
       tain 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.  State‐
                  less  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 char‐
                  acters. 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 com‐
                  mands  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
       Oracle Solaris often provides developers with early access to new tech‐
       nologies, which allows developers to evaluate with them as soon as pos‐
       sible. Unfortunately, new technologies are prone to changes  and  stan‐
       dardization  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 mak‐
       ing 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 applica‐
       tions, because Oracle Solaris will endeavor to ensure that  these  con‐
       tinue  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  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 compatibil‐
       ity 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  Commit‐
       ted  interfaces.  Initial  product  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 inter‐
       faces.   T}  _  Microx.y.zT{ Intended to be interface compatible 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.  T}



       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.




       tab(); cw(1.1i) cw(1.1i) cw(3.3i) lw(1.1i) lw(1.1i)  lw(3.3i)  Stabil‐
       ityReleaseComments   _  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 excep‐
       tion 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 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 justifications.

           Interfaces defined and controlled as industry  standards  are  most
           often  treated  as Committed interfaces. In this case, the control‐
           ling body and/or public, versioned document is typically noted in a
           "Standard"  entry in the Attributes table or elsewhere in the docu‐
           mentation.

           Although a truly exceptional event, incompatible changes are possi‐
           ble  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  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 pro‐
                      vide  an interim solution to a problem where a more gen‐
                      eral solution is anticipated.

               2.     Interfaces whose specification is controlled by an  out‐
                      side  body  yet Oracle Solaris expects to make a reason‐
                      able effort  to  maintain  compatibility  with  previous
                      releases until the next Minor release at which time Ora‐
                      cle Solaris 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  associated  with  administrative  interfaces  for
                      higher tier components.
           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 prod‐
           ucts 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  con‐
           sumer.

           The most common application of this taxonomy level is to interfaces
           that are controlled by a body other than Oracle Solaris, but unlike
           specifications  controlled  by  standards  bodies  or  Free or Open
           Source Software (FOSS) communities which value  interface  compati‐
           bility,  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 impor‐
           tant to track the community with minimal latency  than  to  provide
           stability to our customers.

           It also common to apply the Volatile classification level to inter‐
           faces in the process of being defined by trusted or widely accepted
           organization.   These  are  generically  referred to as draft stan‐
           dards.  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 compatibil‐
           ity 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 accessible by other compo‐
           nents. Because the use of interfaces private to  another  component
           carries  great  stability  risks,  such  use is explicitly not sup‐
           ported. 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  document‐
           ing a Private interface include, but are not limited to, the inten‐
           tion 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  Obso‐
           lete 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 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 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 restric‐
                  tions 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 clas‐
       sification scheme was used. The following table summarizes the  mapping
       between the old and new classification 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 attributes ta‐
       ble  for  the Standard attribute type should appear.  T} StableCommit‐
       tedName  change.    EvolvingUncommittedActual   commitments   match.
       UnstableUncommittedName  change.   ExternalVolatileT{  Name  change
       with expansion of allowed usage.  T} Obsolete(Obsolete)Was a  classi‐
       fication, now a modifier.



       The  increased importance of Free or Open Source Software motivated the
       name change from Stable/Unstable to Committed/Uncommitted. Stable  con‐
       flicted 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 sec‐
       tion.

       Safe

           Safe is an attribute of code that  can  be  called  from  a  multi‐
           threaded  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 exam‐
           ple, 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  pro‐
           tected.  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 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 sup‐
           ports 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 perform‐
           ing  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  opera‐
           tions  when another thread calls forkall(), they will continue per‐
           forming the same I/O operations in both the parent and  child  pro‐
           cesses,  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
           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  mem‐
           ory.  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_can‐
           cel(3C) should ensure that they operate in a  Cancel-Safe  environ‐
           ment.  Libraries  that  have  cancellation points and which acquire
           resources such as locks or allocate memory dynamically,  also  con‐
           tribute 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  Asyn‐
           chronous-Cancel-Safety.   An   application   is  considered  to  be
           Deferred-Cancel-Safe when it is Cancel-Safe for threads whose  can‐
           cellation  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-Can‐
           cel-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 applica‐
           tion 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  docu‐
       ment is noted in this section.


       Programmers  producing  portable applications should rely on the inter‐
       face 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 stan‐
       dard  or  specification  allows alternative implementation choices, the
       manual page usually only describes the alternative implemented by  Ora‐
       cle  Solaris.  The manual page also describes any compatible extensions
       to the base  definition  of  Standard  interfaces  provided  by  Oracle
       Solaris.


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


       pkg(1)



SunOS 5.11                        23 Jun 2011                    attributes(5)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3