1attributes(5)         Standards, Environments, and Macros        attributes(5)
2
3
4

NAME

6       attributes, architecture, availability, CSI, stability, MT-Level, stan‐
7       dard - attributes of interfaces
8

DESCRIPTION

10       The ATTRIBUTES section of a  manual  page  contains  a  table  defining
11       attribute  types  and  their  corresponding values. The following is an
12       example of an attributes table. Not all attribute types are appropriate
13       for all types of interfaces.
14
15
16
17
18       ┌─────────────────────────────┬─────────────────────────────┐
19       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
20       ├─────────────────────────────┼─────────────────────────────┤
21       │Architecture                 │SPARC                        │
22       ├─────────────────────────────┼─────────────────────────────┤
23       │Availability                 │SUNWcsu                      │
24       ├─────────────────────────────┼─────────────────────────────┤
25       │CSI                          │Enabled                      │
26       ├─────────────────────────────┼─────────────────────────────┤
27       │Interface Stability          │Committed                    │
28       ├─────────────────────────────┼─────────────────────────────┤
29       │MT-Level                     │Safe                         │
30       ├─────────────────────────────┼─────────────────────────────┤
31       │Standard                     │See standards(5).            │
32       └─────────────────────────────┴─────────────────────────────┘
33
34   Architecture
35       Architecture  defines  processor or specific hardware. See -p option of
36       uname(1). In some cases, it may indicate required adapters or peripher‐
37       als.
38
39   Availability
40       This refers to the software package which contains  the command or com‐
41       ponent being described on the man page. To be able to use the  command,
42       the  indicated package must have been installed. For information on how
43       to add a package see pkgadd(1M).
44
45   Code Set Independence (CSI)
46       OS utilities and libraries free of dependencies on  the  properties  of
47       any  code  sets are said to have Code Set Independence (CSI). They have
48       the attribute of being CSI enabled. This is in contrast  to  many  com‐
49       mands  and  utilities,  for  example, that work only with Extended Unix
50       Codesets (EUC), an encoding method that allows concurrent  support  for
51       up to four code sets and is commonly used  to represent Asian character
52       sets.
53
54
55       For practical reasons, however, this independence is not absolute. Cer‐
56       tain assumptions are still applied to the current CSI implementation:
57
58           o      File code is a superset of ASCII.
59
60           o      To  support  multi-byte characters and null-terminated  UNIX
61                  file names, the NULL and / (slash) characters cannot be part
62                  of any multi-byte characters.
63
64           o      Only  "stateless"  file code encodings are supported. State‐
65                  less encoding  avoids  shift,  locking  shift,  designation,
66                  invocation,  and  so  forth,  although  single  shift is not
67                  excluded.
68
69           o      Process code (wchar_t values)  is  implementation  dependent
70                  and  can  change  over  time  or  between implementations or
71                  between locales.
72
73           o      Not every object can have names composed of arbitrary  char‐
74                  acters.  The names of the following objects must be composed
75                  of ASCII characters:
76
77               o      User names, group name, and passwords
78
79               o      System name
80
81               o      Names of printers and special devices
82
83               o      Names of terminals (/dev/tty*)
84
85               o      Process ID numbers
86
87               o      Message queues, semaphores, and shared memory labels.
88
89               o      The following may be composed  of  ISO  Latin-1  or  EUC
90                      characters:
91
92                   o      File names
93
94                   o      Directory names
95
96                   o      Command names
97
98                   o      Shell variables and environmental variable names
99
100                   o      Mount points for file systems
101
102                   o      NIS key names and domain names
103
104           o      The  names  of  NFS shared files should be composed of ASCII
105                  characters. Although files and directories  may  have  names
106                  and  contents  composed  of  characters  from non-ASCII code
107                  sets, using only  the  ASCII  codeset  allows  NFS  mounting
108                  across any machine, regardless of localization. For the com‐
109                  mands and utilities that are CSI  enabled,  all  can  handle
110                  single-byte  and  multi-byte  locales  released  in 2.6. For
111                  applications to get  full  support  of  internationalization
112                  services,  dynamic  binding  has  to  be applied. Statically
113                  bound programs  will  only  get  support  for  C  and  POSIX
114                  locales.
115
116   Interface Stability
117       Sun  often  provides  developers with early access to new technologies,
118       which allows developers to evaluate with  them  as  soon  as  possible.
119       Unfortunately,  new  technologies are prone to changes and standardiza‐
120       tion often results in interface incompatibility from previous versions.
121
122
123       To make reasonable risk assessments, developers need to know how likely
124       an interface is to change in future releases. To aid developers in mak‐
125       ing these assessments, interface stability information is  included  on
126       some manual pages  for commands, entry-points, and file formats.
127
128
129       The  more  stable  interfaces can safely be used by nearly all applica‐
130       tions, because Sun will endeavor to ensure that these continue to  work
131       in  future  minor  releases. Applications that depend only on Committed
132       interfaces should reliably continue to  function  correctly  on  future
133       minor releases (but not necessarily on earlier major releases).
134
135
136       The  less  stable interfaces allow experimentation and prototyping, but
137       should be used only with  the  understanding  that  they  might  change
138       incompatibly or even be dropped or replaced with alternatives in future
139       minor releases.
140
141
142       "Interfaces" that Sun does not document (for example, most kernel  data
143       structures  and some symbols in system header files) may be implementa‐
144       tion artifacts. Such internal interfaces are not only subject to incom‐
145       patible change or removal, but we are unlikely to mention such a change
146       in release notes.
147
148   Release Levels
149       Products are given release levels, as well as names, to aid compatibil‐
150       ity  discussions.  Each release level may also include changes suitable
151       for lower levels.
152
153
154
155
156         Release       Version               Significance
157       ──────────────────────────────────────────────────────────────
158       Major         x.0           Likely to contain  major  feature
159                                   additions;  adhere  to different,
160                                   possibly  incompatible   standard
161                                   revisions;  and  though unlikely,
162                                   could change,  drop,  or  replace
163                                   Committed   interfaces.   Initial
164                                   product releases are usually 1.0.
165       ──────────────────────────────────────────────────────────────
166       Minor         x.y           Compared to  an  x.0  or  earlier
167                                   release  (y!=0),  it is likely to
168                                   contain: feature additions,  com‐
169                                   patible   changes   to  Committed
170                                   interfaces, or likely  incompati‐
171                                   ble  changes  to  Uncommitted  or
172                                   Volatile interfaces.
173       ──────────────────────────────────────────────────────────────
174       Micro         x.y.z         Intended to be interface compati‐
175                                   ble  with  the  previous  release
176                                   (z!=0), but  likely  to  add  bug
177                                   fixes,  performance enhancements,
178                                   and support for additional  hard‐
179                                   ware.   Incompatible  changes  to
180                                   Volatile interfaces are possible.
181
182
183
184       In the context of interface stability,  update  releases  (occasionally
185       referred to as patch releases) should be considered equivalent to Micro
186       Releases.
187
188   Classifications
189       The following table summarizes  how  stability  level   classifications
190       relate  to  release  level. The first column lists the Stability Level.
191       The second column lists the Release Level for Incompatible Changes, and
192       the  third  column  lists  other comments. For a complete discussion of
193       individual classifications, see the appropriate subsection below.
194
195
196
197
198
199        Stability       Release                   Comments
200       ─────────────────────────────────────────────────────────────────
201       Committed     Major (x.0)     Incompatibilities are exceptional.
202       ─────────────────────────────────────────────────────────────────
203       Uncommitted   Minor (x.y)     Incompatibilities are common.
204       ─────────────────────────────────────────────────────────────────
205       Volatile      Micro (x.y.z)   Incompatibilities are common.
206
207
208
209       The interface stability level classifications described on this  manual
210       page  apply  to  both  source  and  binary  interfaces unless otherwise
211       stated. All stability level classifications are public, with the excep‐
212       tion  of  the  Private classification. The precise stability level of a
213       public interface (one that  is  documented  in  the  manual  pages)  is
214       unspecified unless explicitly stated. The stability level of an undocu‐
215       mented interface is implicitly Private.
216
217
218       The existence of documentation other than the documentation that  is  a
219       component  of  the Solaris product should not be construed to imply any
220       level of stability for interfaces provided by the Solaris product.  The
221       only source of stability level information is Solaris manual pages.
222
223       Committed
224
225           The  intention  of a Committed interface is to enable third parties
226           to develop applications to these interfaces, release them, and have
227           confidence  that they will run on all releases of the product after
228           the one in which the interface was introduced, and within the  same
229           Major  release.  Even  at a Major release, incompatible changes are
230           expected to be rare, and to have strong justifications.
231
232           Interfaces defined and controlled as industry  standards  are  most
233           often  treated  as Committed interfaces. In this case, the control‐
234           ling body and/or public, versioned document is typically noted in a
235           "Standard"  entry in the Attributes table or elsewhere in the docu‐
236           mentation.
237
238           Although a truly exceptional event, incompatible changes are possi‐
239           ble  in  any  release if the associated defect is serious enough as
240           outlined in the Exceptions section of this document or in  a  Minor
241           release  by  following  the End of Feature process. If support of a
242           Committed interface must be discontinued, Sun will attempt to  pro‐
243           vide notification and the stability level will be marked Obsolete.
244
245
246       Uncommitted
247
248           No  commitment  is made about either source or binary compatibility
249           of these interfaces from one Minor release to the next.   Even  the
250           drastic  incompatible change of removal of the interface in a Minor
251           release is possible.   Uncommitted  interfaces  are  generally  not
252           appropriate for use by release-independent products.
253
254           Incompatible  changes to the interface are intended to be motivated
255           by true improvement to the interface which may include ease of  use
256           considerations.  The general expectation should be that Uncommitted
257           interfaces are not  likely  to  change  incompatibly  and  if  such
258           changes  occur  they  will  be small in impact and may often have a
259           mitigation plan.
260
261           Uncommitted interfaces generally fall into  one  of  the  following
262           subcategorizes:
263
264               1.     Interfaces  that  are experimental or transitional. They
265                      are typically used  to  give  outside  developers  early
266                      access to new or rapidly changing technology, or to pro‐
267                      vide an interim solution to a problem where a more  gen‐
268                      eral solution is anticipated.
269
270               2.     Interfaces  whose specification is controlled by an out‐
271                      side body yet Sun expects to make a reasonable effort to
272                      maintain  compatibility with previous releases until the
273                      next Minor release at which time Sun expects to synchro‐
274                      nize with the external specification.
275
276               3.     Interfaces  whose target audience values innovation (and
277                      possibly ease of use) over stability.  This attribute is
278                      often  associated  with  administrative  interfaces  for
279                      higher tier components.
280           For Uncommitted interfaces, Sun makes no claims about either source
281           or binary compatibility from one minor release to another. Applica‐
282           tions developed based on these interfaces may not  work  in  future
283           minor releases.
284
285
286       Volatile
287
288           Volatile interfaces can change at any time and for any reason.
289
290           The  Volatile  interface  stability  level  allows  Sun products to
291           quickly track a fluid,  rapidly  evolving  specification.  In  many
292           cases,  this  is preferred to providing additional stability to the
293           interface, as it may better meet the expectations of the consumer.
294
295           The most common application of this taxonomy level is to interfaces
296           that are controlled by a body other than Sun, but unlike specifica‐
297           tions controlled by standards bodies or Free or Open  Source  Soft‐
298           ware (FOSS) communities which value interface compatibility, it can
299           not be asserted that an incompatible change to the interface speci‐
300           fication  would be exceedingly rare. It may also be applied to FOSS
301           controlled software where it is deemed more important to track  the
302           community  with  minimal  latency  than to provide stability to our
303           customers.
304
305           It also common to apply the Volatile classification level to inter‐
306           faces in the process of being defined by trusted or widely accepted
307           organization.  These are generically referred  to  as  draft  stan‐
308           dards.   An "IETF Internet draft" is a well understood example of a
309           specification under development.
310
311           Volatile can also be applied to experimental interfaces.
312
313           No assertion is made regarding either source or binary  compatibil‐
314           ity  of  Volatile  interfaces  between  any two releases, including
315           patches. Applications containing these  interfaces  might  fail  to
316           function properly in any future release.
317
318
319       Not-an-Interface
320
321           The situation occasionally occurs where there exists an entity that
322           could be inferred to be an interface, but actually is not.   Common
323           examples  are  output from CLIs intended only for human consumption
324           and the exact layout of a GUI.
325
326           This classification is a convenience term to  be  used  to  clarify
327           such  situations  where  such  confusion  is  identified as likely.
328           Failure to apply this term to an entity is not an  indication  that
329           the  entity  is some form of interface.  It only indicates that the
330           potential for confusion was not identified.
331
332
333       Private
334
335           A Private interface is an interface provided  by  a  component  (or
336           product)  intended  only  for  the use of that component. A Private
337           interface might still be visible to or accessible by  other  compo‐
338           nents.  Because  the use of interfaces private to another component
339           carries great stability risks, such  use  is  explicitly  not  sup‐
340           ported.  Components not supplied by Sun Microsystems should not use
341           Private interfaces.
342
343           Most Private interfaces are not documented. It  is  an  exceptional
344           case  when a Private interface is documented. Reasons for document‐
345           ing a Private interface include, but are not limited to, the inten‐
346           tion  that the interface might be reclassified to one of the public
347           stability level classifications in the future or the fact that  the
348           interface is inordinately visible.
349
350
351       Obsolete
352
353           Obsolete  is  a  modifier  that  can appear in conjunction with the
354           above classification levels. The  Obsolete  modifier  indicates  an
355           interface that is "deprecated" and/or no longer advised for general
356           use. An existing interface may be downgraded from some other status
357           (such  as Committed or Uncommitted) by the application of the Obso‐
358           lete modifier to encourage customers to migrate from that interface
359           before it may be removed (or incompatibly changed).
360
361           An  Obsolete  interface is supported in the current release, but is
362           scheduled to be removed in a future (minor) release.  When  support
363           of  an interface is to be discontinued, Sun will attempt to provide
364           notification before  discontinuing  support.  Use  of  an  Obsolete
365           interface may produce warning messages.
366
367
368   Exceptions
369       There  are  rare  instances when it is in the best interest of both Sun
370       and the customer to break the interface stability commitment. The  fol‐
371       lowing  list  contains  the  common,  known  reasons  for the interface
372       provider to violate an interface stability  commitment,  but  does  not
373       preclude others.
374
375           1.     Security  holes  where  the vulnerability is inherent in the
376                  interface.
377
378           2.     Data corruption where the vulnerability is inherent  in  the
379                  interface.
380
381           3.     Standards violations uncovered by a change in interpretation
382                  or enhancement of conformance tests.
383
384           4.     An interface specification which isn't controlled by Sun has
385                  been changed incompatibly and the vast majority of interface
386                  consumers expect the newer interface.
387
388           5.     Not making the incompatible change would be incomprehensible
389                  to  our  customers.   One  example of this would to have not
390                  incompatibly changed pcfs when the DOS 8.3  naming  restric‐
391                  tions were abandoned.
392
393
394       Incompatible  changes  allowed by exception will always be delivered in
395       the "most major" release vehicle possible.  However, often  the  conse‐
396       quences  of  the  vulnerabilities  or contractual branding requirements
397       will force delivery in a patch.
398
399   Compatibility with Earlier Interface Classification Schemes
400       In releases up to and including Solaris 10, a different interface clas‐
401       sification  scheme was used. The following table summarizes the mapping
402       between the old and new classification schemes.
403
404
405
406
407           Old           New                     Comments
408       ──────────────────────────────────────────────────────────────────
409       Standard      Committed     An entry in the attributes table  for
410                                   the  Standard  attribute  type should
411                                   appear.
412       Stable        Committed     Name change.
413       Evolving      Uncommitted   Actual commitments match.
414       Unstable      Uncommitted   Name change.
415       External      Volatile      Name change with expansion of allowed
416                                   usage.
417       Obsolete      (Obsolete)    Was a classification, now a modifier.
418
419
420
421       The  increased importance of Free or Open Source Software motivated the
422       name change from Stable/Unstable to Committed/Uncommitted. Stable  con‐
423       flicted with the common use of the term in FOSS communities.
424
425
426       Ambiguity  in  the  definition  of  Evolving  was causing difficulty in
427       interpretation. As part of the  migration  to  the  new  classification
428       scheme,  many  formerly Evolving interfaces were upgraded to Committed.
429       However, upon encountering the term  Evolving,  Uncommitted  should  be
430       inferred.
431
432   MT-Level
433       Libraries  are  classified into categories that define their ability to
434       support multiple threads. Manual pages containing functions that are of
435       multiple or differing levels describe this in their NOTES or USAGE sec‐
436       tion.
437
438       Safe
439
440           Safe is an attribute of code that  can  be  called  from  a  multi‐
441           threaded  application.  The effect of calling into a Safe interface
442           or a safe code segment is that the  results  are  valid  even  when
443           called  by  multiple threads. Often overlooked is the fact that the
444           result of this Safe interface or safe code segment can have  global
445           consequences  that  affect  all threads. For example, the action of
446           opening or closing a file from one thread is  visible  by  all  the
447           threads  within  a  process.  A  multithreaded  application has the
448           responsibility for using these interfaces in a safe  manner,  which
449           is  different  from whether or not the interface is Safe. For exam‐
450           ple, a multithreaded application that closes a file that  is  still
451           in  use  by  other  threads within the application is not using the
452           close(2) interface safely.
453
454
455       Unsafe
456
457           An Unsafe library contains global and static data that is not  pro‐
458           tected.  It  is not safe to use unless the application arranges for
459           only one thread at time  to  execute  within  the  library.  Unsafe
460           libraries  might  contain functions that are Safe; however, most of
461           the library's functions are unsafe to call. Some functions that are
462           Unsafe  have  reentrant  counterparts  that  are MT-Safe. Reentrant
463           functions are designated by the _r suffix appended to the  function
464           name.
465
466
467       MT-Safe
468
469           An  MT-Safe  library is fully prepared for multithreaded access. It
470           protects its global and static data with locks, and can  provide  a
471           reasonable amount of concurrency. A library can be safe to use, but
472           not MT-Safe. For example, surrounding an entire library with a mon‐
473           itor  makes  the library Safe, but it supports no concurrency so it
474           is not considered MT-Safe. An MT-Safe library must permit a reason‐
475           able  amount  of concurrency. (This definition's purpose is to give
476           precision to what is meant when a library is described as Safe. The
477           definition  of  a Safe library does not specify if the library sup‐
478           ports concurrency. The MT-Safe definition makes it clear  that  the
479           library  is Safe, and supports some concurrency. This clarifies the
480           Safe definition, which can mean anything from being single threaded
481           to being any degree of multithreaded.)
482
483
484       Async-Signal-Safe
485
486           Async-Signal-Safe  refers  to particular library functions that can
487           be safely called from a signal handler. A thread that is  executing
488           an  Async-Signal-Safe  function  will  not  deadlock with itself if
489           interrupted by a signal. Signals are only  a  problem  for  MT-Safe
490           functions that acquire locks.
491
492           Async-Signal-Safe  functions are also MT-Safe. Signals are disabled
493           when locks are acquired in Async-Signal-Safe functions. These  sig‐
494           nals prevent a signal handler that might acquire the same lock from
495           being called.
496
497
498       MT-Safe with Exceptions
499
500           See the NOTES or USAGE sections of these pages for a description of
501           the exceptions.
502
503
504       Safe with Exceptions
505
506           See the NOTES or USAGE sections of these pages for a description of
507           the exceptions.
508
509
510       Fork-Safe
511
512           The fork(2) function replicates only  the  calling  thread  in  the
513           child  process. The fork1(2) function exists for compatibility with
514           the past and is synonymous with fork(). If a thread other than  the
515           one  performing  the  fork  holds a lock when fork() is called, the
516           lock will still be held in the child process but there will  be  no
517           lock  owner  since  the  owning  thread was not replicated. A child
518           calling a function that attempts to acquire the lock will  deadlock
519           itself.
520
521           When  fork() is called, a Fork-Safe library arranges to have all of
522           its internal locks held only by the  thread  performing  the  fork.
523           This  is  usually  accomplished  with  pthread_atfork(3C), which is
524           called when the library is initialized.
525
526           The forkall(2) function provides the capability for the  rare  case
527           when  a process needs to replicate all of its threads when perform‐
528           ing  a  fork.  No  pthread_atfork()  actions  are  performed   when
529           forkall()  is  called.  There  are  dangers associated with calling
530           forkall(). If some threads in a process are performing  I/O  opera‐
531           tions  when another thread calls forkall(), they will continue per‐
532           forming the same I/O operations in both the parent and  child  pro‐
533           cesses,  possibly causing data corruption. For this and other race-
534           condition reasons, the use of forkall() is discouraged.
535
536           In all Solaris releases prior to Solaris 10, the behavior of fork()
537           depended  on  whether  or  not  the  application  was  linked  with
538           -lpthread  (POSIX  threads,  see  standards(5)).  If  linked   with
539           -lpthread,  fork()  behaved like fork1(); otherwise it behaved like
540           forkall(). To  avoid  any  confusion  concerning  the  behavior  of
541           fork(),  applications can specifically call fork1() or forkall() as
542           appropriate.
543
544
545       Cancel-Safety
546
547           If a multithreaded application uses  pthread_cancel(3C)  to  cancel
548           (that  is, kill) a thread, it is possible that the target thread is
549           killed while holding a resource, such as a lock or  allocated  mem‐
550           ory.  If  the thread has not installed the appropriate cancellation
551           cleanup  handlers  to  release  the  resources  appropriately  (see
552           pthread_cancel(3C)),  the  application is "cancel-unsafe", that is,
553           it is not safe with respect to cancellation.  This  unsafety  could
554           result in deadlocks due to locks not released by a thread that gets
555           cancelled, or resource leaks; for example, memory not  being  freed
556           on  thread  cancellation.  All  applications  that use pthread_can‐
557           cel(3C) should ensure that they operate in a  Cancel-Safe  environ‐
558           ment.  Libraries  that  have  cancellation points and which acquire
559           resources such as locks or allocate memory dynamically,  also  con‐
560           tribute to the cancel-unsafety of applications that are linked with
561           these libraries.  This  introduces  another  level  of  safety  for
562           libraries  in a multithreaded program: Cancel-Safety. There are two
563           sub-categories of Cancel-Safety: Deferred-Cancel-Safety, and  Asyn‐
564           chronous-Cancel-Safety.   An   application   is  considered  to  be
565           Deferred-Cancel-Safe when it is Cancel-Safe for threads whose  can‐
566           cellation  type  is PTHREAD_CANCEL_DEFERRED. An application is con‐
567           sidered to be Asynchronous-Cancel-Safe when it is  Cancel-Safe  for
568           threads  whose  cancellation  type  is PTHREAD_CANCEL_ASYNCHRONOUS.
569           Deferred-Cancel-Safety is easier to achieve than  Asynchronous-Can‐
570           cel-Safety,  since a thread with the deferred cancellation type can
571           be cancelled only at well-defined cancellation  points,  whereas  a
572           thread  with  the  asynchronous  cancellation type can be cancelled
573           anywhere. Since all threads are created  by  default  to  have  the
574           deferred  cancellation  type,  it might never be necessary to worry
575           about asynchronous cancel safety. Most applications  and  libraries
576           are  expected  to always be Asynchronous-Cancel-Unsafe. An applica‐
577           tion which is  Asynchronous-Cancel-Safe  is  also,  by  definition,
578           Deferred-Cancel-Safe.
579
580
581   Standard
582       Many  interfaces are defined and controlled as industry standards. When
583       this is the case, the controlling body and/or public,  versioned  docu‐
584       ment is noted in this section.
585
586
587       Programmers  producing  portable applications should rely on the inter‐
588       face descriptions present in the standard or specification to which the
589       application  is  intended  to  conform,  rather  than  the  manual page
590       descriptions of interfaces based upon a public standard. When the stan‐
591       dard  or  specification  allows alternative implementation choices, the
592       manual page usually only describes the alternative implemented by  Sun.
593       The  manual  page  also describes any compatible extensions to the base
594       definition of Standard interfaces provided by Sun.
595
596
597       No endorsement of the referenced controlling body or document should be
598       inferred  by  its  presence as a "Standard" entry. The controlling body
599       may be a very formal organization, as in ISO or ANSII, a  less  formal,
600       but generally accepted organization such as IETF, or as informal as the
601       sole contributor in the case of FOSS (Free or Open Source Software).
602

SEE ALSO

604       uname(1), pkgadd(1M), Intro(3), standards(5)
605
606
607
608SunOS 5.11                        29 Jul 2007                    attributes(5)
Impressum