attributes man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

ATTRIBUTES(5)							 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.

       ┌────────────────────┬───────────────────┐
       │  ATTRIBUTE TYPE    │  ATTRIBUTE VALUE	│
       ├────────────────────┼───────────────────┤
       │Architecture	    │ SPARC		│
       ├────────────────────┼───────────────────┤
       │CSI		    │ Enabled		│
       ├────────────────────┼───────────────────┤
       │Interface Stability │ Committed		│
       ├────────────────────┼───────────────────┤
       │MT-Level	    │ Safe		│
       ├────────────────────┼───────────────────┤
       │Standard	    │ See 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.

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

       Release	 Version      Significance
       ────────────────────────────────────────
       Major	 x.0	   Likely  to  contain
			   major feature addi‐
			   tions;   adhere  to
			   different,	possi‐
			   bly	  incompatible
			   standard revisions;
			   and		though
			   unlikely,	 could
			   change,   drop,  or
			   replace   Committed
			   interfaces. Initial
			   product    releases
			   are usually 1.0.
       ────────────────────────────────────────
       Minor	 x.y	   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	Uncom‐
			   mitted  or Volatile
			   interfaces.
       ────────────────────────────────────────
       Micro	 x.y.z	   Intended   to    be
			   interface  compati‐
			   ble with the previ‐
			   ous release (z!=0),
			   but likely  to  add
			   bug	fixes, perfor‐
			   mance enhancements,
			   and	 support   for
			   additional	 hard‐
			   ware.  Incompatible
			   changes to Volatile
			   interfaces are pos‐
			   sible.

       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.

	Stability	Release			  Comments
       ─────────────────────────────────────────────────────────────────
       Committed     Major (x.0)     Incompatibilities are exceptional.
       ─────────────────────────────────────────────────────────────────
       Uncommitted   Minor (x.y)     Incompatibilities are common.
       ─────────────────────────────────────────────────────────────────
       Volatile	     Micro (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 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.

       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, Sun will attempt to  pro‐
	   vide 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 Sun expects to make a reasonable effort to
		      maintain	compatibility with previous releases until the
		      next Minor release at which time Sun expects to synchro‐
		      nize 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, 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.

       Volatile

	   Volatile interfaces can change at any time and for any reason.

	   The	Volatile  interface  stability	level  allows  Sun products to
	   quickly track a fluid,  rapidly  evolving  specification.  In  many
	   cases,  this	 is preferred to providing additional stability to the
	   interface, as it may better meet the expectations of the consumer.

	   The most common application of this taxonomy level is to interfaces
	   that are controlled by a body other than Sun, but unlike specifica‐
	   tions controlled by standards bodies or Free or Open	 Source	 Soft‐
	   ware (FOSS) communities which value interface compatibility, it can
	   not be asserted that an incompatible change to the interface speci‐
	   fication  would be exceedingly rare. It may also be applied to FOSS
	   controlled software where it is deemed more important to track  the
	   community  with  minimal  latency  than to provide stability to our
	   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 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.

       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, Sun 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 Sun
       and the customer to break the interface stability commitment. The  fol‐
       lowing  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 Sun 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.

	 Old	      New		      Comments
       ───────────────────────────────────────────────────────────────
       Standard	  Committed	An entry in the attributes table  for
				the  Standard  attribute  type should
				appear.
       Stable	  Committed	Name change.
       Evolving	  Uncommitted	Actual commitments match.
       Unstable	  Uncommitted	Name change.
       External	  Volatile	Name change with expansion of allowed
				usage.
       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(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  Sun.
       The  manual  page  also describes any compatible extensions to the base
       definition of Standard interfaces provided by Sun.

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

				 Jul 29, 2007			 ATTRIBUTES(5)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net