Print this page 
Minor markup tweaks (Sy instead of Nm).
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man5/mdoc.5
          +++ new/usr/src/man/man5/mdoc.5
↓ open down ↓ 385 lines elided ↑ open up ↑ 
 386  386  Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 387  387  UTF-8 and GB2312.
 388  388  .Pp
 389  389  Generally there will be some limitations that are fairly standard.  See
 390  390  .Xr standards 5 for more information about some of these.  Most interfaces
 391  391  should support at least UTF-8 in addition to ASCII.
 392  392  .It Em INTERFACE STABILITY
 393  393  Indicates the level of commitment to the interface. Interfaces can be described
 394  394  with in the following ways:
 395  395  .Bl -tag -width Ds
 396      -.It Nm Standard
      396 +.It Sy Standard
 397  397  Indicates that the interface is defined by one or more standards bodies.
 398  398  Generally, changes to the interface will be carefully managed to conform
 399  399  to the relevant standards.  These interfaces are generally the most suitable
 400  400  for use in portable programs.
 401      -.It Nm Committed
      401 +.It Sy Committed
 402  402  Indicates that the interface is intended to be preserved for the long-haul, and
 403  403  will rarely, if ever change, and never without notification (barring
 404  404  extraordinary and extenuating circumstances). These interfaces are
 405  405  preferred over other interfaces with the exeception of
 406      -.Nm Standard
      406 +.Sy Standard
 407  407  interfaces.
 408      -.It Nm Uncommitted
      408 +.It Sy Uncommitted
 409  409  Indicates that the interface may change.  Generally, changes to these interfaces
 410  410  should be infrequent, and some effort will be made to address compatibility
 411  411  considerations when changing or removing such interfaces.  However, there is
 412  412  no firm commitment to the preservation of the interface.  Most often this
 413  413  is applied to interfaces where operational experience with the interface
 414  414  is still limited and some need to change may be anticipated.
 415  415  .Pp
 416  416  Consumers should expect to revalidate any
 417      -.Nm Uncommitted
      417 +.Sy Uncommitted
 418  418  interfaces when crossing release boundaries.  Products intended for
 419  419  use on many releases or intended to support compatibility with future
 420  420  releases should avoid these interfaces.
 421      -.It Nm Volatile
      421 +.It Sy Volatile
 422  422  The interface can change at any time for any reason. Often this relates to
 423  423  interfaces that are part of external software components that are still evolving
 424  424  rapidly.  Consumers should not expect that the interface (either binary or
 425  425  source level) will be unchanged from one release to the next.
 426      -.It Nm Not-an-Interface
      426 +.It Sy Not-an-Interface
 427  427  Describes something that is specifically not intended for programmatic
 428  428  consumption.  For example, specific human-readable output, or the layout
 429  429  of graphical items on a user interface, may be described this way.  Generally
 430  430  programmatic alternatives to these will be available, and should be used
 431  431  when programmatic consumption is needed.
 432      -.It Nm Private
      432 +.It Sy Private
 433  433  This is an internal interface.  Generally these interfaces should only be
 434  434  used within the project, and should not be used by other programs or modules.
 435  435  The interface can and will change without notice as the project needs, at
 436  436  any time.
 437  437  .Pp
 438  438  Most often, Private interfaces will lack any documentation whatsoever, and
 439  439  generally any undocumented interface can be assumed to be Private.
 440      -.It Nm Obsolete
      440 +.It Sy Obsolete
 441  441  The interface is not intended for use in new projects or programs, and may
 442  442  be removed at a future date.  The
 443      -.Nm Obsolete
      443 +.Sy Obsolete
 444  444  word is a modifier that can
 445  445  be applied to other commitment levels. For example an
 446      -.Nm Obsolete Committed
      446 +.Sy Obsolete Committed
 447  447  interface is unlikely to be removed or changed, but nonetheless new use
 448  448  is discouraged (perhaps a better newer alternative is present).
 449  449  .El
 450  450  .It Em MT-LEVEL
 451  451  This section describes considerations for the interface when used within
 452  452  programs that use multiple threads.  More discussion of these considerations
 453  453  is made in the MT-Level section of
 454  454  .Xr attributes 5 .
 455  455  The interface can be described in the following ways.
 456  456  .Bl -tag -width Ds
 457      -.It Nm Safe
      457 +.It Sy Safe
 458  458  Indicates the interface is safe for use within multiple threads.  There
 459  459  may be additional caveats that apply, in which case those will be
 460  460  described.  Note that some interfaces have semantics which may affect
 461  461  other threads, but these should be an intrinsic part of the interface
 462  462  rather than an unexpected side effect.  For example, closing a file in
 463  463  one thread will cause that file to be closed in all threads.
 464      -.It Nm Unsafe
      464 +.It Sy Unsafe
 465  465  Indicates the interface is unsuitable for concurrent use within multiple
 466  466  threads.  A threaded application may still make use of the interface, but
 467  467  will be required to provide external synchronization means to ensure that
 468  468  only a single thread calls the interface at a time.
 469      -.It Nm MT-Safe
      469 +.It Sy MT-Safe
 470  470  Indicates that the interface is not only safe for concurrent use, but is
 471  471  designed for such use.  For example, a
 472      -.Nm Safe
      472 +.Sy Safe
 473  473  interface may make use of a global lock to provide safety, but at reduced
 474  474  internal concurrency, whereas an
 475      -.Nm MT-Safe
      475 +.Sy MT-Safe
 476  476  interface will be designed to be efficient even when used concurrently.
 477      -.It Nm Async-Signal-Safe
      477 +.It Sy Async-Signal-Safe
 478  478  Indicates that the library is safe for use within a signal handler.  An
 479      -.Nm MT-Safe
      479 +.Sy MT-Safe
 480  480  interface can be made
 481      -.Nm Async-Signal-Safe
      481 +.Sy Async-Signal-Safe
 482  482  by ensuring that it blocks signals when acquiring locks.
 483      -.It Nm Safe with Exections
      483 +.It Sy Safe with Exections
 484  484  As for
 485      -.Nm Safe
      485 +.Sy Safe
 486  486  but with specific exceptions noted.
 487      -.It Nm MT-Safe with Exections
      487 +.It Sy MT-Safe with Exections
 488  488  As for
 489      -.Nm MT-Safe
      489 +.Sy MT-Safe
 490  490  but with specific exceptions noted.
 491  491  .El
 492  492  .It Em SECURITY
 493  493  Documents any security precautions that operators should consider.
 494  494  .It Em SEE ALSO
 495  495  References other manuals with related topics.
 496  496  This section should exist for most manuals.
 497  497  Cross-references should conventionally be ordered first by section, then
 498  498  alphabetically.
 499  499  .Pp
↓ open down ↓ 2708 lines elided ↑ open up ↑ 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX