unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



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.

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | SPARC                       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Unstable                    |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


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

  Availability
     This refers to the software package which contains  the com-
     mand  or  component  being  described on the man page. To be
     able to use the command, the  indicated  package  must  have
     been  installed. For information on how to add a package see
     pkgadd(1M).

  Code Set Independence (CSI)
     OS utilities and libraries which are 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 commands and utilities
     in Solaris, 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.

     However, for practical reasons,  this  independence  is  not
     absolute.  Certain  assumptions  are  still  applied  to the
     current CSI implementation:

        o  File code is a superset of ASCII.




SunOS 5.9           Last change: 15 Aug 2001                    1






Standards, Environments, and Macros                 attributes(5)



        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, desig-
           nation, invocation,  and  so  forth,  although  single
           shift is not excluded.

        o  Process code (wchar_t values) is implementation depen-
           dent  and  can change over time or between implementa-
           tions or between locales.

        o  Not every object in Solaris 2 and  Solaris  7can  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 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



SunOS 5.9           Last change: 15 Aug 2001                    2






Standards, Environments, and Macros                 attributes(5)



           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  internationalization  services,   dynamic
           binding  has  to be applied. Statically bound programs
           will only get support for C and POSIX locales.

  Interface Stability
     Sun often provides developers with early access to new tech-
     nologies,  which  allows developers to evaluate with them as
     soon as possible.  Unfortunately, new technologies are prone
     to  changes  and  standardization often results in interface
     incompatibility from previous versions.

     To make reasonable risk assessments, developers need to know
     how likely an interface is to change in future releases.  To
     aid developers in making these assessments,  interface  sta-
     bility  information  is  included  on some manual pages  for
     commands, entry-points, and file formats.

     The more stable interfaces can safely be used by nearly  all
     applications, because Sun will endeavor to ensure that these
     continue to work in future  minor  releases.    Applications
     that  depend  only  on 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  proto-
     typing,  but should be used only with the understanding that
     they  might  change  incompatibly  or  even  be  dropped  or
     replaced with alternatives in future minor releases.

     "Interfaces" that Sun does not document (for  example,  most
     kernel  data  structures  and  some symbols in system header
     files) may be implementation artifacts. Such internal inter-
     faces  are  not only subject to incompatible change or remo-
     val, but we are unlikely to mention such a change in release
     notes.

  Release Levels
     Products are given release levels, as well as names, to  aid
     compatibility  discussions.   Each  release  level  may also
     include changes suitable for lower levels.

     Release              Version               Significance










SunOS 5.9           Last change: 15 Aug 2001                    3






Standards, Environments, and Macros                 attributes(5)



     Major                x.0                   Likely to  contain
                                                major      feature
                                                additions;  adhere
                                                to      different,
                                                possibly  incompa-
                                                tible     Standard
                                                revisions;     and
                                                though   unlikely,
                                                could      change,
                                                drop,  or  replace
                                                Standard or Stable
                                                interfaces.   Ini-
                                                tial       product
                                                releases  are usu-
                                                ally 1.0.
     Minor                x.y                   Compared to an x.0
                                                or earlier release
                                                (y!=0),       it's
                                                likely to contain:
                                                minor      feature
                                                additions,  compa-
                                                tible Standard and
                                                Stable interfaces,
                                                possibly  incompa-
                                                tible     Evolving
                                                interfaces,     or
                                                likely  incompati-
                                                ble       Unstable
                                                interfaces.
     Micro                x.y.z                 Intended   to   be
                                                interface compati-
                                                ble with the  pre-
                                                vious      release
                                                (z!=0), but likely
                                                to  add bug fixes,
                                                performance
                                                enhancements,  and
                                                support for  addi-
                                                tional hardware.


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

     Stability       Release            Comments
     Standard        Major (x.0)        Actual or de facto.
     Stable          Major (x.0)        Incompatibilities are exceptional.



SunOS 5.9           Last change: 15 Aug 2001                    4






Standards, Environments, and Macros                 attributes(5)



     Evolving        Minor (x.y)        Migration advice  might  accompany
                                        an incompatibility.
     Unstable        Minor (x.y)        Experimental   or    transitional:
                                        incompatibilities are common.
     External        Micro (x.y.z)      Not     controlled     by     Sun:
                                        intrarelease incompatibilities are
                                        common.
     Obsolete        Minor (x.y)        Deprecated interface: likely to be
                                        removed in a future minor release.


     The interface stability  levels  described  in  this  manual
     page apply to both source and binary  interfaces unless oth-
     erwise stated.  The stability level of  each   interface  is
     unknown unless explicitly stated.

     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 standards. 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 standards(5) for a complete
           list of these standards.

           Most of these interfaces are defined by a formal stan-
           dard, and controlled by a standards development organ-
           ization. Changes will usually 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  standard;  support  for  later  versions is not
           guaranteed. If the standards 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  manual 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 defin-
           ition of Standard interfaces provided by Sun.



SunOS 5.9           Last change: 15 Aug 2001                    5






Standards, Environments, and Macros                 attributes(5)



     Stable
           A Stable interface is a mature interface  under  Sun's
           control.  Sun will try to avoid non-upwards-compatible
           changes to these interfaces, 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 compatibil-
           ity  with  previous 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 development.

     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  ver-
           sions  of such interfaces, subject to their availabil-
           ity 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. Applications 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 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.

     Obsolete: Scheduled for removal after event
           An Obsolete interface  is  supported  in  the  current



SunOS 5.9           Last change: 15 Aug 2001                    6






