1attributes(5) Standards, Environments, and Macros attributes(5)
2
6 attributes, architecture, availability, CSI, stability, MT-Level, stan‐
7 dard - attributes of interfaces
8
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 ┌─────────────────────────────┬─────────────────────────────┐
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 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 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 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 For practical reasons, however, this independence is not absolute. Cer‐
56 tain assumptions are still applied to the current CSI implementation:
57 o File code is a superset of ASCII.
59 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 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 o Process code (wchar_t values) is implementation dependent
70 and can change over time or between implementations or
71 between locales.
72 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 o User names, group name, and passwords
78 o System name
80 o Names of printers and special devices
82 o Names of terminals (/dev/tty*)
84 o Process ID numbers
86 o Message queues, semaphores, and shared memory labels.
88 o The following may be composed of ISO Latin-1 or EUC
90 characters:
91 o File names
93 o Directory names
95 o Command names
97 o Shell variables and environmental variable names
99 o Mount points for file systems
101 o NIS key names and domain names
103 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 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 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 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 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 "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 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 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 In the context of interface stability, update releases (occasionally
185 referred to as patch releases) should be considered equivalent to Micro
186 Releases.
187 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 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 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 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 Committed
224 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 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 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 Uncommitted
247 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 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 Uncommitted interfaces generally fall into one of the following
262 subcategorizes:
263 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 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 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 Volatile
287 Volatile interfaces can change at any time and for any reason.
289 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 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 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 Volatile can also be applied to experimental interfaces.
312 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 Not-an-Interface
320 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 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 Private
334 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 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 Obsolete
352 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 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 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 1. Security holes where the vulnerability is inherent in the
376 interface.
377 2. Data corruption where the vulnerability is inherent in the
379 interface.
380 3. Standards violations uncovered by a change in interpretation
382 or enhancement of conformance tests.
383 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 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 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 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 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 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 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 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 Safe
439 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 Unsafe
456 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 MT-Safe
468 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 Async-Signal-Safe
485 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 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 MT-Safe with Exceptions
499 See the NOTES or USAGE sections of these pages for a description of
501 the exceptions.
502 Safe with Exceptions
505 See the NOTES or USAGE sections of these pages for a description of
507 the exceptions.
508 Fork-Safe
511 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 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 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 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 Cancel-Safety
546 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 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 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 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
604 uname(1), pkgadd(1M), Intro(3), standards(5)
605SunOS 5.11 29 Jul 2007 attributes(5)