Changeset d1a859c in rtems


Ignore:
Timestamp:
08/25/98 20:54:47 (24 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
142f6a5
Parents:
d5ef5bd1
Message:

Cleaned up formatting.

Added notes on background and operations sections.

Added NOTE to indicate the feature flag defined.

Location:
doc/new_chapters
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/adminiface.t

    rd5ef5bd1 rd1a859c  
    1111@section Introduction
    1212
    13 The
    14 administration interface manager is ...
     13The administration interface manager provides a portable
     14interface for some system administrative functions.
     15The capabilities in this manager were defined in the POSIX
     161003.1h/D3 proposed standard titled @b{Services for Reliable,
     17Available, and Serviceable Systems}.
    1518
    1619The directives provided by the administration interface manager are:
     
    2124
    2225@section Background
     26
     27@subsection admin_args Structure
     28
     29@example
     30put structure here
     31@end example
     32
     33@table @b
     34@item admin_type
     35This field ...
     36
     37@table @b
     38@item ADMIN_AUTOBOOT
     39This field ...
     40
     41@item ADMIN_HALT
     42This field ...
     43
     44@item ADMIN_FAST
     45This field ...
     46
     47@item ADMIN_IMMEDIATE
     48This field ...
     49
     50@item ADMIN_ALTSYSTEM
     51This field ...
     52
     53@item ADMIN_ALTCONFIG
     54This field ...
     55
     56@item ADMIN_SYSDUMP
     57This field ...
     58
     59@item ADMIN_INIT
     60This field ...
     61
     62
     63@end table
     64
     65@item admin_data
     66This field ...
     67
     68@end table
    2369
    2470@section Operations
     
    3985@example
    4086int admin_shutdown(
    41   struct admin_args_   *args[],
    42   size_t                nargs
     87  struct admin_args   *args[],
     88  size_t               nargs
    4389);
    4490@end example
     
    5399@item EINVAL
    54100An invalid argument was passed to the function call.
    55 @item ENOSYS
    56 The function admin_shutdown() is not supported by this implementation.
     101
    57102@item EPERM
    58103The caller does not have appropriate permission for shutting down the
     
    63108@subheading DESCRIPTION:
    64109
    65 
    66 If @code{_POSIX_ADMIN} is defined:
    67 
    68    The @code{admin_shutdown} function restarts the system.  The
    69    @code{args} argument specifies alternate or optional behavior
    70    for the @code{admin_shutdown} function.  The @code{admin_type}
    71    member of each element of the @code{args} array specifies the
    72    optional behavior to be performed.  There are som @code{admin_types}
    73    values that may provoke unspecified behavior.  The @code{nargs}
    74    argument specifies the length of the @code{args} array.
    75 
    76 Otherwise:
    77 
    78    The @code{admin_shutdown} function shall fail.
     110The @code{admin_shutdown} function restarts the system.  The
     111@code{args} argument specifies alternate or optional behavior
     112for the @code{admin_shutdown} function.  The @code{admin_type}
     113member of each element of the @code{args} array specifies the
     114optional behavior to be performed.  There are som @code{admin_types}
     115values that may provoke unspecified behavior.  The @code{nargs}
     116argument specifies the length of the @code{args} array.
    79117
    80118@subheading NOTES:
    81119
     120The @code{_POSIX_ADMIN} feature flag is defined to indicate
     121this service is available.
  • doc/new_chapters/confspace.t

    rd5ef5bd1 rd1a859c  
    1111@section Introduction
    1212
    13 The
    14 configuration space manager is ...
     13The configuration space manager provides a portable
     14interface for manipulating configuration data.
     15The capabilities in this manager were defined in the POSIX
     161003.1h/D3 proposed standard titled @b{Services for Reliable,
     17Available, and Serviceable Systems}.
    1518
    1619The directives provided by the configuration space manager are:
     
    6568@item EPERM
    6669The caller does not have the appropriate privilege.
     70
    6771@item EACCES
    6872Search permission is denied for a component of the path prefix.
     73
    6974@item EEXIST
    7075The file specified by the file argument does not exist
     76
    7177@item ENAMETOOLONG
    7278A component of a pathname exceeded @code{NAME_MAX} characters,
    7379or an entire path name exceed @code{PATH_MAX} characters while
    7480@code{_POSIX_NO_TRUNC} is in effect.
     81
    7582@item ENOENT
    7683A component of cfgpath does not exist.
     84
    7785@item ENOTDIR
    7886A component of the file path prefix is not a directory.
     87
    7988@item EBUSY
    8089The configuration space defined by file is already mounted.
     90
    8191@item EINVAL
    8292The notification argument specifies an invalid log facility.
    83 @item ENOSYS
    84 The cfg_mount() function is not supported by this implementation.
    85 
    86 @end table
    87 
    88 @subheading DESCRIPTION:
    89 
    90 If @code{_POSIX_CFG} is defined:
    91 
    92    The @code{cfg_mount} function maps a configuration space defined
    93    by the file identified by the the @code{file} argument.  The
    94    distinguished node of the mapped configuration space shall be
    95    mounted in the active space at the point identified bt the
    96    @code{cfgpath} configuration pathname.
    97 
    98    The @code{notification} argument specifies how changes to the
    99    mapped configuration space shall be communicated to the application.
    100    If the @code{notification} argument is NULL, no notification shall
    101    be performed for the mapped configuration space.  If the Event
    102    Logging option is defined, the notification argument defines the
    103    facility to which changes in the mapped configuration space shall
    104    be logged.  Otherwise, the @code{notification} argument shall
    105    specify an implementation defined method of notifying the application
    106    of changes to the mapped configuration space.
    107 
    108 Otherwise:
    109 
    110    The @code{cfg_mount} function shall fail.
     93
     94@end table
     95
     96@subheading DESCRIPTION:
     97
     98The @code{cfg_mount} function maps a configuration space defined
     99by the file identified by the the @code{file} argument.  The
     100distinguished node of the mapped configuration space shall be
     101mounted in the active space at the point identified bt the
     102@code{cfgpath} configuration pathname.
     103
     104The @code{notification} argument specifies how changes to the
     105mapped configuration space shall be communicated to the application.
     106If the @code{notification} argument is NULL, no notification shall
     107be performed for the mapped configuration space.  If the Event
     108Logging option is defined, the notification argument defines the
     109facility to which changes in the mapped configuration space shall
     110be logged.  Otherwise, the @code{notification} argument shall
     111specify an implementation defined method of notifying the application
     112of changes to the mapped configuration space.
    111113
    112114@subheading NOTES:
     115
     116The @code{_POSIX_CFG} feature flag is defined to indicate
     117this service is available.
    113118
    114119@page
     
    133138@item EPERM
    134139The caller does not have the appropriate privileges.
     140
    135141@item EACCES
    136142Search permission is denied for a component of the path prefix.
     143
    137144@item ENOENT
    138145A component of cfgpath does not exist.
     146
    139147@item ENAMETOOLONG
    140148A component of a pathname exceeded @code{NAME_MAX} characters,
    141149or an entire path name exceed @code{PATH_MAX} characters while
    142150@code{_POSIX_NO_TRUNC} is in effect.
     151
    143152@item EINVAL
    144153The requested node is not the distinguished node of a mounted
    145154configuration space.
     155
    146156@item EBUSY
    147157One or more processes has an open configuration traversal
    148158stream for the configuration space whose distinguished node is
    149159referenced by the cfgpath argument.
    150 @item ENOSYS
    151 The cfg_umount function is not supported by this implementation.
     160
    152161@item ELOOP
    153162A node appears more than once in the path specified by the
    154163cfg_path argument
     164
    155165@item ELOOP
    156166More than @code{SYMLOOP_MAX} symbolic links were encountered during
     
    161171@subheading DESCRIPTION:
    162172
    163 If @code{_POSIX_CFG} is defined:
    164 
    165    The @code{cfg_umount} function unmaps the configuration space whose
    166    distinguished node is mapped in the active space at the location defined
    167    by @code{cfgpatah} configuration pathname.  All system resources
    168    allocated for this configuration space should be deallocated.
    169 
    170 Otherwise:
    171 
    172    The @code{cfg_umount} function shall fail.
     173The @code{cfg_umount} function unmaps the configuration space whose
     174distinguished node is mapped in the active space at the location defined
     175by @code{cfgpatah} configuration pathname.  All system resources
     176allocated for this configuration space should be deallocated.
    173177
    174178@subheading NOTES:
     179
     180The @code{_POSIX_CFG} feature flag is defined to indicate
     181this service is available.
    175182
    176183@page
     
    199206or an entire path name exceed @code{PATH_MAX} characters while
    200207@code{_POSIX_NO_TRUNC} is in effect.
     208
    201209@item ENOENT
    202210A compent of the path prefix does not exist.
     211
    203212@item EACCES
    204213Search permission is denied for a component of the path prefix.
     214
    205215@item ELOOP
    206216Too many symbolic links were encountered in translating the
    207217pathname.
     218
    208219@item EPERM
    209220The calling process does not have the appropriate privilege.
     221
    210222@item EEXIST
    211223The named node exists.
     224
    212225@item EINVAL
    213226The value of mode is invalid.
     227
    214228@item EINVAL
    215229The value of type is invalid.
    216 @item ENOSYS
    217 The function cfg_mknod() is not supported by this implementation.
     230
    218231@item ELOOP
    219232A node appears more than once in the path specified by the
    220233cfg_path argument
     234
    221235@item ELOOP
    222236More than @code{SYMLOOP_MAX} symbolic links were encountered during
    223237resolution of the cfgpath argument.
     238
    224239@item EROFS
    225240The named node resides on a read-only configuration space.
     
    229244@subheading DESCRIPTION:
    230245
    231 If @code{_POSIX_CFG} is defined:
    232 
    233    The @code{cfg_mknod} function creates a new node in the configuration
    234    space which contains the pathname prefix of @code{cfgpath}.  T he node
    235    name shall be defined by the pathname suffix of @code{cfgpath}.  The
    236    node name shall be defined by the pathname suffix of @code{cfgpath}.
    237    The node permissions shall be specified by the value of @code{mode}.
    238    The node type shall be specified by the value of @code{type}.
    239 
    240 Otherwise:
    241 
    242    The @code{cfg_mknod} function shall fail.
     246The @code{cfg_mknod} function creates a new node in the configuration
     247space which contains the pathname prefix of @code{cfgpath}.  T he node
     248name shall be defined by the pathname suffix of @code{cfgpath}.  The
     249node name shall be defined by the pathname suffix of @code{cfgpath}.
     250The node permissions shall be specified by the value of @code{mode}.
     251The node type shall be specified by the value of @code{type}.
    243252
    244253@subheading NOTES:
     254
     255The @code{_POSIX_CFG} feature flag is defined to indicate
     256this service is available.
    245257
    246258@page
     
    268280or an entire path name exceed @code{PATH_MAX} characters while
    269281@code{_POSIX_NO_TRUNC} is in effect.
     282
    270283@item ENOENT
    271284A component of cfgpath does not exist.
     285
    272286@item EACCES
    273287Search permission is denied for a component of the path prefix.
     288
    274289@item EPERM
    275290The calling process does not have the appropriate priviledges.
    276 @item ENOSYS
    277 The function cfg_get() is not supported by this implementation
     291
    278292@item ELOOP
    279293A node appears more than once in the path specified by the
    280294cfg_path argument
     295
    281296@item ELOOP
    282297More than @code{SYMLOOP_MAX} symbolic links were encountered during
     
    287302@subheading DESCRIPTION:
    288303
    289 If @code{_POSIX_CFG} is defined:
    290 
    291    The @code{cfg_get} function stores the value attribute of the
    292    configuration node identified by @code{cfgpath}, into the buffer
    293    described by the @code{value} pointer.
    294 
    295 Otherwise:
    296 
    297    The @code{cfg_get} function shall fail.
    298 
     304The @code{cfg_get} function stores the value attribute of the
     305configuration node identified by @code{cfgpath}, into the buffer
     306described by the @code{value} pointer.
    299307
    300308@subheading NOTES:
     309
     310The @code{_POSIX_CFG} feature flag is defined to indicate
     311this service is available.
    301312
    302313@page
     
    324335or an entire path name exceed @code{PATH_MAX} characters while
    325336@code{_POSIX_NO_TRUNC} is in effect.
     337
    326338@item ENOENT
    327339A component of cfgpath does not exist
     340
    328341@item EACCES
    329342Search permission is denied for a component of the path prefix.
     343
    330344@item EPERM
    331345The calling process does not have the appropriate privilege.
    332 @item ENOSYS
    333 The function cfg_set() is not supported by this implementation.
     346
    334347@item ELOOP
    335348A node appears more than once in the path specified by the
    336349cfg-path argument.
     350
    337351@item ELOOP
    338352More than @code{SYMLOOP_MAX} symbolic links were encountered during
     
    343357@subheading DESCRIPTION:
    344358
    345 If @code{_POSIX_CFG} is defined:
    346 
    347    The @code{cfg_set} function stores the value specified by the
    348    @code{value} argument in the configuration node defined by the
    349    @code{cfgpath} argument.
    350 
    351 Otherwise:
    352 
    353    The @code{cfg_set} function shall fail.
    354 
     359The @code{cfg_set} function stores the value specified by the
     360@code{value} argument in the configuration node defined by the
     361@code{cfgpath} argument.
    355362
    356363@subheading NOTES:
     364
     365The @code{_POSIX_CFG} feature flag is defined to indicate
     366this service is available.
    357367
    358368@page
     
    380390or an entire path name exceed @code{PATH_MAX} characters while
    381391@code{_POSIX_NO_TRUNC} is in effect.
     392
    382393@item ENOENT
    383394A component of either path prefix does not exist.
     395
    384396@item EACCES
    385397A component of either path prefix denies search permission.
     398
    386399@item EACCES
    387400The requested link requires writing in a node with a mode that
    388401denies write permission.
     402
    389403@item ENOENT
    390404The node named by src does not exist.
     405
    391406@item EEXIST
    392407The node named by dest does exist.
     408
    393409@item EPERM
    394410The calling process does not have the appropriate privilege to
    395411modify the node indicated by the src argument.
     412
    396413@item EXDEV
    397414The link named by dest and the node named by src are from different
    398415configuration spaces.
     416
    399417@item ENOSPC
    400418The node in which the entry for the new link is boeing placed
    401419cannot be extended because there is no space left on the
    402420configuration space containing the node.
     421
    403422@item EIO
    404423An I/O error occurred while reading from or writing to the
    405424configuration space to make the link entry.
     425
    406426@item EROFS
    407427The requested link requires writing in a node on a read-only
    408428configuration space.
    409 @item ENOSYS
    410 The function cfg_link() is not supported by this implementation.
     429
    411430@item ELOOP
    412431A node appears more than once in the path specified by the
    413432cfg-path argument.
     433
    414434@item ELOOP
    415435More than @code{SYMLOOP_MAX} symbolic links were encountered during
     
    420440@subheading DESCRIPTION:
    421441
    422 If @code{_POSIX_CFG} is defined:
    423 
    424    The @code{src} and @code{dest}arguments point to pathnnames which
    425    name existing nodes.  The @code{cfg_link} function shall atomically
    426    create a link between specified nodes, and increment by one the link
    427    count of the node specified by the @code{src} argument.
    428 
    429    If the @code{cfg_lin} function fails, no link shall be created, and
    430    the link count of the node shall remain unchanged by this function
    431    call.
    432 
    433    This implementation may require that the calling process has permission
    434    to access the specified nodes.
    435 
    436 Otherwise:
    437 
    438    The @code{cfg_link} functioin shall fail.
     442The @code{src} and @code{dest}arguments point to pathnnames which
     443name existing nodes.  The @code{cfg_link} function shall atomically
     444create a link between specified nodes, and increment by one the link
     445count of the node specified by the @code{src} argument.
     446
     447If the @code{cfg_link} function fails, no link shall be created, and
     448the link count of the node shall remain unchanged by this function
     449call.
     450
     451This implementation may require that the calling process has permission
     452to access the specified nodes.
    439453
    440454@subheading NOTES:
     455
     456The @code{_POSIX_CFG} feature flag is defined to indicate
     457this service is available.
    441458
    442459@page
     
    462479A component of a pathname exceeded @code{NAME_MAX} characters,
    463480or an entire path name exceed @code{PATH_MAX} characters.
     481
    464482@item ENOENT
    465483The named  node does not exist.
     484
    466485@item EACCES
    467486Search permission is denied on the node containing the link to
    468487be removed.
     488
    469489@item EACCES
    470490Write permission is denied on the node containing the link to
    471491be removed.
     492
    472493@item ENOENT
    473494A component of cfgpath does not exist.
     495
    474496@item EPERM
    475497The calling process does not have the appropriate priviledge to
    476498modify the node indicated by the path prefix of the cfgpath
    477499argument.
     500
    478501@item EBUSY
    479502The node to be unlinked is the distinguished node of a mounted
    480503configuration space.
     504
    481505@item EIO
    482506An I/O error occurred while deleting the link entry or deallocating
    483507the node.
     508
    484509@item EROFS
    485510The named node resides in a read-opnly configuration space.
    486 @item ENOSYS
    487 The function cfg_unlink() is not supported by this implementation.
     511
    488512@item ELOOP
    489513A node appears more than once in the path specified by the
    490514cfg-path argument.
     515
    491516@item ELOOP
    492517More than @code{SYMLOOP_MAX} symbolic links were encountered during
     
    497522@subheading DESCRIPTION:
    498523
    499 If @code{_POSIX_CFG} is defined:
    500 
    501    The @code{cfg_unlink} function removes the link between the node
    502    specified by the @code{cfgpath} path prefix and the parent node
    503    specified by @code{cfgpaht}, and shall decrement the link count
    504    of the @code{cfgpath} node.
    505 
    506    When the link count of the node becomes zero, the space occupied
    507    by the node shall be freed and the node shall no longer be accessible.
    508 
    509 Otherwise:
    510 
    511    The @code{unlink} function shall fail.
     524The @code{cfg_unlink} function removes the link between the node
     525specified by the @code{cfgpath} path prefix and the parent node
     526specified by @code{cfgpaht}, and shall decrement the link count
     527of the @code{cfgpath} node.
     528
     529When the link count of the node becomes zero, the space occupied
     530by the node shall be freed and the node shall no longer be accessible.
    512531
    513532@subheading NOTES:
     533
     534The @code{_POSIX_CFG} feature flag is defined to indicate
     535this service is available.
    514536
    515537@page
     
    537559@item EACCES
    538560Search permission is denied for any component of a pathname.
     561
    539562@item ELOOP
    540563A loop exists in symbolic links encountered during resolution
    541564of a pathname.
     565
    542566@item ENAMETOOLONG
    543567The length of a pathname exceeds @code{PATH_MAX}, or a pathname
    544568component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}
     569
    545570@item ENOENT
    546571The pathname argument is an empty string or the named node
    547572does not exist.
     573
    548574@item EINVAL
    549575Either both or neither of CFG_LOGICAL and CFG_PHYSICAL are
    550576specified by the options argument ???????????
     577
    551578@item ENOMEM
    552579Not enough memory is available to create the necessary structures.
    553 @item ENOSYS
    554 The function cfg_open() is not supported by this implementation.
     580
    555581@item ELOOP
    556582More than @code{SYMLOOP_MAX} symbolic links were encountered during
    557583resolution of the pathnames argument.
     584
    558585@item ENAMETOOLONG
    559586As a result of encountering a symbolic link in resolution of the
     
    565592@subheading DESCRIPTION:
    566593
    567 If @code{_POSIX_CFG} is defined:
    568 
    569    The @code{cfg_open} function shall open a configuration traversal stream
    570    rooted in the configuration nodes name by the @code{pathnames} argument.
    571    It shall store a pointer to a CFG object that represents that stream at
    572    the location identified the @code{cfgstream} pointer.  The @code{pathnames}
    573    argument is an array of character pointers to NULL-terminated strings.
    574    The last member of this array shall be a NULL pointer.
    575 
    576    The value of @code{options} is the bitwise inclusive OR of values from the
    577    following lists.  Applications shall supply exactly one of the first two
    578    values below in @code{options}.
    579 
    580       CFG_LOGICAL   - When symbolic links referencing existing nodes are
    581                       encountered during the traversal, the @code{cfg_info}
    582                       field of the returned CFGENT structure shall describe
    583                       the target node pointed to by the link instead of the
    584                       link itself, unless the target node does not exist.
    585                       If the target node has children, the pre-order return,
    586                       followed by the return of structures referenceing all of
    587                       its descendants, followed by a post-order return, shall
    588                       be done.
     594The @code{cfg_open} function shall open a configuration traversal stream
     595rooted in the configuration nodes name by the @code{pathnames} argument.
     596It shall store a pointer to a CFG object that represents that stream at
     597the location identified the @code{cfgstream} pointer.  The @code{pathnames}
     598argument is an array of character pointers to NULL-terminated strings.
     599The last member of this array shall be a NULL pointer.
     600
     601The value of @code{options} is the bitwise inclusive OR of values from the
     602following lists.  Applications shall supply exactly one of the first two
     603values below in @code{options}.
     604
     605@table @b
     606
     607@item CFG_LOGICAL
     608When symbolic links referencing existing nodes are
     609encountered during the traversal, the @code{cfg_info}
     610field of the returned CFGENT structure shall describe
     611the target node pointed to by the link instead of the
     612link itself, unless the target node does not exist.
     613If the target node has children, the pre-order return,
     614followed by the return of structures referenceing all of
     615its descendants, followed by a post-order return, shall
     616be done.
    589617                   
    590       CFG_PHYSICAL  - When symbolic links are encountered during the traversal,
    591                       the @code{cfg_info} field shall describe the symbolic
    592                       link.
     618@item CFG_PHYSICAL
     619When symbolic links are encountered during the traversal,
     620the @code{cfg_info} field shall describe the symbolic
     621link.
     622
     623@end table
    593624                   
    594625
    595    Any combination of the remaining flags can be specified in the value of
    596    @code{options}
    597 
    598       CFG_COMFOLLOW - When symbolic links referencing existing nodes are
    599                       specified in the @code{pathnames} argument, the
    600                       @code{cfg_info} field of the returned CFGENT structure
    601                       shall describe the target node pointed to by the link
    602                       instead of the link itself, unless the target node does
    603                       not exist.  If the target node has children, the
    604                       pre-order return, followed by the return of structures
    605                       referencing all its descendants, followed by a post-order
    606                       return, shall be done.
    607 
    608       CFG_XDEV      - The configuration space functions shall not return a
    609                       CFGENT structure for any node in a different configuration
    610                       space than the configuration spacce of the nodes identified
    611                       by the CFGENT structures for the @code{pathnames} argument.
    612 
    613    The @code{cfg_open} argument @code{compar} shall either be NULL or point
    614    to a function that shall be called with two pointers to pointers to CFGENT
    615    structures that shall return less than, equal to , or greater than zero if
    616    the node referenced by the first argument is considered to be respectively
    617    less than, equal to, or greater than the node referenced by the second.
    618    The CFGENT structure fields provided to the comparison routine shall be as
    619    described with the exception that the contents of the @code{cfg_path} and
    620    @code{cfg_pathlen} fields are unspecified.
    621 
    622    This comparison routine is used to determine the order in which nodes in
    623    directories encountered during the traversal are returned, and the order
    624    of traversal when more than one node is specified in the @code{pathnames}
    625    argument to @code{cfg_open}.  If a comparison routine is specified, the
    626    order of traversal shall be from the least to the greatest.  If the
    627    @code{compar} argument is NULL, the order of traversal shall be as listed
    628    in the @code{pathnames} argument.
    629 
    630 Otherwise:
    631 
    632    The @code{cfg_open} shall fail.
     626Any combination of the remaining flags can be specified in the value of
     627@code{options}
     628
     629@table @b
     630
     631@item CFG_COMFOLLOW
     632When symbolic links referencing existing nodes are
     633specified in the @code{pathnames} argument, the
     634@code{cfg_info} field of the returned CFGENT structure
     635shall describe the target node pointed to by the link
     636instead of the link itself, unless the target node does
     637not exist.  If the target node has children, the
     638pre-order return, followed by the return of structures
     639referencing all its descendants, followed by a post-order
     640return, shall be done.
     641
     642@item CFG_XDEV
     643The configuration space functions shall not return a
     644CFGENT structure for any node in a different configuration
     645space than the configuration spacce of the nodes identified
     646by the CFGENT structures for the @code{pathnames} argument.
     647
     648@end table
     649
     650The @code{cfg_open} argument @code{compar} shall either be NULL or point
     651to a function that shall be called with two pointers to pointers to CFGENT
     652structures that shall return less than, equal to , or greater than zero if
     653the node referenced by the first argument is considered to be respectively
     654less than, equal to, or greater than the node referenced by the second.
     655The CFGENT structure fields provided to the comparison routine shall be as
     656described with the exception that the contents of the @code{cfg_path} and
     657@code{cfg_pathlen} fields are unspecified.
     658
     659This comparison routine is used to determine the order in which nodes in
     660directories encountered during the traversal are returned, and the order
     661of traversal when more than one node is specified in the @code{pathnames}
     662argument to @code{cfg_open}.  If a comparison routine is specified, the
     663order of traversal shall be from the least to the greatest.  If the
     664@code{compar} argument is NULL, the order of traversal shall be as listed
     665in the @code{pathnames} argument.
    633666
    634667@subheading NOTES:
     668
     669The @code{_POSIX_CFG} feature flag is defined to indicate
     670this service is available.
    635671
    636672@page
     
    656692@item EACCES
    657693Search permission is denied for any component of a pathname.
     694
    658695@item EBADF
    659696The cfgp argument does not refer to an open configuration
    660697space.
     698
    661699@item ELOOP
    662700A loop exists in symbolic links encountered during resolution
    663701of a pathname.
     702
    664703@item ENOENT
    665704A named node does not exist.
     705
    666706@item ENOMEM
    667707Not enough memory is available to create the necessary structures.
    668 @item ENOSYS
    669 The function cfg_read() is not suported by this implementation.
     708
    670709@item ELOOP
    671710More than @code{SYMLOOP_MAX} symbolic links were encountered during
    672711resolution of the cfgpath argument.
     712
    673713@item ENAMETOOLONG
    674714As aresult of encountering a symbolic link in resolution of the
     
    680720@subheading DESCRIPTION:
    681721
    682 if @code{_POSIX_CFG} is defined:
    683 
    684    The @code{cfg_read} function returns a pointer to a CFGENT sturcture
    685    representing a node in the configuration space to which @code{cfgp}
    686    refers.  The returned pointer shall be stored at the location
    687    indicated by the @code{node} argument.
    688 
    689    The child nodes of each node in the configuration tree is returned
    690    by @code{cfg_read}.  If a comparison routine is specified to the
    691    @code{cfg_open} function, the order of return of the child nodes shall
    692    be as specified by the routine, from least to greatest.  Otherwise
    693    the order of return is unspecified.
    694 
    695    Structures referencing nodes with children shall be returned by the
    696    function @code{cfg_read} at least twice [unless the application
    697    specifies otherwise with @code{cfg_mark}]-once immediately before
    698    the structures representing their descendants, are returned
    699    (pre-order), and once immediately after structures representing all
    700    of their descendants, if any, are returned (post-order).  The
    701    CFGENT structure returned in post-porder (with the exception of the
    702    @code{cfg_info} field) shall be identical to that returned in pre-order.
    703    Structures referencing nodes of other types shall be returned at least
    704    once.
    705 
    706    The fields of the CFGENT structure shall contain the following
    707    informatation:
    708       cfg_parent  - A pointer to the structure returned by the
    709                     @code{cfg_read} function for the node that contains
    710                     the entry for the current node.  A @code{cfg_parent}
    711                     structure shall be provided for the node(s) specified
    712                     by the @code{pathnames} argument to the @code{cfg_open}
    713                     function, but the contents of other than its
    714                     @code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
    715                     and @code{cfg_parent}, and @code{cfg_level} fields are
    716                     unspecified.  Its @code{cfg_link} field is unspecified.
    717       cfg_link    - Upon return from the @code{cfg_children} function, the
    718                     @code{cfg_link} field points to the next CFGENT structure
    719                     in a NULL-terminated linked list of CFGENT structures. 
    720                     Otherwise, the content of the @code{cfg_link} field is
    721                     unspecified.
    722       cfg_cycle   - If the structure being returned by @code{cfg_read}
    723                     represents a node that appears in the @code{cfg_parent}
    724                     linked list tree, the @code{cfg_cycle} field shall point
    725                     to the structure representing that entry from the
    726                     @code{cfg_parent} linked list.  Otherwise the content of
    727                     the @code{cfg_cycle} field is unspecified.
    728       cfg_number  - The @code{cfg_number} field is provided for use by the
    729                     application program.  It shall be initialized to zero for
    730                     each new node returned by the @code{cfg_read} function,
    731                     but shall not be further modified the configuration space
    732                     routines.
    733       cfg_pointer - The @code{cfg_pointer} field is provided for use by the
    734                     application program.  It shall be initialized to NULL for
    735                     each new node returned by the @code{cfg_read} function,
    736                     but shall not be further modified by the configuration
    737                     space routines.
    738       cfg_path    - A pathname for the node including and relative to the
    739                     argument supplied to the @code{cfg_open} routine for this
    740                     configuration space.  This pathname may be logner than
    741                     @code{PATH_MAX} bytes.  This patname shall be NULL-terminated.
    742       cfg_name    - The nodename of the node.
    743       cfg_pathlen - The length of the string pointed at by the @code{cfg_path}
    744                     field when returned by @code{cfg_read}.
    745       cfg_namelen - The length of the string pointed at by the @code{cfg_name}
    746                     field.
    747       cfg_level   - The depth of the current entry in the configuration space.
    748                     The @code{cfg_level} field of the @code{cfg_partent}
    749                     structure for each of the node(s) specified in the
    750                     @code{pathnames} argument to the @code{cfg_open} function
    751                     shall be set to 0, and this number shall be incremented for
    752                     for each node level descendant.
    753       cfg_info    - This field shall contain one of the values listed below.  If
    754                     an object can have more than one info value, the first
    755                     appropriate value listed below shall be returned.
    756 
    757                     CFG_D       - The structure represents a node with children in
    758                                   pre-order.
    759                     CFG_DC      - The structure represents a node that is a parent
    760                                   of the node most recently returned by @code{cfg_read}.
    761                                   The @code{cfg_cycle} field shall reference the
    762                                   structure previously returned by @code{cfg_read} that
    763                                   is the same as the returned structure.
    764                     CFG_DEFAULT - The structure represents a node that is not
    765                                   represented by one of the other node types
    766                     CFG_DNR     - The structure represents a node, not of type symlink,
    767                                   that is unreadable.   The variable @code{cfg_errno}
    768                                   shall be set to the appropriate value.
    769                     CFG_DP      - The structure represents a node with children in
    770                                   post-order.  This value shall occur only if CFG_D
    771                                   has previously been returned for this entry.
    772                     CFG_ERR     - The structure represents a node for which an error has
    773                                   occurred.  The variable @code{cfg_errno} shall be set
    774                                   to the appropriate value.
    775                     CFG_F       - The structure represents a node without children.
    776                     CFG_SL      - The structure represents a node of type symbolic link.
    777                     CFG_SLNONET - The structure represents a node of type symbolic link
    778                                   with a target node for which node characteristic
    779                                   information cannot be obtained.
    780 
    781    Structurres returned by @code{cfg_read} with a @code{cfg_info} field equal to CFG_D
    782    shall be accessible until a subsequent call, on the same configuration traversal
    783    stream, to @code{cfg_close}, or to @code{cfg_read} after they have been returned by
    784    the @code{cfg_read} function in post-order.  Structures returnded by @code{cfg_read}
    785    with an @code{cfg_info} field not equal to CFG_D shall be accessible until a
    786    subsequent call, on the same configuration traversal stream, to @code{cfg_close} or
    787    @code{cfg_read}.
    788 
    789    The content of the @code{cfg_path} field is specified only for the structure most
    790    recently returned by @code{cfg_read}.
    791 
    792    The specified fields in structures in the list representing nodes for which structures
    793    have previously been returned by @code{cfg_children}, shall be identical to those
    794    returned by @code{cfg_children}, except that the contents of the @code{cfg_path} and
    795    @code{cfg_pathlen} fields are unspecified.
     722The @code{cfg_read} function returns a pointer to a CFGENT sturcture
     723representing a node in the configuration space to which @code{cfgp}
     724refers.  The returned pointer shall be stored at the location
     725indicated by the @code{node} argument.
     726
     727The child nodes of each node in the configuration tree is returned
     728by @code{cfg_read}.  If a comparison routine is specified to the
     729@code{cfg_open} function, the order of return of the child nodes shall
     730be as specified by the routine, from least to greatest.  Otherwise
     731the order of return is unspecified.
     732
     733Structures referencing nodes with children shall be returned by the
     734function @code{cfg_read} at least twice [unless the application
     735specifies otherwise with @code{cfg_mark}]-once immediately before
     736the structures representing their descendants, are returned
     737(pre-order), and once immediately after structures representing all
     738of their descendants, if any, are returned (post-order).  The
     739CFGENT structure returned in post-porder (with the exception of the
     740@code{cfg_info} field) shall be identical to that returned in pre-order.
     741Structures referencing nodes of other types shall be returned at least
     742once.
     743
     744The fields of the CFGENT structure shall contain the following
     745informatation:
     746
     747@table @b
     748
     749@item cfg_parent
     750A pointer to the structure returned by the
     751@code{cfg_read} function for the node that contains
     752the entry for the current node.  A @code{cfg_parent}
     753structure shall be provided for the node(s) specified
     754by the @code{pathnames} argument to the @code{cfg_open}
     755function, but the contents of other than its
     756@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
     757and @code{cfg_parent}, and @code{cfg_level} fields are
     758unspecified.  Its @code{cfg_link} field is unspecified.
     759
     760@item cfg_link
     761Upon return from the @code{cfg_children} function, the
     762@code{cfg_link} field points to the next CFGENT structure
     763in a NULL-terminated linked list of CFGENT structures. 
     764Otherwise, the content of the @code{cfg_link} field is
     765unspecified.
     766
     767@item cfg_cycle
     768If the structure being returned by @code{cfg_read}
     769represents a node that appears in the @code{cfg_parent}
     770linked list tree, the @code{cfg_cycle} field shall point
     771to the structure representing that entry from the
     772@code{cfg_parent} linked list.  Otherwise the content of
     773the @code{cfg_cycle} field is unspecified.
     774
     775@item cfg_number
     776The @code{cfg_number} field is provided for use by the
     777application program.  It shall be initialized to zero for
     778each new node returned by the @code{cfg_read} function,
     779but shall not be further modified the configuration space
     780routines.
     781
     782@item cfg_pointer
     783The @code{cfg_pointer} field is provided for use by the
     784application program.  It shall be initialized to NULL for
     785each new node returned by the @code{cfg_read} function,
     786but shall not be further modified by the configuration
     787space routines.
     788
     789@item cfg_path
     790A pathname for the node including and relative to the
     791argument supplied to the @code{cfg_open} routine for this
     792configuration space.  This pathname may be logner than
     793@code{PATH_MAX} bytes.  This patname shall be NULL-terminated.
     794
     795@item cfg_name
     796The nodename of the node.
     797
     798@item cfg_pathlen
     799The length of the string pointed at by the @code{cfg_path}
     800field when returned by @code{cfg_read}.
     801
     802@item cfg_namelen
     803The length of the string pointed at by the @code{cfg_name}
     804field.
     805
     806@item cfg_level
     807The depth of the current entry in the configuration space.
     808The @code{cfg_level} field of the @code{cfg_partent}
     809structure for each of the node(s) specified in the
     810@code{pathnames} argument to the @code{cfg_open} function
     811shall be set to 0, and this number shall be incremented for
     812for each node level descendant.
     813
     814@item cfg_info
     815This field shall contain one of the values listed below.  If
     816an object can have more than one info value, the first
     817appropriate value listed below shall be returned.
     818
     819@table @b
     820
     821@item CFG_D
     822The structure represents a node with children in
     823pre-order.
     824
     825@item CFG_DC
     826The structure represents a node that is a parent
     827of the node most recently returned by @code{cfg_read}.
     828The @code{cfg_cycle} field shall reference the
     829structure previously returned by @code{cfg_read} that
     830is the same as the returned structure.
     831
     832@item CFG_DEFAULT
     833The structure represents a node that is not
     834represented by one of the other node types
     835
     836@item CFG_DNR
     837The structure represents a node, not of type symlink,
     838that is unreadable.  The variable @code{cfg_errno}
     839shall be set to the appropriate value.
     840
     841@item CFG_DP
     842The structure represents a node with children in
     843post-order.  This value shall occur only if CFG_D
     844has previously been returned for this entry.
     845
     846@item CFG_ERR
     847The structure represents a node for which an error has
     848occurred.  The variable @code{cfg_errno} shall be set
     849to the appropriate value.
     850
     851@item CFG_F
     852The structure represents a node without children.
     853
     854@item CFG_SL
     855The structure represents a node of type symbolic link.
     856
     857@item CFG_SLNONET
     858The structure represents a node of type symbolic link
     859with a target node for which node characteristic
     860information cannot be obtained.
     861
     862@end table
     863
     864@end table
     865
     866Structures returned by @code{cfg_read} with a @code{cfg_info} field equal
     867to CFG_D shall be accessible until a subsequent call, on the same
     868configuration traversal stream, to @code{cfg_close}, or to @code{cfg_read}
     869after they have been returned by the @code{cfg_read} function in
     870post-order.  Structures returded by @code{cfg_read} with an
     871@code{cfg_info} field not equal to CFG_D shall be accessible until a
     872subsequent call, on the same configuration traversal stream, to
     873@code{cfg_close} or @code{cfg_read}.
     874
     875The content of the @code{cfg_path} field is specified only for the
     876structure most recently returned by @code{cfg_read}.
     877
     878The specified fields in structures in the list representing nodes for
     879which structures have previously been returned by @code{cfg_children},
     880shall be identical to those returned by @code{cfg_children}, except that
     881the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
     882unspecified.
    796883         
    797 Otherwise:
    798 
    799    The @code{cfg_read} function shall fail.
    800 
    801 @subheading NOTES:
     884@subheading NOTES:
     885
     886The @code{_POSIX_CFG} feature flag is defined to indicate
     887this service is available.
    802888
    803889@page
     
    824910@item EACCES
    825911Search permission is denied for any component of a pathname
     912
    826913@item EBADF
    827914The cfgp argument does not refer to an open configuration space.
     915
    828916@item ELOOP
    829917A loop exists in symbolic links encountered during resolution of
    830918a pathname.
     919
    831920@item ENAMETOOLONG
    832921The length of a pathname exceeds @code{PATH_MAX}, or a pathname
    833922component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
    834923in effect.
     924
    835925@item EINVAL
    836926The specified value of the optiions argument is invalid.
     927
    837928@item ENOENT
    838929The named node does not exist.
     930
    839931@item ENOMEM
    840932Not enough memory is available to create the necessary structures.
    841 @item ENOSYS
    842 The function cfg_children() is not supported by this implementation.
    843 
    844 @end table
    845 
    846 @subheading DESCRIPTION:
    847 
    848 If @code{_POSIX_CFG} is defined:
    849 
    850    The first @code{cfg_children} call after a @code{cfg_read} shall
    851    return information about the first node without children under the
    852    node returned by @code{cfg_read}.  Subsequent calls to
    853    @code{cfg_children} without the intervening @code{cfg_read} shall
    854    return information about the remaining nodes without children under
    855    that same node.
    856 
    857    If @code{cfg_read} has not yet been called for the configuration
    858    traversal stream represented by @code{cfgp}, @code{cfg_children}
    859    shall return a pointer to the first entry in a list of the nodes
    860    represented by the @code{pathnames} argument to @code{cfg_open}.
    861 
    862    In either case, the list shall be NULL-terminated, ordered by the
    863    user-specified comparison function, if any, and linked through the
    864    cfg_link field.
    865 
    866 Otherwise:
    867 
    868    The @code{cfg_children} function shall fail.
     933
     934@end table
     935
     936@subheading DESCRIPTION:
     937
     938The first @code{cfg_children} call after a @code{cfg_read} shall
     939return information about the first node without children under the
     940node returned by @code{cfg_read}.  Subsequent calls to
     941@code{cfg_children} without the intervening @code{cfg_read} shall
     942return information about the remaining nodes without children under
     943that same node.
     944
     945If @code{cfg_read} has not yet been called for the configuration
     946traversal stream represented by @code{cfgp}, @code{cfg_children}
     947shall return a pointer to the first entry in a list of the nodes
     948represented by the @code{pathnames} argument to @code{cfg_open}.
     949
     950In either case, the list shall be NULL-terminated, ordered by the
     951user-specified comparison function, if any, and linked through the
     952cfg_link field.
    869953
    870954@subheading NOTES:
     955
     956The @code{_POSIX_CFG} feature flag is defined to indicate
     957this service is available.
    871958
    872959@page
     
    894981The specified combination of the cfgp and f arguments is not
    895982supported by the implementation.
     983
    896984@item EINVAL
    897985The specified value of the options argument is invalid.
    898 @item ENOSYS
    899 The function cfg_mark() is not supported by this implementation.
    900 
    901 @end table
    902 
    903 @subheading DESCRIPTION:
    904 
    905 If @code{_POSIX_CF} is defined:
    906 
    907    The @code{cfg_mark} function modifies the subsequent behavior of
    908    the cfg functions with regard to the node referenced by the structure
    909    pointed to by the argument @code{f} or the configuration space referenced
    910    by the structure pointed to by the argument @code{cfgp}.
    911 
    912    Exactly one of the @code{f} argument and the @code{cfgp} argument shall
    913    be NULL.
    914 
    915    The value of the @code{options} argument shall be exactly one of the
    916    flags specified in the following list:
    917 
    918       CFG_AGAIN  - If the @code{cfgp} argument is non-NULL, or the @code{f}
    919                    argument is NULL, or the structure referenced by @code{f}
    920                    is not the one most recently returned by @code{cfg_read},
    921                    @code{cfg_mark} ahall return an error.  Otherwise, the next
    922                    call to teh @code{cfg_read} function shall return the
    923                    structure referenced by @code{f} with the @code{cfg_info}
    924                    field reinitialized.  Subsequent behavior of the @code{cfg}
    925                    functions shall be based on the reinitialized value of
    926                    @code{cfg_ingo}.
    927 
    928       CFG_SKIP   - If the @code{cfgp} argument is non-NULL, or the @code{f}
    929                    argument is NULL, or the structure referenced by @code{f}
    930                    is not one of those specified as accessible, or the structure
    931                    referenced by @code{f} is not for a node of type pre-order
    932                    node, @code{cfg_mark} shall return an error.  Otherwise, no
    933                    more structures for the node referenced by @code{f} or its
    934                    descendants shall be returned by the @code{cfg_read} function.
    935 
    936       CFG_FOLLOW - If the @code{cfgp} argument is non-NULL, or the @code{f}
    937                    argument is NULL, or the structure referenced by @code{f}
    938                    is not one of those specified as accessible, or the structure
    939                    referenced by @code{f} is not for a node of type symbolic link,
    940                    @code{cfg_mark} shall return an error.  Otherwise, the next
    941                    call to the @code{cfg_read} function shall return the structure
    942                    referenced by @code{f} with the @code{cfg_info} field reset
    943                    to reflect the target of the symbolic link instead of the
    944                    symbolic link itself.  If the target of the link is node with
    945                    children, the pre-order return, followed by the return of
    946                    structures referencing all of its descendants, followed by a
    947                    post-order return, shall be don.
    948 
    949                    If the target of the symbolic link does not exist, the fields
    950                    of the structure by @code{cfg_read} shall be unmodified, except
    951                    that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
    952 
    953 Otherwise:
    954    
    955    The @code{cfg_mark} function shall fail.
     986
     987@end table
     988
     989@subheading DESCRIPTION:
     990
     991The @code{cfg_mark} function modifies the subsequent behavior of
     992the cfg functions with regard to the node referenced by the structure
     993pointed to by the argument @code{f} or the configuration space referenced
     994by the structure pointed to by the argument @code{cfgp}.
     995
     996Exactly one of the @code{f} argument and the @code{cfgp} argument shall
     997be NULL.
     998
     999The value of the @code{options} argument shall be exactly one of the
     1000flags specified in the following list:
     1001
     1002@table @b
     1003
     1004@item CFG_AGAIN
     1005If the @code{cfgp} argument is non-NULL, or the @code{f}
     1006argument is NULL, or the structure referenced by @code{f}
     1007is not the one most recently returned by @code{cfg_read},
     1008@code{cfg_mark} ahall return an error.  Otherwise, the next
     1009call to teh @code{cfg_read} function shall return the
     1010structure referenced by @code{f} with the @code{cfg_info}
     1011field reinitialized.  Subsequent behavior of the @code{cfg}
     1012functions shall be based on the reinitialized value of
     1013@code{cfg_ingo}.
     1014
     1015@item CFG_SKIP
     1016If the @code{cfgp} argument is non-NULL, or the @code{f}
     1017argument is NULL, or the structure referenced by @code{f}
     1018is not one of those specified as accessible, or the structure
     1019referenced by @code{f} is not for a node of type pre-order
     1020node, @code{cfg_mark} shall return an error.  Otherwise, no
     1021more structures for the node referenced by @code{f} or its
     1022descendants shall be returned by the @code{cfg_read} function.
     1023
     1024@item CFG_FOLLOW
     1025If the @code{cfgp} argument is non-NULL, or the @code{f}
     1026argument is NULL, or the structure referenced by @code{f}
     1027is not one of those specified as accessible, or the structure
     1028referenced by @code{f} is not for a node of type symbolic link,
     1029@code{cfg_mark} shall return an error.  Otherwise, the next
     1030call to the @code{cfg_read} function shall return the structure
     1031referenced by @code{f} with the @code{cfg_info} field reset
     1032to reflect the target of the symbolic link instead of the
     1033symbolic link itself.  If the target of the link is node with
     1034children, the pre-order return, followed by the return of
     1035structures referencing all of its descendants, followed by a
     1036post-order return, shall be done.
     1037
     1038@end table
     1039
     1040If the target of the symbolic link does not exist, the fields
     1041of the structure by @code{cfg_read} shall be unmodified, except
     1042that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
    9561043
    9571044@subheading NOTES:
     1045
     1046The @code{_POSIX_CFG} feature flag is defined to indicate
     1047this service is available.
    9581048
    9591049@page
     
    9791069The cfgp argument does not refer to an open configuration space
    9801070traversal stream.
    981 @item ENOSYS
    982 The function cfg_close() is not supported by this implementatioin.
    983 
    984 @end table
    985 
    986 @subheading DESCRIPTION:
    987 
    988 if @code{_POSIX_CFG} is defined:
    989 
    990    The @code{cfg_close} function closes a configuration space transversal
    991    stream represented by the CFG structure pointed at by the @code{cfgp}
    992    argument.  All system resources allocated for this configuration space
    993    travsversal stream should be deallocated.  Upon return, the value of
    994    @code{cfgp} need not point to an accessible object of type CFG.
    995 
    996 Otherwise:
    997 
    998    The @code{cfg_close} function shall fail.
     1071
     1072@end table
     1073
     1074@subheading DESCRIPTION:
     1075
     1076The @code{cfg_close} function closes a configuration space transversal
     1077stream represented by the CFG structure pointed at by the @code{cfgp}
     1078argument.  All system resources allocated for this configuration space
     1079travsversal stream should be deallocated.  Upon return, the value of
     1080@code{cfgp} need not point to an accessible object of type CFG.
    9991081
    10001082@subheading NOTES:
    10011083
     1084The @code{_POSIX_CFG} feature flag is defined to indicate
     1085this service is available.
  • doc/new_chapters/dumpcontrol.t

    rd5ef5bd1 rd1a859c  
    1111@section Introduction
    1212
    13 The
    14 process dump control manager is ...
     13The process dump control manager provides a portable
     14interface for changing the path to which a process dump
     15is written.  The capabilities in this manager were defined in
     16the POSIX 1003.1h/D3 proposed standard titled @b{Services for Reliable,
     17Available, and Serviceable Systems}.
    1518
    1619The directives provided by the process dump control manager are:
     
    5457or write permission is denied on the directory containing the
    5558file.
     59
    5660@item ENAMETOOLONG
    5761The length of the argument exceeds @code{PATH_MAX} or a pathname
    5862component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}
    5963is in effect.
     64
    6065@item ENOENT
    6166The path argument points to an empty string.
    62 @item ENOSYS
    63 The function dump_setpath() is not suppo9rted by this implementation.
     67
    6468@item ENOTDIR
    6569A component of the path prefix is not a directory.
     70
    6671@item EROFS
    6772The directory entry specified resides on a read-only file system.
     
    7176@subheading DESCRIPTION:
    7277
    73 If @code{_POSIX_DUMP} is defined:
     78The @code{dump_setpath} function defines the pathname where process
     79dumps are written.  The pathname pointed to by @code{path} shall
     80define where a process dump file will be written if the calling
     81process terminates with a dump file.  The @code{path} argument
     82shall not name a directory.
    7483
    75    The @code{dump_setpath} function defines the pathname where process
    76    dumps are written.  The pathname pointed to by @code{path} shall
    77    define where a process dump file will be written if the calling
    78    process terminates with a dump file.  The @code{path} argument
    79    shall not name a directory.
    80 
    81    If the @code{path} argument is NULL, the system shall not write a
    82    process dump file if the calling process terminates with a dump
    83    file.  If the @code{dump_setpath} function fails, the pathname for
    84    writing process dumps shall not change.
    85 
    86 Otherwise:
    87 
    88    The @code{dump_setpath} function shall fail.
     84If the @code{path} argument is NULL, the system shall not write a
     85process dump file if the calling process terminates with a dump
     86file.  If the @code{dump_setpath} function fails, the pathname for
     87writing process dumps shall not change.
    8988
    9089@subheading NOTES:
    9190
     91The @code{_POSIX_DUMP} feature flag is defined to indicate
     92this service is available.
  • doc/new_chapters/eventlog.t

    rd5ef5bd1 rd1a859c  
    1111@section Introduction
    1212
    13 The
    14 event logging manager is ...
     13The event logging manager provides a portable method for logging
     14system and appplication events and subsequent processing of those
     15events.  The capabilities in this manager were defined in the POSIX
     161003.1h/D3 proposed standard titled @b{Services for Reliable,
     17Available, and Serviceable Systems}.
    1518
    1619The directives provided by the event logging manager are:
     
    3336@section Background
    3437
     38@subsection Log Files and Events
     39
     40System log
     41
     42Non-system logs
     43
     44Events, facility, severity
     45
     46@subsection Queries
     47
    3548@section Operations
     49
     50@subsection Creating and Writing a non-System Log
     51
     52Discuss creating and writing to a non-system log.
     53
     54@example
     55  log_create
     56  log_write loop
     57@end example
     58
     59@subsection Reading a Log
     60
     61Discuss opening and reading from a log.
     62
     63@example
     64  build a query
     65  log_open
     66  log_read loop
     67@end example
    3668
    3769@section Directives
     
    6799@item EINVAL
    68100The facility argument is not a valid log_facility.
     101
    69102@item EINVAL
    70103The severity argument exceeds @code{LOG_SEVERITY_MAX}
     104
    71105@item EINVAL
    72106The len argument exceeds @code{LOG_ENTRY_MAXLEN}
     107
    73108@item ENOSPC
    74109The log file has run out of space on the device.
    75 @item ENOSYS
    76 The function log_write() is not supported by this implementation.
     110
    77111@item EPERM
    78112The caller does not have appropriate permission for writing to
    79113the given facility.
     114
    80115@item EIO
    81116An I/O error occurred in writing to the system event log.
     
    85120@subheading DESCRIPTION:
    86121
    87 If @code{_POSIX_LOGGING} is defined:
    88 
    89    The @code{log_write} function writes an event record, consisting
    90    of event attributes, and the data identified by the @code{buf}
    91    argument, to the system log.  The @code{len} argument specifies
    92    the length in bytes of the buffer pointed to by @code{buf}.  The
    93    @code{len} argument shall specify the value of the event record
    94    length attribute.  The value of @code{len} shall be less than or
    95    equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
    96 
    97    The @code{event_id} argument identifies the type of event record
    98    being written.  The @code{event_id} argument shall specify the value
    99    of the event ID attribute of the event record.
    100 
    101    The argument @code{facility} indicates the facility from which the
    102    event type is drawn.  The @code{facility} aargument shall specify the
    103    value of the event record facility attribute.  The value of the
    104    @code{facility} argument shall be a valid log facility or the
    105    @code{log_write} function shall fail.
    106 
    107    The @code{severity} argument indicates the severity level of the
    108    event record.  The @code{severity} argument shall specify the value
    109    of the event record severity attribute.  The value of the
    110    @code{severity} argument shall be less than or equal to
    111    @code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
    112 
    113    The effective_UID of the calling process shall specify the event
    114    record UID attribute.  The efective-GID of the calling process
    115    shall specify the event record GID attribute.  The process ID
    116    of the calling process shall specify the event record process ID
    117    attribute.  The process group ID of the calling process shall
    118    specify the event record process group ID attribute.  The current
    119    value of the system clock shall specify the event record timestamp
    120    attribute.
    121 
    122 Otherwise:
    123 
    124    The @code{log_write} function shall fail.
    125 
    126 @subheading NOTES:
     122The @code{log_write} function writes an event record, consisting
     123of event attributes, and the data identified by the @code{buf}
     124argument, to the system log.  The @code{len} argument specifies
     125the length in bytes of the buffer pointed to by @code{buf}.  The
     126@code{len} argument shall specify the value of the event record
     127length attribute.  The value of @code{len} shall be less than or
     128equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
     129
     130The @code{event_id} argument identifies the type of event record
     131being written.  The @code{event_id} argument shall specify the value
     132of the event ID attribute of the event record.
     133
     134The argument @code{facility} indicates the facility from which the
     135event type is drawn.  The @code{facility} aargument shall specify the
     136value of the event record facility attribute.  The value of the
     137@code{facility} argument shall be a valid log facility or the
     138@code{log_write} function shall fail.
     139
     140The @code{severity} argument indicates the severity level of the
     141event record.  The @code{severity} argument shall specify the value
     142of the event record severity attribute.  The value of the
     143@code{severity} argument shall be less than or equal to
     144@code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
     145
     146The effective_UID of the calling process shall specify the event
     147record UID attribute.  The efective-GID of the calling process
     148shall specify the event record GID attribute.  The process ID
     149of the calling process shall specify the event record process ID
     150attribute.  The process group ID of the calling process shall
     151specify the event record process group ID attribute.  The current
     152value of the system clock shall specify the event record timestamp
     153attribute.
     154
     155@subheading NOTES:
     156
     157The @code{_POSIX_LOGGING} feature flag is defined to indicate
     158this service is available.
    127159
    128160@page
     
    150182Search permission is denied on a component of the path prefix,
    151183or the log file exists and read permission is denied.
     184
    152185@item  EINTR
    153186A signal interrupted the call to log_open().
     187
    154188@item EINVAL
    155189The log_facility field of the query argument is not a valid
    156190facility set.
     191
    157192@item EINVAL
    158193The log_severity field of the query argument exceeds
    159194@code{LOG_SEVERITY_MAX}.
     195
    160196@item EINVAL
    161197The path argument referred to a file that was not a log file.
     198
    162199@item EMFILE
    163200Too many log file descriptors are currently in use by this
    164201process.
     202
    165203@item ENAMETOOLONG
    166204The length of the path string exceeds @code{PATH_MAX}, or a pathname
    167205component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
    168206in effect.
     207
    169208@item ENFILE
    170209Too many files are currently open in the system.
     210
    171211@item ENOENT
    172212The file specified by the path argument does not exist.
     213
    173214@item ENOTDIR
    174215A component of the path prefix is not a directory.
    175 @item ENOSYS
    176 The function log_open() is not supported by this implementation.
    177 
    178 @end table
    179 
    180 @subheading DESCRIPTION:
    181 
    182 If @code{_POSIX_LOGGING} is defined:
    183 
    184    The @code{log_open} function establishes the connection between a
    185    log file and a log file descriptor.  It creates an open log file
    186    description that refers to a log file and a log file descriptor that
    187    refers to that open log file description.  The log file descriptor is
    188    used by other log functions to refer to that log file.  The @code{path}
    189    argument points to a pathname naming a log file.  A @code{path}
    190    argument of NULL specifies the current system log file. 
    191 
    192    The @code{query} argument points to a log query specification that
    193    restricts log operations using the returned log file descriptor to
    194    to event records from the log file which match the query.  The
    195    predicate which determines the success of the match operation is the
    196    logical AND of the individual comparison predicates for each member
    197    of the log query specification.  The query attribute of the open file
    198    description is set to filter as specified by the @code{query} argument.
    199    If the value of the query argument is not NULL, the value of the
    200    @code{log_facility} member of the @code{query} specification shall be
    201    a set of valid log facilities or the @code{log_open} shall fail.  If
    202    the value of the @code{query} argument is not NULL, the value of the
    203    @code{log_severity} member of the @code{query} specification shall be
    204    less than or equal to @code{LOG_SEVERITY_MAX} or the @code{log_open}
    205    shall fail.  If the value of the @code{query} argument is NULL, no
    206    query filter shall be applied.
    207 
    208 Otherwise:
    209 
    210    The @code{log_open} shall fail.
    211 
    212 @subheading NOTES:
     216
     217@end table
     218
     219@subheading DESCRIPTION:
     220
     221The @code{log_open} function establishes the connection between a
     222log file and a log file descriptor.  It creates an open log file
     223description that refers to a log file and a log file descriptor that
     224refers to that open log file description.  The log file descriptor is
     225used by other log functions to refer to that log file.  The @code{path}
     226argument points to a pathname naming a log file.  A @code{path}
     227argument of NULL specifies the current system log file. 
     228
     229The @code{query} argument points to a log query specification that
     230restricts log operations using the returned log file descriptor to
     231to event records from the log file which match the query.  The
     232predicate which determines the success of the match operation is the
     233logical AND of the individual comparison predicates for each member
     234of the log query specification.  The query attribute of the open file
     235description is set to filter as specified by the @code{query} argument.
     236If the value of the query argument is not NULL, the value of the
     237@code{log_facility} member of the @code{query} specification shall be
     238a set of valid log facilities or the @code{log_open} shall fail.  If
     239the value of the @code{query} argument is not NULL, the value of the
     240@code{log_severity} member of the @code{query} specification shall be
     241less than or equal to @code{LOG_SEVERITY_MAX} or the @code{log_open}
     242shall fail.  If the value of the @code{query} argument is NULL, no
     243query filter shall be applied.
     244
     245@subheading NOTES:
     246
     247The @code{_POSIX_LOGGING} feature flag is defined to indicate
     248this service is available.
    213249
    214250@page
     
    237273@item EBADF
    238274The logdes argument is not a valid log file descriptor.
     275
    239276@item EBUSY
    240277No data available.  The open log file descriptor references
    241278the current system log.  and there are no unread event records
    242279remaining.
     280
    243281@item EINTR
    244282A signal interrupted the call to log_read().
    245 @item ENOSYS
    246 The function log_read() is not supported by this implementation.
     283
    247284@item EIO
    248285An I/O error occurred in reading from the event log.
     
    252289@subheading DESCRIPTION:
    253290
    254 If @code{_POSIX_LOGGING} is defined:
    255 
    256    The @code{log_read} function shall attempt to read the @code{log_entry}
    257    structure and @code{log_len} bytes of data from the next event record
    258    of the log file associated with the open log file descriptor @code{logdes},
    259    placing the @code{log_entry} structure into the buffer pointed to by
    260    @code{entry}, and the data into the buffer pointed to by @code{log_buf}.
    261    The log record ID of the returned event record shall be stored in the
    262    @code{log_recied} member of the @code{log_entry} structure for the event
    263    record.
    264 
    265    If the query attribute of the open log file description associated with
    266    the @code{logdes} is set, the event record read shall match that query.
    267    If the @code{entry} argument is not NULL it will point to a @code{log_entry}
    268    structure which sall be filled with the creation information for this log
    269    entry.  If the argument @code{log_buf} is not NULL the data written with the
    270    log entry will be placed in the buffer.  The size of the buffer is specified
    271    by the argument @code{log_len}.
    272 
    273    If the @code{log_read} is successful the call shall store the actual length
    274    of the data associated with the event record into the location specified by
    275    @code{log_sizeread}.  This number may be smaller or greater than
    276    @code{log_len}.
    277 
    278 Otherwise:
    279 
    280    The @code{log_read} function shall fail.
    281 
    282 
    283 @subheading NOTES:
     291The @code{log_read} function shall attempt to read the @code{log_entry}
     292structure and @code{log_len} bytes of data from the next event record
     293of the log file associated with the open log file descriptor @code{logdes},
     294placing the @code{log_entry} structure into the buffer pointed to by
     295@code{entry}, and the data into the buffer pointed to by @code{log_buf}.
     296The log record ID of the returned event record shall be stored in the
     297@code{log_recied} member of the @code{log_entry} structure for the event
     298record.
     299
     300If the query attribute of the open log file description associated with
     301the @code{logdes} is set, the event record read shall match that query.
     302If the @code{entry} argument is not NULL it will point to a @code{log_entry}
     303structure which sall be filled with the creation information for this log
     304entry.  If the argument @code{log_buf} is not NULL the data written with the
     305log entry will be placed in the buffer.  The size of the buffer is specified
     306by the argument @code{log_len}.
     307
     308If the @code{log_read} is successful the call shall store the actual length
     309of the data associated with the event record into the location specified by
     310@code{log_sizeread}.  This number may be smaller or greater than
     311@code{log_len}.
     312
     313@subheading NOTES:
     314
     315The @code{_POSIX_LOGGING} feature flag is defined to indicate
     316this service is available.
    284317
    285318@page
     
    305338@item EBADF
    306339The logdes arfument is not a valid log file descriptor.
     340
    307341@item EINVAL
    308342The notification argument specifies an invalid signal.
     343
    309344@item EINVAL
    310345The process has requested a notify on a log that will not be
    311346written to.
     347
    312348@item ENOSY
    313349The function log_notify() is not supported by this implementation.
     
    317353@subheading DESCRIPTION:
    318354
    319 If @code{_POSIX_LOGGING} is defined:
    320  
    321    If the argument @code{notification} is not NULL this function registers
    322    the calling process to be notified of event records received by the system
    323    log, which match the query parameters associated with the open log descriptor
    324    specified by @code{logdes}.  The notification specified by the
    325    @code{notification} argument shall be sent to the process when an event
    326    record received by the system log is matched by the query attribute of the
    327    open log file description associated with the @code{logdes} log file
    328    descriptor.  If the calling process has already registered a notification
    329    for the @code{logdes} log file descriptor, the new notification shall
    330    replace the existing notification registration.
    331 
    332    If the @code{notification} argument is NULL and the calling process is
    333    currently registered to be notified for the @code{logdes} log file
    334    descriptor, the existing registration shall be removed.
    335 
    336 Otherwise:
    337 
    338    The @code{log_notify} function shall fail.
    339    
    340 
    341 @subheading NOTES:
     355If the argument @code{notification} is not NULL this function registers
     356the calling process to be notified of event records received by the system
     357log, which match the query parameters associated with the open log descriptor
     358specified by @code{logdes}.  The notification specified by the
     359@code{notification} argument shall be sent to the process when an event
     360record received by the system log is matched by the query attribute of the
     361open log file description associated with the @code{logdes} log file
     362descriptor.  If the calling process has already registered a notification
     363for the @code{logdes} log file descriptor, the new notification shall
     364replace the existing notification registration.
     365
     366If the @code{notification} argument is NULL and the calling process is
     367currently registered to be notified for the @code{logdes} log file
     368descriptor, the existing registration shall be removed.
     369
     370@subheading NOTES:
     371
     372The @code{_POSIX_LOGGING} feature flag is defined to indicate
     373this service is available.
    342374
    343375@page
     
    362394@item EBADF
    363395The logdes argument is not a valid log file descriptor.
    364 @item ENOSYS
    365 The function log_close() is not supported by t his implementation.
    366 
    367 @end table
    368 
    369 @subheading DESCRIPTION:
    370 
    371 If @code{_POSIX_LOGGING} is defined:
    372 
    373    The @code{log_close} function deallocates the open log file descriptor
    374    indicated by @code{log_des}.
    375 
    376    When all log file descriptors associated with an open log file description
    377    have been closed, the open log file description shall be freed.
    378 
    379    If the link count of the log file is zero, when all log file descriptors
    380    have been closed, the space occupied by the log file shall be freed and the
    381    log file shall no longer be accessible.
    382 
    383    If the process has successfully registered a notification request for the
    384    log file descriptor, the registration shall be removed.
    385 
    386 Otherwise:
    387 
    388    The @code{log_close} function shall fail.
    389 
    390 @subheading NOTES:
     396
     397@end table
     398
     399@subheading DESCRIPTION:
     400
     401The @code{log_close} function deallocates the open log file descriptor
     402indicated by @code{log_des}.
     403
     404When all log file descriptors associated with an open log file description
     405have been closed, the open log file description shall be freed.
     406
     407If the link count of the log file is zero, when all log file descriptors
     408have been closed, the space occupied by the log file shall be freed and the
     409log file shall no longer be accessible.
     410
     411If the process has successfully registered a notification request for the
     412log file descriptor, the registration shall be removed.
     413
     414@subheading NOTES:
     415
     416The @code{_POSIX_LOGGING} feature flag is defined to indicate
     417this service is available.
    391418
    392419@page
     
    412439@item EBADF
    413440The logdes argument is not a valid log file descriptor.
     441
    414442@item EINTR
    415443The log_seek() function was interrupted by a signal.
     444
    416445@item EINVAL
    417446The log_recid argument is not a valid record id.
    418 @item ENOSYS
    419 The function log_seek() is not supported by this implementation.
    420 
    421 @end table
    422 
    423 @subheading DESCRIPTION:
    424 
    425 If @code{_POSIX_LOGGING} is defined:
    426 
    427    The @code{log_seek} function shall set the log file offset of the open
    428    log descriptioin associated with the @code{logdes} log file descriptor
    429    to the event record in the log file identified by @code{log_recid}. 
    430    The @code{log_recid} argument is either the record id of a valid event
    431    record or one of the following values, as defined in the header <evlog.h>:
    432       LOG_SEEK_START - Set log file position to point at the first event
    433                        record in the log file
    434       LOG_SEEK_END   - Set log file position to point after the last event
    435                        record in the log file
    436    If the @code{log_seek} function is interrupted, the state of the open log
    437    file description associated with @code{logdes} is unspecified.
    438 
    439 Otherwise:
    440 
    441    The @code{log_seek} function shall fail.
    442 
    443 @subheading NOTES:
     447
     448@end table
     449
     450@subheading DESCRIPTION:
     451
     452The @code{log_seek} function shall set the log file offset of the open
     453log descriptioin associated with the @code{logdes} log file descriptor
     454to the event record in the log file identified by @code{log_recid}. 
     455The @code{log_recid} argument is either the record id of a valid event
     456record or one of the following values, as defined in the header <evlog.h>:
     457
     458@table @b
     459@item LOG_SEEK_START
     460Set log file position to point at the first event
     461record in the log file
     462
     463@item LOG_SEEK_END
     464Set log file position to point after the last event
     465record in the log file
     466
     467@end table
     468
     469If the @code{log_seek} function is interrupted, the state of the open log
     470file description associated with @code{logdes} is unspecified.
     471
     472@subheading NOTES:
     473
     474The @code{_POSIX_LOGGING} feature flag is defined to indicate
     475this service is available.
    444476
    445477@page
     
    465497@item EINVAL
    466498The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
    467 @item ENOSYS
    468 The function log_severity_before() is not supported by this
    469 implementation.
    470 
    471 @end table
    472 
    473 @subheading DESCRIPTION:
    474 
    475 If @code{_POSIX_LOGGING} is defined:
    476 
    477    The @code{log_severity_before} function shall compare the severity order
    478    of the @code{s1} and @code{s2} arguments.  Severity values ordered
    479    according to this function shall be according to decreasing severity.
    480 
    481    If @code{s1} is ordered before or is equal to @code{s2} then the ordering
    482    predicate shall return 1, otherwise the predicate shall return 0.  If
    483    either @code{s1} or @code{s2} specify invlid severity values, the return
    484    value of @code{log_severity_before} is unspecified.
    485 
    486 Otherwise:
    487    
    488    The @code{log_severity_before} function shall fail.
    489 
    490 @subheading NOTES:
     499
     500@end table
     501
     502@subheading DESCRIPTION:
     503
     504The @code{log_severity_before} function shall compare the severity order
     505of the @code{s1} and @code{s2} arguments.  Severity values ordered
     506according to this function shall be according to decreasing severity.
     507
     508If @code{s1} is ordered before or is equal to @code{s2} then the ordering
     509predicate shall return 1, otherwise the predicate shall return 0.  If
     510either @code{s1} or @code{s2} specify invlid severity values, the return
     511value of @code{log_severity_before} is unspecified.
     512
     513@subheading NOTES:
     514
     515The @code{_POSIX_LOGGING} feature flag is defined to indicate
     516this service is available.
    491517
    492518@page
     
    511537@item EINVAL
    512538The facilityno argument is not a valid facility.
    513 @item ENOSYS
    514 The function is not supported by this implementation.
    515 
    516 @end table
    517 
    518 @subheading DESCRIPTION:
    519 
    520 If @code{_POSIX_LOGGING} is defined:
    521 
    522    The facilitysetops primitives manipulate sets of facilities.  They
    523    operate on data objects addressable by the application.
    524 
    525    The @code{log_facilityemptyset} function initializes the facility
    526    set pointed to by the argument @code{set}, such that all facilties
    527    are included.
    528 
    529    Applications shall call either @code{log_facilityemptyset} or
    530    @code{log_cacilityfillset} at least once for each object of type
    531    @code{log_facilityset_t} prior to any other use of that object.  If
    532    such an object is not initialized in this way, but is nonetheless
    533    supplied as an argument  to any of the @code{log_facilityaddset},
    534    @code{logfacilitydelset}, @code{log_facilityismember} or
    535    @code{log_open} functions, the results are undefined.
    536 
    537    The @code{log_facilityaddset} and @code{log_facilitydelset} functions
    538    respectively add or delete the individual facility specified by the
    539    value of the argument @code{facilityno} to or from the facility set
    540    pointed to by the argument @code{set}
    541 
    542    The @code{log_facilityismember} function tests whether the facility
    543    specified by the value of the argument @code{facilityno} is a member
    544    of the set pointed to by the argument @code{set}.  Upon successful
    545    completion, the @code{log_facilityismember} function either returns
    546    a value of one to the location specified by @code{member} if the
    547    specified facility is a member of the specified set or returns a
    548    value of zero to the location specified by @code{member} if the
    549    specified facility is not a member of the specified set.
    550 
    551 Otherwise:
    552 
    553    The function fails
    554 
    555 @subheading NOTES:
     539
     540@end table
     541
     542@subheading DESCRIPTION:
     543
     544The facilitysetops primitives manipulate sets of facilities.  They
     545operate on data objects addressable by the application.
     546
     547The @code{log_facilityemptyset} function initializes the facility
     548set pointed to by the argument @code{set}, such that all facilties
     549are included.
     550
     551Applications shall call either @code{log_facilityemptyset} or
     552@code{log_facilityfillset} at least once for each object of type
     553@code{log_facilityset_t} prior to any other use of that object.  If
     554such an object is not initialized in this way, but is nonetheless
     555supplied as an argument  to any of the @code{log_facilityaddset},
     556@code{logfacilitydelset}, @code{log_facilityismember} or
     557@code{log_open} functions, the results are undefined.
     558
     559The @code{log_facilityaddset} and @code{log_facilitydelset} functions
     560respectively add or delete the individual facility specified by the
     561value of the argument @code{facilityno} to or from the facility set
     562pointed to by the argument @code{set}
     563
     564The @code{log_facilityismember} function tests whether the facility
     565specified by the value of the argument @code{facilityno} is a member
     566of the set pointed to by the argument @code{set}.  Upon successful
     567completion, the @code{log_facilityismember} function either returns
     568a value of one to the location specified by @code{member} if the
     569specified facility is a member of the specified set or returns a
     570value of zero to the location specified by @code{member} if the
     571specified facility is not a member of the specified set.
     572
     573@subheading NOTES:
     574
     575The @code{_POSIX_LOGGING} feature flag is defined to indicate
     576this service is available.
    556577
    557578@page
     
    576597@item EINVAL
    577598The facilityno argument is not a valid facility.
    578 @item ENOSYS
    579 The function is not supported by this implementation.
    580 
    581 @end table
    582 
    583 @subheading DESCRIPTION:
    584 
    585 If @code{_POSIX_LOGGING} is defined:
    586 
    587    The facilitysetops primitives manipulate sets of facilities.  They
    588    operate on data objects addressable by the application.
    589 
    590    The @code{log_facilityemptyset} function initializes the facility
    591    set pointed to by the argument @code{set}, such that all facilties
    592    are included.
    593 
    594    Applications shall call either @code{log_facilityemptyset} or
    595    @code{log_cacilityfillset} at least once for each object of type
    596    @code{log_facilityset_t} prior to any other use of that object.  If
    597    such an object is not initialized in this way, but is nonetheless
    598    supplied as an argument  to any of the @code{log_facilityaddset},
    599    @code{logfacilitydelset}, @code{log_facilityismember} or
    600    @code{log_open} functions, the results are undefined.
    601 
    602    The @code{log_facilityaddset} and @code{log_facilitydelset} functions
    603    respectively add or delete the individual facility specified by the
    604    value of the argument @code{facilityno} to or from the facility set
    605    pointed to by the argument @code{set}
    606 
    607    The @code{log_facilityismember} function tests whether the facility
    608    specified by the value of the argument @code{facilityno} is a member
    609    of the set pointed to by the argument @code{set}.  Upon successful
    610    completion, the @code{log_facilityismember} function either returns
    611    a value of one to the location specified by @code{member} if the
    612    specified facility is a member of the specified set or returns a
    613    value of zero to the location specified by @code{member} if the
    614    specified facility is not a member of the specified set.
    615 
    616 Otherwise:
    617 
    618    The function fails
    619 
    620 @subheading NOTES:
     599
     600@end table
     601
     602@subheading DESCRIPTION:
     603
     604The facilitysetops primitives manipulate sets of facilities.  They
     605operate on data objects addressable by the application.
     606
     607The @code{log_facilityemptyset} function initializes the facility
     608set pointed to by the argument @code{set}, such that all facilties
     609are included.
     610
     611Applications shall call either @code{log_facilityemptyset} or
     612@code{log_facilityfillset} at least once for each object of type
     613@code{log_facilityset_t} prior to any other use of that object.  If
     614such an object is not initialized in this way, but is nonetheless
     615supplied as an argument  to any of the @code{log_facilityaddset},
     616@code{logfacilitydelset}, @code{log_facilityismember} or
     617@code{log_open} functions, the results are undefined.
     618
     619The @code{log_facilityaddset} and @code{log_facilitydelset} functions
     620respectively add or delete the individual facility specified by the
     621value of the argument @code{facilityno} to or from the facility set
     622pointed to by the argument @code{set}
     623
     624The @code{log_facilityismember} function tests whether the facility
     625specified by the value of the argument @code{facilityno} is a member
     626of the set pointed to by the argument @code{set}.  Upon successful
     627completion, the @code{log_facilityismember} function either returns
     628a value of one to the location specified by @code{member} if the
     629specified facility is a member of the specified set or returns a
     630value of zero to the location specified by @code{member} if the
     631specified facility is not a member of the specified set.
     632
     633@subheading NOTES:
     634
     635The @code{_POSIX_LOGGING} feature flag is defined to indicate
     636this service is available.
    621637
    622638@page
     
    642658@item EINVAL
    643659The facilityno argument is not a valid facility.
    644 @item ENOSYS
    645 The function is not supported by this implementation.
    646 
    647 @end table
    648 
    649 @subheading DESCRIPTION:
    650 
    651 If @code{_POSIX_LOGGING} is defined:
    652 
    653    The facilitysetops primitives manipulate sets of facilities.  They
    654    operate on data objects addressable by the application.
    655 
    656    The @code{log_facilityemptyset} function initializes the facility
    657    set pointed to by the argument @code{set}, such that all facilties
    658    are included.
    659 
    660    Applications shall call either @code{log_facilityemptyset} or
    661    @code{log_cacilityfillset} at least once for each object of type
    662    @code{log_facilityset_t} prior to any other use of that object.  If
    663    such an object is not initialized in this way, but is nonetheless
    664    supplied as an argument  to any of the @code{log_facilityaddset},
    665    @code{logfacilitydelset}, @code{log_facilityismember} or
    666    @code{log_open} functions, the results are undefined.
    667 
    668    The @code{log_facilityaddset} and @code{log_facilitydelset} functions
    669    respectively add or delete the individual facility specified by the
    670    value of the argument @code{facilityno} to or from the facility set
    671    pointed to by the argument @code{set}
    672 
    673    The @code{log_facilityismember} function tests whether the facility
    674    specified by the value of the argument @code{facilityno} is a member
    675    of the set pointed to by the argument @code{set}.  Upon successful
    676    completion, the @code{log_facilityismember} function either returns
    677    a value of one to the location specified by @code{member} if the
    678    specified facility is a member of the specified set or returns a
    679    value of zero to the location specified by @code{member} if the
    680    specified facility is not a member of the specified set.
    681 
    682 Otherwise:
    683 
    684    The function fails
    685 
    686 @subheading NOTES:
     660
     661@end table
     662
     663@subheading DESCRIPTION:
     664
     665The facilitysetops primitives manipulate sets of facilities.  They
     666operate on data objects addressable by the application.
     667
     668The @code{log_facilityemptyset} function initializes the facility
     669set pointed to by the argument @code{set}, such that all facilties
     670are included.
     671
     672Applications shall call either @code{log_facilityemptyset} or
     673@code{log_facilityfillset} at least once for each object of type
     674@code{log_facilityset_t} prior to any other use of that object.  If
     675such an object is not initialized in this way, but is nonetheless
     676supplied as an argument  to any of the @code{log_facilityaddset},
     677@code{logfacilitydelset}, @code{log_facilityismember} or
     678@code{log_open} functions, the results are undefined.
     679
     680The @code{log_facilityaddset} and @code{log_facilitydelset} functions
     681respectively add or delete the individual facility specified by the
     682value of the argument @code{facilityno} to or from the facility set
     683pointed to by the argument @code{set}
     684
     685The @code{log_facilityismember} function tests whether the facility
     686specified by the value of the argument @code{facilityno} is a member
     687of the set pointed to by the argument @code{set}.  Upon successful
     688completion, the @code{log_facilityismember} function either returns
     689a value of one to the location specified by @code{member} if the
     690specified facility is a member of the specified set or returns a
     691value of zero to the location specified by @code{member} if the
     692specified facility is not a member of the specified set.
     693
     694@subheading NOTES:
     695
     696The @code{_POSIX_LOGGING} feature flag is defined to indicate
     697this service is available.
    687698
    688699@page
     
    708719@item EINVAL
    709720The facilityno argument is not a valid facility.
    710 @item ENOSYS
    711 The function is not supported by this implementation.
    712 
    713 @end table
    714 
    715 @subheading DESCRIPTION:
    716 
    717 If @code{_POSIX_LOGGING} is defined:
    718 
    719    The facilitysetops primitives manipulate sets of facilities.  They
    720    operate on data objects addressable by the application.
    721 
    722    The @code{log_facilityemptyset} function initializes the facility
    723    set pointed to by the argument @code{set}, such that all facilties
    724    are included.
    725 
    726    Applications shall call either @code{log_facilityemptyset} or
    727    @code{log_cacilityfillset} at least once for each object of type
    728    @code{log_facilityset_t} prior to any other use of that object.  If
    729    such an object is not initialized in this way, but is nonetheless
    730    supplied as an argument  to any of the @code{log_facilityaddset},
    731    @code{logfacilitydelset}, @code{log_facilityismember} or
    732    @code{log_open} functions, the results are undefined.
    733 
    734    The @code{log_facilityaddset} and @code{log_facilitydelset} functions
    735    respectively add or delete the individual facility specified by the
    736    value of the argument @code{facilityno} to or from the facility set
    737    pointed to by the argument @code{set}
    738 
    739    The @code{log_facilityismember} function tests whether the facility
    740    specified by the value of the argument @code{facilityno} is a member
    741    of the set pointed to by the argument @code{set}.  Upon successful
    742    completion, the @code{log_facilityismember} function either returns
    743    a value of one to the location specified by @code{member} if the
    744    specified facility is a member of the specified set or returns a
    745    value of zero to the location specified by @code{member} if the
    746    specified facility is not a member of the specified set.
    747 
    748 Otherwise:
    749 
    750    The function fails
    751 
    752 @subheading NOTES:
     721
     722@end table
     723
     724@subheading DESCRIPTION:
     725
     726The facilitysetops primitives manipulate sets of facilities.  They
     727operate on data objects addressable by the application.
     728
     729The @code{log_facilityemptyset} function initializes the facility
     730set pointed to by the argument @code{set}, such that all facilties
     731are included.
     732
     733Applications shall call either @code{log_facilityemptyset} or
     734@code{log_facilityfillset} at least once for each object of type
     735@code{log_facilityset_t} prior to any other use of that object.  If
     736such an object is not initialized in this way, but is nonetheless
     737supplied as an argument  to any of the @code{log_facilityaddset},
     738@code{logfacilitydelset}, @code{log_facilityismember} or
     739@code{log_open} functions, the results are undefined.
     740
     741The @code{log_facilityaddset} and @code{log_facilitydelset} functions
     742respectively add or delete the individual facility specified by the
     743value of the argument @code{facilityno} to or from the facility set
     744pointed to by the argument @code{set}
     745
     746The @code{log_facilityismember} function tests whether the facility
     747specified by the value of the argument @code{facilityno} is a member
     748of the set pointed to by the argument @code{set}.  Upon successful
     749completion, the @code{log_facilityismember} function either returns
     750a value of one to the location specified by @code{member} if the
     751specified facility is a member of the specified set or returns a
     752value of zero to the location specified by @code{member} if the
     753specified facility is not a member of the specified set.
     754
     755@subheading NOTES:
     756
     757The @code{_POSIX_LOGGING} feature flag is defined to indicate
     758this service is available.
    753759
    754760@page
     
    775781@item EINVAL
    776782The facilityno argument is not a valid facility.
    777 @item ENOSYS
    778 The function is not supported by this implementation.
    779 
    780 @end table
    781 
    782 @subheading DESCRIPTION:
    783 
    784 If @code{_POSIX_LOGGING} is defined:
    785 
    786    The facilitysetops primitives manipulate sets of facilities.  They
    787    operate on data objects addressable by the application.
    788 
    789    The @code{log_facilityemptyset} function initializes the facility
    790    set pointed to by the argument @code{set}, such that all facilties
    791    are included.
    792 
    793    Applications shall call either @code{log_facilityemptyset} or
    794    @code{log_cacilityfillset} at least once for each object of type
    795    @code{log_facilityset_t} prior to any other use of that object.  If
    796    such an object is not initialized in this way, but is nonetheless
    797    supplied as an argument  to any of the @code{log_facilityaddset},
    798    @code{logfacilitydelset}, @code{log_facilityismember} or
    799    @code{log_open} functions, the results are undefined.
    800 
    801    The @code{log_facilityaddset} and @code{log_facilitydelset} functions
    802    respectively add or delete the individual facility specified by the
    803    value of the argument @code{facilityno} to or from the facility set
    804    pointed to by the argument @code{set}
    805 
    806    The @code{log_facilityismember} function tests whether the facility
    807    specified by the value of the argument @code{facilityno} is a member
    808    of the set pointed to by the argument @code{set}.  Upon successful
    809    completion, the @code{log_facilityismember} function either returns
    810    a value of one to the location specified by @code{member} if the
    811    specified facility is a member of the specified set or returns a
    812    value of zero to the location specified by @code{member} if the
    813    specified facility is not a member of the specified set.
    814 
    815 Otherwise:
    816 
    817    The function fails
    818 
    819 @subheading NOTES:
     783
     784@end table
     785
     786@subheading DESCRIPTION:
     787
     788The facilitysetops primitives manipulate sets of facilities.  They
     789operate on data objects addressable by the application.
     790
     791The @code{log_facilityemptyset} function initializes the facility
     792set pointed to by the argument @code{set}, such that all facilties
     793are included.
     794
     795Applications shall call either @code{log_facilityemptyset} or
     796@code{log_facilityfillset} at least once for each object of type
     797@code{log_facilityset_t} prior to any other use of that object.  If
     798such an object is not initialized in this way, but is nonetheless
     799supplied as an argument  to any of the @code{log_facilityaddset},
     800@code{logfacilitydelset}, @code{log_facilityismember} or
     801@code{log_open} functions, the results are undefined.
     802
     803The @code{log_facilityaddset} and @code{log_facilitydelset} functions
     804respectively add or delete the individual facility specified by the
     805value of the argument @code{facilityno} to or from the facility set
     806pointed to by the argument @code{set}
     807
     808The @code{log_facilityismember} function tests whether the facility
     809specified by the value of the argument @code{facilityno} is a member
     810of the set pointed to by the argument @code{set}.  Upon successful
     811completion, the @code{log_facilityismember} function either returns
     812a value of one to the location specified by @code{member} if the
     813specified facility is a member of the specified set or returns a
     814value of zero to the location specified by @code{member} if the
     815specified facility is not a member of the specified set.
     816
     817@subheading NOTES:
     818
     819The @code{_POSIX_LOGGING} feature flag is defined to indicate
     820this service is available.
    820821
    821822@page
     
    846847@subheading DESCRIPTION:
    847848
    848 If @code{_POSIX_LOGGING} is defined:
    849 
    850    This function dynamically allocates memory for the @code{ld}, associates
    851    a directory path to the @code{Ld}, andprovides access permissions to the
    852    @code{ld}.
    853 
    854 Otherwise:
    855 
    856    The function fails
    857 
    858 @subheading NOTES:
     849This function dynamically allocates memory for the @code{ld}, associates
     850a directory path to the @code{Ld}, andprovides access permissions to the
     851@code{ld}.
     852
     853@subheading NOTES:
     854
     855The @code{_POSIX_LOGGING} feature flag is defined to indicate
     856this service is available.
    859857
    860858@page
     
    882880@subheading DESCRIPTION:
    883881
    884 If @code{_POSIX_LOGGING} is defined:
    885 
    886    This function will create a predefined system log directory path and system log
    887    file if they do not already exist.
    888 
    889 Otherwise:
    890 
    891    The function fails
    892 
    893 @subheading NOTES:
    894 
    895 
    896 
     882This function will create a predefined system log directory path and
     883system log file if they do not already exist.
     884
     885@subheading NOTES:
     886
     887The @code{_POSIX_LOGGING} feature flag is defined to indicate
     888this service is available.
Note: See TracChangeset for help on using the changeset viewer.