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

FreeBSD Manual Pages


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

       attributes,  architecture, availability,	CSI, stability,	MT-Level - at-
       tributes	of interfaces

       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  defines processor or specific hardware. (See -p option of
       uname(1)). In some cases, it may	indicate required adapters or  periph-

       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  in Solaris, for example,	that work only
       with Extended Unix Codesets (EUC), an encoding method that allows  con-
       current	support	for up to four code sets and is	commonly used  to rep-
       resent Asian character 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 in Solaris 2 and Solaris 7can  have  names  com-
	     posed of arbitrary	characters. 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 charac-

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

       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
       Obsolete	       Minor (x.y)	  Deprecated interface:	likely to be
					  removed in a future minor release.

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

       Standard[: [organization_name,] standard_name, version]
	     The documented interface complies with the	standard listed. If  a
	     standard  is  not	specified  the interface is defined by several
	     standards.	This is	usually	the hierarchy built up from the	C Lan-
	     guage  (defined  by  ISO/IEC  or K&R), SVID 3 and associated ABIs
	     (defined by AT&T),	the  POSIX  standards  (defined	 by  IEEE  and
	     ISO/IEC), and the Single UNIX Specifications (defined by The Open
	     Group). See standards(5) for a complete list of these standards.

	     Most of these interfaces are defined by a	formal	standard,  and
	     controlled	 by a standards	development organization. Changes will
	     usually be	made in	accordance with	approved changes to that stan-
	     dard. This	stability level	can also apply to interfaces that have
	     been adopted (without a formal standard) by an "industry  conven-

	     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
	     manual page descriptions of Standard interfaces. When  the	 stan-
	     dard  or specification allows alternative implementation choices,
	     the manual	page usually only  describes  the  alternative	imple-
	     mented  by	Sun. The manual	page also describes any	compatible ex-
	     tensions to the base definition of	Standard  interfaces  provided
	     by	Sun.

	     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.

	     An	 Evolving  interface  may eventually become Standard or	Stable
	     but is still in transition.

	     Sun will make reasonable efforts  to  ensure  compatibility  with
	     previous  releases	 as  it	 evolves.  When	non-upwards compatible
	     changes become necessary, they will  occur	in minor and major re-
	     leases;  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 con-
	     tinued source development.

	     An	 External interface is controlled by an	entity other than Sun.
	     At	Sun's discretion, Sun can deliver as part of any  release  up-
	     dated and possibly	incompatible versions of such interfaces, sub-
	     ject to their availability	 from  the  controlling	 entity.  This
	     classification  is	typically applied to publicly available	"free-
	     ware" 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  re-
	     leases, including patches that contain External interfaces.

	     An	 Unstable   interface is provided to give developers early ac-
	     cess to new  or rapidly changing technology or as an interim  so-
	     lution  to	 a problem for which a more stable solution is antici-
	     pated in the future.

	     For Unstable interfaces, Sun no claims about either source	or bi-
	     nary  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  sup-
	     port  of  an interface is to be discontinued, Sun will attempt to
	     provide notification before discontinuing support.	Use of an  Ob-
	     solete interface may produce warning messages.

       Libraries are classified	into four categories which define  their abil-
       ity to support multiple threads.	Manual pages containing	routines  that
       are  of	multiple  or  differing	levels show this within	their NOTES or

       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 multi-threaded application
	     has the responsibility for	using these interfaces in a safe  man-
	     ner,  which  is  different	 from  whether or not the interface is
	     Safe.  For	example, a multi-threaded application  that  closes  a
	     file that is still	in use by other	threads	within the application
	     is	not using the close(2) interface safely.

	     An	Unsafe library contains	global and static  data	 that  is  not
	     protected.	 It is not safe	to use unless the application arranges
	     for only one thread at time to execute within the library.	Unsafe
	     libraries	may   contain routines that are	Safe; however, most of
	     the library's routines are	unsafe to call.

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

	     Reentrant functions for libc:

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

	     rand			   rand_r
	     readdir			   readdir_r
	     strtok			   strtok_r
	     tmpnam			   tmpnam_r

	     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. Note that a library can be safe
	     to	use, but not MT-Safe.  For example, surrounding	an entire  li-
	     brary  with  a monitor makes the library Safe, but	it supports no
	     concurrency so it is not considered MT-Safe. An  MT-Safe  library
	     must  permit  a  reasonable  amount of concurrency. (This defini-
	     tion's purpose is to give precision to what is meant when	a  li-
	     brary  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 sup-
	     ports some	concurrency.   This  clarifies	the  Safe  definition,
	     which  can	 mean anything from being single threaded to being any
	     degree of multithreaded.)

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

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

	     _exit		  access		aio_error
	     aio_return		  aio_suspend		alarm
	     cfgetispeed	  cfgetospeed		cfsetispeed
	     cfsetospeed	  chdir			chmod
	     chown		  clock_gettime		close
	     creat		  dup			dup2
	     execle		  execve		fcntl
	     fdatasync		  fork			fstat
	     fsync		  getegid		geteuid
	     getgid		  getgroups		getpgrp
	     getpid		  getppid		getuid
	     kill		  link			lseek
	     mkdir		  mkfifo		open
	     pathconf		  pause			pipe
	     read		  rename		rmdir
	     sem_post		  sema_post		setgid
	     setpgid		  setsid		setuid
	     sigaction		  sigaddset		sigdelset
	     sigemptyset	  sigfillset		sigismember
	     sigpending		  sigprocmask		sigqueue
	     sigsuspend		  sleep			stat
	     sysconf		  tcdrain		tcflow
	     tcflush		  tcgetattr		tcgetpgrp
	     tcsendbreak	  tcsetattr		tcsetpgrp
	     thr_kill		  thr_sigsetmask	time
	     timer_getoverrun	  timer_gettime		timer_settime
	     times		  umask			uname
	     unlink		  utime			wait
	     waitpid		  write

       MT-Safe with Exceptions
	     See  the NOTES or USAGE sections of these pages for a description
	     of	the exceptions.

       Safe with Exceptions
	     See the NOTES or USAGE sections of	these pages for	a  description
	     of	the exceptions.

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

	     If	a multi-threaded application uses pthread_cancel(3THR) to can-
	     cel (that is, kill) a thread, it  is  possible  that  the	target
	     thread  is	killed while holding a resource, such as a lock	or al-
	     located memory. If	the thread has not installed  the  appropriate
	     cancellation  cleanup handlers to release the resources appropri-
	     ately (see	pthread_cancel(3THR)), the application is  "cancel-un-
	     safe", 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, mem-
	     ory not being freed on thread cancellation. All applications that
	     use  pthread_cancel(3THR)	should	ensure	that they operate in a
	     Cancel-Safe environment. Libraries	that have cancellation	points
	     and  which	acquire	resources such as locks	or allocate memory dy-
	     namically,	also contribute	to the cancel-unsafety of applications
	     that  are	linked	with  these libraries. This introduces another
	     level of safety for libraries in a	multi-threaded	program:  Can-
	     cel-Safety.  There	 are  two sub-categories of Cancel-Safety: De-
	     ferred-Cancel-Safety, and Asynchronous-Cancel-Safety. An applica-
	     tion  is considered to be Deferred-Cancel-Safe when it is Cancel-
	     Safe for threads whose cancellation  type	is  PTHREAD_CANCEL_DE-
	     FERRED.  An  application is considered to be Asynchronous-Cancel-
	     Safe when it is Cancel-Safe for threads whose  cancellation  type
	     is	 PTHREAD_CANCEL_ASYNCHRONOUS. Deferred-Cancel-Safety is	easier
	     to	achieve	than Asynchronous-Cancel-Safety, since a  thread  with
	     the  deferred cancellation	type can be cancelled only at well-de-
	     fined cancellation	points,	whereas	a thread with the asynchronous
	     cancellation  type	 can  be cancelled anywhere. Since all threads
	     are created by default to have the	deferred cancellation type, it
	     may never be necessary to worry about asynchronous	cancel safety.
	     Indeed, most applications and libraries are expected to always be
	     Asynchronous-Cancel-Unsafe. An application	which is Asynchronous-
	     Cancel-Safe is also, by definition, Deferred-Cancel-Safe.

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

SunOS 5.9			  15 Aug 2001			 attributes(5)


Want to link to this manual page? Use this URL:

home | help