unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

attributes(5)         Standards, Environments, and Macros        attributes(5)



NAME
       attributes,  architecture,  availability,  CSI,  stability,  MT-Level -
       attributes of interfaces

DESCRIPTION
       The ATTRIBUTES section of a manual page contains a  table  (see  below)
       defining attribute types and their corresponding values.


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE ArchitectureSPARC  Avail-
       abilitySUNWcsu CSIEnabled Interface StabilityUnstable MT-LevelSafe


   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 pkgadd(1M).

   Code Set Independence (CSI)
       OS utilities and libraries which are free of dependencies on the  prop-
       erties  of  any code sets are said to have Code Set Independence (CSI).
       They have the attribute of being CSI enabled. This is  in  contrast  to
       many  commands and utilities, for example, that work only with Extended
       Unix Codesets (EUC), an encoding method that allows concurrent  support
       for up to four code sets and is commonly used  to represent Asian char-
       acter sets.

       However, for practical reasons, 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. Stateless
            encoding avoids shift, locking shift, designation, invocation, and
            so forth, although single shift is not excluded.

         o  Process  code (wchar_t values) is implementation dependent and can
            change over time or between implementations or between locales.

         o  Not every object can have names composed of arbitrary  characters.
            The names of the following objects must be composed of ASCII char-
            acters:

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

                   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 charac-
            ters. 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.  Stati-
            cally  bound  programs  will  only  get  support  for  C and POSIX
            locales.


   Interface Stability
       Sun often provides developers with early access  to  new  technologies,
       which  allows  developers  to  evaluate  with them as soon as possible.
       Unfortunately, new technologies are prone to changes  and  standardiza-
       tion 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 Sun will endeavor to ensure that these continue to work
       in future minor releases. Applications that depend only on Standard and
       Stable  interfaces  should  reliably  continue to function correctly on
       future minor releases (but not necessarily on earlier major releases).

       The less stable interfaces allow experimentation and  prototyping,  but
       should  be  used  only  with  the  understanding that they might change
       incompatibly or even be dropped or replaced with alternatives in future
       minor releases.

       "Interfaces"  that Sun does not document (for example, most kernel data
       structures and some symbols in system header files) may be  implementa-
       tion artifacts. Such internal interfaces are not only subject to incom-
       patible 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(1.833333i)  lw(1.833333i)  lw(1.833333i).   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  Standard  or  Stable
       interfaces.  Initial  product  releases are usually 1.0.  T} Minorx.yT{
       Compared to an x.0 or earlier release (y!=0), it's likely  to  contain:
       minor  feature  additions,  compatible  Standard and Stable interfaces,
       possibly  incompatible  Evolving  interfaces,  or  likely  incompatible
       Unstable interfaces.  T} Microx.y.zT{ Intended to be interface compati-
       ble with the previous release (z!=0), but likely to add bug fixes, per-
       formance enhancements, and support for additional hardware.  T}


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

       tab(); lw(1.306020i) lw(1.637124i) lw(2.556856i).  StabilityReleaseCom-
       ments StandardMajor (x.0)Actual or de facto.   StableMajor  (x.0)Incom-
       patibilities  are  exceptional.  EvolvingMinor (x.y)T{ Migration advice
       might accompany an incompatibility.  T} UnstableMinor  (x.y)T{  Experi-
       mental or transitional: incompatibilities are common.  T} ExternalMicro
       (x.y.z)T{ Not controlled by  Sun:  intrarelease  incompatibilities  are
       common.   T}  ObsoleteMinor  (x.y)T{ Deprecated interface: likely to be
       removed in a future minor release.  T}


       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 stability level of a documented
       interface (one that is documented in the manual pages)  is  unspecified
       unless explicitly stated. The stability level of an undocumented inter-
       face is implicitly Private.

       The existence of documentation other than the documentation that  is  a
       component  of  the Solaris product should not be construed to imply any
       level of stability for interfaces provided by the Solaris product.  The
       only source of stability level information is Solaris manual pages.

       Standard[: [organization_name,] standard_name, version]

           The  documented  interface  complies with the standard listed. If a
           standard is not specified the interface is defined by several stan-
           dards.  This  is usually the hierarchy built up from the C Language
           (defined by ISO/IEC or K&R), SVID 3 and associated ABIs (defined by
           AT&T),  the  POSIX standards (defined by IEEE and ISO/IEC), and the
           Single UNIX Specifications (defined by The Open Group).  See  stan-
           dards(5) for a complete list of these standards.

           Most of these interfaces are defined by a formal standard, and con-
           trolled by a standards development organization. Changes will  usu-
           ally  be made in accordance with approved changes to that standard.
           This stability level can also apply to interfaces  that  have  been
           adopted (without a formal standard) by an "industry convention."

           Support  is  provided  for only the specified version(s) of a stan-
           dard; support for later versions is not guaranteed.  If  the  stan-
           dards  development  organization  approves  a non-upward-compatible
           change to a Standard interface that Sun  decides  to  support,  Sun
           will announce a compatibility and migration strategy.

           Programmers  producing  portable  applications  should  rely on the
           interface descriptions present in the standard or specification  to
           which  the application is intended to conform, rather than the man-
           ual page descriptions of Standard interfaces. When the standard  or
           specification allows alternative implementation choices, the manual
           page usually only describes the alternative implemented by Sun. The
           manual  page  also  describes any compatible extensions to the base
           definition of Standard interfaces provided by Sun.



       Stable

           A Stable interface is a mature interface under Sun's  control.  Sun
           will  try  to  avoid non-upwards-compatible changes to these inter-
           faces, especially in minor or micro releases.

           If support of a Stable interface must  be  discontinued,  Sun  will
           attempt  to provide notification and the stability level changes to
           Obsolete.



       Evolving

           An Evolving interface may eventually become Standard or Stable  but
           is still in transition.

           Sun  will make reasonable efforts to ensure compatibility with pre-
           vious releases as it evolves. When non-upwards  compatible  changes
           become necessary, they will occur in minor and major releases; such
           changes will be avoided in micro  releases  whenever  possible.  If
           such  a  change  is necessary, it will be documented in the release
           notes for the affected release, and when feasible, Sun will provide
           migration aids for binary compatibility and continued source devel-
           opment.



       External

           An External interface is controlled by an entity other than Sun. At
           Sun's  discretion,  Sun  can deliver as part of any release updated
           and possibly incompatible versions of such interfaces,  subject  to
           their availability from the controlling entity. This classification
           is typically applied to publicly available "freeware"  and  similar
           objects.

           For  External  interfaces,  Sun  makes  no  claims regarding either
           source or binary compatibility between any two  releases.  Applica-
           tions  based on these interfaces might not work in future releases,
           including patches that contain External interfaces.



       Unstable

           An Unstable  interface is provided to give developers early  access
           to new  or rapidly changing technology or as an interim solution to
           a problem for which a more stable solution is  anticipated  in  the
           future.

           For Unstable interfaces, Sun makes no claims about either source or
           binary compatibility from one minor release  to  another.  Applica-
           tions  developed  based on  these interfaces may not work in future
           minor releases.



       Obsolete: Scheduled for removal after event

           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
           interface may produce warning messages.



       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 Sun Microsystems should not use
           Private interfaces.

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



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



       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.



SEE ALSO
       uname(1), pkgadd(1M), Intro(3), standards(5)



SunOS 5.10                        19 Dec 2003                    attributes(5)