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