Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
attributes(5)	      Standards, Environments, and Macros	 attributes(5)

NAME
       attributes,  architecture, availability,	CSI, stability,	MT-Level - at-
       tributes	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 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 en-
	    coding 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 en-
	    abled, all can handle single-byte and multi-byte locales  released
	    in	2.6. For applications to get full support of internationaliza-
	    tion 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.  Un-
       fortunately,  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 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 fu-
       ture 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  in-
       compatibly  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 ad-
						  ditions; adhere to
						  different,  possi-
						  bly	incompatible
						  Standard     revi-
						  sions; and  though
						  unlikely,    could
						  change,  drop,  or
						  replace   Standard
						  or  Stable  inter-
						  faces.     Initial
						  product   releases
						  are usually 1.0.
       Minor		    x.y			  Compared to an x.0
						  or earlier release
						  (y!=0),	it's
						  likely to contain:
						  minor	 feature ad-
						  ditions,  compati-
						  ble  Standard	 and
						  Stable interfaces,
						  possibly incompat-
						  ible Evolving	 in-
						  terfaces,	  or
						  likely  incompati-
						  ble  Unstable	 in-
						  terfaces.
       Micro		    x.y.z		  Intended to be in-
						  terface compatible
						  with the  previous
						  release    (z!=0),
						  but likely to	 add
						  bug fixes, perfor-
						  mance	    enhance-
						  ments, and support
						  for	  additional
						  hardware.

   Classifications
       The following table summarizes how stability level  classifications re-
       late 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	 indi-
       vidual classifications, see the appropriate subsection below.

       Stability       Release		  Comments
       Standard	       Major (x.0)	  Actual or de facto.
       Stable	       Major (x.0)	  Incompatibilities are	exceptional.
       Evolving	       Minor (x.y)	  Migration  advice  might accompany
					  an incompatibility.
       Unstable	       Minor (x.y)	  Experimental or transitional:	 in-
					  compatibilities are common.

       External	       Micro (x.y.z)	  Not	controlled   by	  Sun:	 in-
					  trarelease  incompatibilities	 are
					  common.
       Obsolete	       Minor (x.y)	  Deprecated interface:	likely to be
					  removed in a future minor release.

       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 in-
	   terface 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 at-
	   tempt  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 in-
	   terface 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 in-
	   terface 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 re-
	   sponsibility	for using these	interfaces in a	safe manner, which  is
	   different from whether or not the interface is Safe.	For example, 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  li-
	   braries might contain functions that	are Safe; however, most	of the
	   library's functions are unsafe to call. Some	functions that are Un-
	   safe	 have reentrant	counterparts that are MT-Safe. Reentrant func-
	   tions 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 in-
	   terrupted by	a signal. Signals are only a problem for MT-Safe func-
	   tions 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 re-
	   sources such	as locks or allocate memory dynamically, also contrib-
	   ute	to  the	 cancel-unsafety  of applications that are linked with
	   these libraries. This introduces another level of  safety  for  li-
	   braries  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 De-
	   ferred-Cancel-Safe when it is Cancel-Safe for threads whose cancel-
	   lation  type	 is PTHREAD_CANCEL_DEFERRED. An	application is consid-
	   ered	to be Asynchronous-Cancel-Safe	when  it  is  Cancel-Safe  for
	   threads whose cancellation type is PTHREAD_CANCEL_ASYNCHRONOUS. De-
	   ferred-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  de-
	   ferred  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,  De-
	   ferred-Cancel-Safe.

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

SunOS 5.10			  19 Dec 2003			 attributes(5)

NAME | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=attributes&sektion=5&manpath=SunOS+5.10>

home | help