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

       Release		    Version		  Significance
       Major		    x.0			  Likely  to contain
						  major	     feature
						  additions;  adhere
						  to	  different,
						  possibly incompat-
						  ible	    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, compat-
						  ible	Standard and
						  Stable interfaces,
						  possibly incompat-
						  ible	    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  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.

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

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