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

   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
       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
       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
       Micro		    x.y.z		  Intended   to	  be
						  interface compati-
						  ble with the	pre-
						  vious	     release
						  (z!=0), but likely
						  to  add bug fixes,
						  enhancements,	 and
						  support for  addi-
						  tional hardware.

       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
       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
	     extensions	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
	     releases;	such  changes will be avoided in  micro	releases when-
	     ever possible. If such a change is	necessary, it  will  be	 docu-
	     mented  in	 the  release notes for	the affected release, and when
	     feasible, Sun will	provide	migration aids for binary  compatibil-
	     ity and continued 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
	     updated  and  possibly  incompatible versions of such interfaces,
	     subject 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
	     releases, including patches that contain External interfaces.

	     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 antici-
	     pated in the future.

	     For Unstable interfaces, Sun 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  sup-
	     port  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.

       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
	     library 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
	     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 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
	     allocated 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-
	     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_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 mem-
	     ory dynamically, also contribute to the cancel-unsafety of	appli-
	     cations  that  are	 linked	 with these libraries. This introduces
	     another level of safety for libraries in  a  multi-threaded  pro-
	     gram:  Cancel-Safety.  There  are	two  sub-categories of Cancel-
	     Safety: Deferred-Cancel-Safety,  and  Asynchronous-Cancel-Safety.
	     An	 application  is considered to be Deferred-Cancel-Safe when it
	     is	 Cancel-Safe  for   threads   whose   cancellation   type   is
	     PTHREAD_CANCEL_DEFERRED. An application is	considered to be Asyn-
	     chronous-Cancel-Safe when it is  Cancel-Safe  for	threads	 whose
	     cancellation  type	 is PTHREAD_CANCEL_ASYNCHRONOUS. Deferred-Can-
	     cel-Safety	is easier to achieve than  Asynchronous-Cancel-Safety,
	     since  a  thread  with the	deferred cancellation type can be can-
	     celled only at well-defined cancellation points, whereas a	thread
	     with  the	asynchronous  cancellation  type can be	cancelled any-
	     where. 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 def-
	     inition, 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