Standards, Environments, and Macros                 attributes(5)



           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 notifica-
           tion before discontinuing support. Use of an  Obsolete
           interface may produce warning messages.

  MT-Level
     Libraries are classified into four categories  which  define
     their ability to support multiple threads. Manual pages con-
     taining routines that are of multiple or   differing  levels
     show this within their NOTES or USAGEsection.

     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 pro-
           cess.   A multi-threaded application has the responsi-
           bility for using these interfaces in  a  safe  manner,
           which  is  different from whether or not the interface
           is Safe.  For example,  a  multi-threaded  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
           execute within the library. Unsafe libraries may  con-
           tain routines that are  Safe;  however,  most  of  the
           library's routines are unsafe to call.

           The following table  contains  reentrant  counterparts
           for Unsafe functions.  This table is subject to change
           by Sun.

           Reentrant functions for libc:


           Unsafe Function               Reentrant counterpart
           ctime                         ctime_r
           localtime                     localtime_r
           asctime                       asctime_r
           gmtime                        gmtime_r
           ctermid                       ctermid_r
           getlogin                      getlogin_r
           rand                          rand_r



SunOS 5.9           Last change: 15 Aug 2001                    7






Standards, Environments, and Macros                 attributes(5)



           readdir                       readdir_r
           strtok                        strtok_r
           tmpnam                        tmpnam_r


     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.  Note that a library can be safe to use, but
           not  MT-Safe.   For  example,  surrounding  an  entire
           library  with a monitor makes the library Safe, but it
           supports no concurrency so it is  not  considered  MT-
           Safe.  An  MT-Safe  library  must  permit a reasonable
           amount of concurrency. (This definition's  purpose  is
           to  give  precision to what is meant when a library is
           described as Safe.  The definition of a  Safe  library
           does  not specify if the library supports concurrency.
           The MT-Safe definition makes it clear that the library
           is  Safe,  and supports some concurrency.  This clari-
           fies the Safe definition, which can mean anything from
           being  single  threaded  to  being  any degree of mul-
           tithreaded.)

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

           Signals  are  disabled  when  locks  are  acquired  in
           Async-Signal-Safe  routines.  This  prevents  a signal
           handler that might acquire the same  lock  from  being
           called.   The   list  of  Async-Signal-Safe  functions
           includes:


           _exit                access                aio_error
           aio_return           aio_suspend           alarm
           cfgetispeed          cfgetospeed           cfsetispeed
           cfsetospeed          chdir                 chmod
           chown                clock_gettime         close
           creat                dup                   dup2
           execle               execve                fcntl
           fdatasync            fork                  fstat
           fsync                getegid               geteuid
           getgid               getgroups             getpgrp
           getpid               getppid               getuid
           kill                 link                  lseek
           mkdir                mkfifo                open



SunOS 5.9           Last change: 15 Aug 2001                    8






Standards, Environments, and Macros                 attributes(5)



           pathconf             pause                 pipe
           read                 rename                rmdir
           sem_post             sema_post             setgid
           setpgid              setsid                setuid
           sigaction            sigaddset             sigdelset
           sigemptyset          sigfillset            sigismember
           sigpending           sigprocmask           sigqueue
           sigsuspend           sleep                 stat
           sysconf              tcdrain               tcflow
           tcflush              tcgetattr             tcgetpgrp
           tcsendbreak          tcsetattr             tcsetpgrp
           thr_kill             thr_sigsetmask        time
           timer_getoverrun     timer_gettime         timer_settime
           times                umask                 uname
           unlink               utime                 wait
           waitpid              write


     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.

     Fork1-Safe
           A Fork1-Safe library releases the locks  it  had  held
           whenever  fork1(2)  is called in a Solaris thread pro-
           gram, or fork(2) in a POSIX (see standards(5))  thread
           program. Calling fork(2) in a POSIX thread program has
           the same semantic as calling  fork1(2)  in  a  Solaris
           thread program. All system calls, libpthread, and lib-
           thread are Fork1-Safe. Otherwise,  you  should  handle
           the      locking      clean-up      yourself      (see
           pthread_atfork(3C)).

     Cancel-Safety
           If     a     multi-threaded      application      uses
           pthread_cancel(3THR)  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(3THR)),  the  application  is  "cancel-
           unsafe", that is, it is not safe with respect to  can-
           cellation. 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(3THR)  should  ensure that they operate



SunOS 5.9           Last change: 15 Aug 2001                    9






Standards, Environments, and Macros                 attributes(5)



           in a Cancel-Safe environment. Libraries that have can-
           cellation  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  multi-threaded program:
           Cancel-Safety.  There  are   two   sub-categories   of
           Cancel-Safety:       Deferred-Cancel-Safety,       and
           Asynchronous-Cancel-Safety.  An  application  is  con-
           sidered  to be Deferred-Cancel-Safe when it is Cancel-
           Safe  for   threads   whose   cancellation   type   is
           PTHREAD_CANCEL_DEFERRED.  An application is considered
           to be Asynchronous-Cancel-Safe when it is  Cancel-Safe
           for     threads    whose    cancellation    type    is
           PTHREAD_CANCEL_ASYNCHRONOUS. Deferred-Cancel-Safety is
           easier  to  achieve  than  Asynchronous-Cancel-Safety,
           since a thread with the deferred cancellation type can
           be cancelled only at well-defined cancellation points,
           whereas a thread with  the  asynchronous  cancellation
           type  can be cancelled anywhere. Since all threads are
           created by default to have the  deferred  cancellation
           type,  it  may never be necessary to worry about asyn-
           chronous cancel safety. Indeed, most applications  and
           libraries  are  expected  to  always  be Asynchronous-
           Cancel-Unsafe. An application which  is  Asynchronous-
           Cancel-Safe  is  also, by definition, Deferred-Cancel-
           Safe.

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

























SunOS 5.9           Last change: 15 Aug 2001                   10