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

개요

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

attributes(7)

Standards, Environments, Macros, Character Sets, and miscellany
                                                                 attributes(7)



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 TYPEAT‐
       TRIBUTE VALUE _ ArchitectureSPARC _ Availabilitysystem/kernel _  CSIEn‐
       abled _ Interface StabilityCommitted _ MT-LevelSafe _ StandardSee stan‐
       dards(7).


   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.

   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 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();  lw(1i)  lw(1i)  lw(3.5i) lw(1i) lw(1i) lw(3.5i) ReleaseVersion‐
       Significance _ 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  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 interfaces, or incompatible
       changes to Uncommitted or Volatile  interfaces.  Interfaces  previously
       declared  Obsolete may be removed via the End of Feature process.  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}



       For  example,  compared  to  Oracle Solaris 10, the Oracle Solaris 11.0
       release was a major release due to the switch from the  SVR4  packaging
       format to the Image Packaging System (IPS), even though binary compati‐
       bility was maintained for  applications  which  called  only  Committed
       interfaces in the Oracle Solaris ABI.


       Oracle  Solaris  11.2  was  a minor release, despite adding significant
       features such as Kernel Zones and Unified Archives, since  it  did  not
       have such incompatible changes when compared to the Oracle Solaris 11.0
       or 11.1 releases.


       Release levels of software included with Oracle Solaris may not  always
       reflect  the  release  level  of Oracle Solaris itself. For instance, a
       Micro release of Oracle Solaris (such as a Support  Repository  Update)
       may  include a Major release of a bundled software package, such as the
       Oracle Java Runtime Environment or a FOSS language interpreter.

   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(); lw(1i) lw(1i) lw(3.5i) lw(1i) lw(1i) lw(3.5i) StabilityReleaseC‐
       omments  _  CommittedMajor  (x.0)Incompatibilities  are exceptional.  _
       UncommittedMinor (x.y)Incompatibilities are possible.  _  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 standards.
           An "IETF Internet draft" is a well understood example of a specifi‐
           cation 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. Fail‐
           ure  to  apply this term to an entity is not an indication that the
           entity is some form of interface. It only indicates that the poten‐
           tial for confusion was not identified.


       Private

           A  Private  interface  is  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 components.
           Because the use of interfaces private to another component  carries
           great stability risks, such use is explicitly not supported. Compo‐
           nents not supplied by Oracle Solaris should not use Private  inter‐
           faces.

           Most  Private  interfaces  are not documented. It is an exceptional
           case when a Private interface is documented. Reasons for  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.


       Pass-through

           Pass-through is a modifier that can appear in conjunction with  the
           above classification levels. The Pass-through modifier indicates an
           interface whose specification is controlled by any body outside  of
           Oracle  Solaris  (typically  a Free/Open Source Software community)
           and "passed through" with minimal modification (typically only what
           is needed to make the component work well on Oracle Solaris).

           The  risk  of  using Pass-through interfaces in release-independent
           products will vary based on where the  outside  body  that  governs
           each  such  interface falls on the spectrum of stability (low, slow
           change) versus flexibility (high, fast  change).  Oracle  will  not
           commit  to insulating any consumers of these interfaces from incom‐
           patibilities introduced by those  outside  bodies.  In  particular,
           when  outside bodies drop support for a given version of their com‐
           ponents, Oracle Solaris will generally follow suit and drop support
           for  that version shortly thereafter, generally in favor of a later
           version. Note that "drop support" may mean removal, even in a Micro
           release.  For  how to freeze a component to allow its continued use
           in an unsupported fashion, see pkg(1) man page.


   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.


           6.     An outside body drops support for a particular version of  a
                  Pass-through  component.  One  example  of  this is when the
                  Python community dropped support for version 2.6 in favor of
                  versions 2.7 and 3.x.




       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(); lw(1i) lw(1i) lw(3.5i) lw(1i) lw(1i) lw(3.5i)  OldNewComments  _
       StandardCommittedT{  An  entry in the attributes table for the Standard
       attribute type should appear.  T} StableCommittedName change.  Evolvin‐
       gUncommittedActual  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  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(7)).  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 ANSI, 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(7)


       End  of Feature Notices (http://www.oracle.com/technetwork/systems/end-
       of-notices/)



Oracle Solaris 11.4               11 Dec 2017                    attributes(7)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3