source: rtems/doc/new_chapters/confspace.t @ 4be3f4d

@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved. 
@c
@c  $Id$
@c

@chapter Configuration Space Manager

@section Introduction

The configuration space manager provides a portable
interface for manipulating configuration data.
The capabilities in this manager were defined in the POSIX
1003.1h/D3 proposed standard titled @b{Services for Reliable,
Available, and Serviceable Systems}.

The directives provided by the configuration space manager are:

@itemize @bullet
@item @code{cfg_mount} - Mount a Configuration Space
@item @code{cfg_unmount} - Unmount a Configuration Space
@item @code{cfg_mknod} - Create a Configuration Node
@item @code{cfg_get} - Get Configuration Node Value
@item @code{cfg_set} - Set Configuration Node Value
@item @code{cfg_link} - Create a Configuration Link
@item @code{cfg_unlink} - Remove a Configuration Link
@item @code{cfg_open} - Open a Configuration Space
@item @code{cfg_read} - Read a Configuration Space
@item @code{cfg_children} - Get Node Entries
@item @code{cfg_mark} - Set Configuration Space Option
@item @code{cfg_readdir} - Reads a directory
@item @code{cfg_umask} - Sets a file creation mask
@item @code{cfg_chmod} - Changes file mode
@item @code{cfg_chown} - Changes the owner and/or group of a file
@end itemize

@section Background

@subsection Configuration Nodes

@subsection Configuration Space

@subsection Format of a Configuration Space File

@section Operations

@subsection Mount and Unmounting

@subsection Creating a Configuration Node

@subsection Removing a Configuration Node

@subsection Manipulating a Configuration Node

@subsection Traversing a Configuration Space

@section Directives

This section details the configuration space manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.

@page
@subsection cfg_mount - Mount a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_mount(
  const char     *file,
  const char     *cfgpath,
  log_facility_t  notification,
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_mount()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EPERM
The caller does not have the appropriate privilege.

@item EACCES
Search permission is denied for a component of the path prefix.

@item EEXIST
The file specified by the @code{file} argument does not exist

@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of @code{cfgpath} does not exist.

@item ENOTDIR
A component of the @code{file} path prefix is not a directory.

@item EBUSY
The configuration space defined by @code{file} is already mounted.

@item EINVAL
The notification argument specifies an invalid log facility.

@end table

@subheading DESCRIPTION:

The @code{cfg_mount()} function maps a configuration space defined
by the file identified by the the @code{file} argument.  The 
distinguished node of the mapped configuration space is
mounted in the active space at the point identified by the
@code{cfgpath} configuration pathname.

The @code{notification} argument specifies how changes to the
mapped configuration space are communicated to the application.
If the @code{notification} argument is NULL, no notification will be
be performed for the mapped configuration space.  If the Event
Logging option is defined, the notification argument defines the
facility to which changes in the mapped configuration space are
logged.  Otherwise, the @code{notification} argument specifies
an implementation defined method of notifying the application
of changes to the mapped configuration space.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_unmount - Unmount a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_unmount(
  const char     *cfgpath
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_umount()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EPERM
The caller does not have the appropriate privileges.

@item EACCES
Search permission is denied for a component of the path prefix.

@item ENOENT
A component of @code{cfgpath} does not exist.

@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item EINVAL
The requested node is not the distinguished node of a mounted
configuration space.

@item EBUSY
One or more processes has an open configuration traversal
stream for the configuration space whose distinguished node is
referenced by the cfgpath argument.

@item ELOOP
A node appears more than once in the path specified by the 
@code{cfgpath} argument

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument

@end table

@subheading DESCRIPTION:

The @code{cfg_umount()} function unmaps the configuration space whose 
distinguished node is mapped in the active space at the location defined
by @code{cfgpath} configuration pathname.  All system resources 
allocated for this configuration space should be deallocated.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_mknod - Create a Configuration Node

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_mknod(
  const char   *cfgpath,
  mode_t        mode,
  cfg_type_t    type         
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_mknod()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of the path prefix does not exist.

@item EACCES
Search permission is denied for a component of the path prefix.


@item EPERM
The calling process does not have the appropriate privilege.

@item EEXIST
The named node exists.

@item EINVAL
The value of @code{mode} is invalid.

@item EINVAL
The value of @code{type} is invalid.

@item ELOOP
A node appears more than once in the path specified by the 
@code{cfg_path} argument

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the @code{cfgpath} argument.

@item EROFS
The named @code{node} resides on a read-only configuration space.

@end table

@subheading DESCRIPTION:

The @code{cfg_mknod()} function creates a new node in the configuration
space which contains the pathname prefix of @code{cfgpath}.  The node
name is defined by the pathname suffix of @code{cfgpath}. The node
permissions are specified by the value of @code{mode}.  The node type
is specified by the value of @code{type}.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_get - Get Configuration Node Value

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_get(
  const char  *cfgpath
  cfg_value_t *value
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_get()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of @code{cfgpath} does not exist.

@item EACCES
Search permission is denied for a component of the path prefix.

@item EPERM
The calling process does not have the appropriate privileges.

@item ELOOP
A node appears more than once in the path specified by the 
@code{cfgpath} argument

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the @code{cfgpath} argument.

@end table

@subheading DESCRIPTION:

The @code{cfg_get()} function stores the value attribute of the
configuration node identified by @code{cfgpath}, into the buffer
described by the @code{value} pointer.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_set - Set Configuration Node Value

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_set(
  const char  *cfgpath
  cfg_value_t *value
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_set()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of @code{cfgpath} does not exist

@item EACCES
Search permission is denied for a component of the path prefix.

@item EPERM
The calling process does not have the appropriate privilege.

@item ELOOP
A node appears more than once in the path specified by the
@code{cfgpath} argument.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

The @code{cfg_set()} function stores the value specified by the
@code{value} argument in the configuration node defined by the 
@code{cfgpath} argument.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_link - Create a Configuration Link

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_link(
  const char *src
  const char *dest
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_link()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of either path prefix does not exist.

@item EACCES
A component of either path prefix denies search permission.

@item EACCES
The requested link requires writing in a node with a mode that
denies write permission.

@item ENOENT
The node named by @code{src} does not exist.

@item EEXIST
The node named by @code{dest} does exist.

@item EPERM
The calling process does not have the appropriate privilege to
modify the node indicated by the @code{src} argument.

@item EXDEV
The link named by @code{dest} and the node named by @code{src} are from different
configuration spaces.

@item ENOSPC
The node in which the entry for the new link is being placed
cannot be extended because there is no space left on the 
configuration space containing the node.

@item EIO
An I/O error occurred while reading from or writing to the 
configuration space to make the link entry.

@item EROFS
The requested link requires writing in a node on a read-only
configuration space.

@end table

@subheading DESCRIPTION:

The @code{src} and @code{dest} arguments point to pathnames which 
name existing nodes.  The @code{cfg_link()} function atomically creates
a link between specified nodes, and increment by one the link count 
of the node specified by the @code{src} argument. 

If the @code{cfg_link()} function fails, no link is created, and the
link count of the node remains unchanged by this function call.


@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_unlink - Remove a Configuration Link

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_unlink(
  const char    *cfgpath
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_unlink()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters.

@item EACCES
Search permission is denied on the node containing the link to
be removed.

@item EACCES
Write permission is denied on the node containing the link to 
be removed.

@item ENOENT
A component of @code{cfgpath} does not exist.

@item EPERM
The calling process does not have the appropriate privilege to 
modify the node indicated by the path prefix of the @code{cfgpath}
argument.

@item EBUSY
The node to be unlinked is the distinguished node of a mounted
configuration space.

@item EIO
An I/O error occurred while deleting the link entry or deallocating
the node.

@item EROFS
The named node resides in a read-only configuration space.

@item ELOOP
A node appears more than once in the path specified by the
@code{cfgpath} argument.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

The @code{cfg_unlink()} function removes the link between the node
specified by the @code{cfgpath} path prefix and the parent node 
specified by @code{cfgpath}, and decrements the link count 
of the @code{cfgpath} node.

When the link count of the node becomes zero, the space occupied
by the node is freed and the node is no longer be accessible.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_open - Open a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_open(
  const char     *pathnames[],
  int             options,
  int           (*compar)(const CFGENT **f1, const CFGENT **f2),
  CFG           **cfgstream
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_open()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EACCES
Search permission is denied for any component of a pathname.

@item ELOOP
A loop exists in symbolic links encountered during resolution 
of a pathname.

@item ENAMETOOLONG
The length of a pathname exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}

@item ENOENT
The pathname argument is an empty string or the named node
does not exist.

@item EINVAL
Either both or neither of @code{CFG_LOGICAL} and @code{CFG_PHYSICAL} are
specified by the @code{options} argument

@item ENOMEM
Not enough memory is available to create the necessary structures.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the @code{pathnames} argument.

@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the @code{pathnames} argument, the length of
the substituted pathname string exceeded @code{PATH_MAX}.

@end table

@subheading DESCRIPTION:

The @code{cfg_open()} function opens a configuration traversal stream
rooted in the configuration nodes name by the @code{pathnames} argument.
It stores a pointer to a CFG object that represents that stream at 
the location identified the @code{cfgstream} pointer.  The @code{pathnames}
argument is an array of character pointers to NULL-terminated strings. 
The last member of this array is a NULL pointer.

The value of @code{options} is the bitwise inclusive OR of values from the 
following lists.  Applications supply exactly one of the first two values
below in @code{options}.

@table @b

@item CFG_LOGICAL
When symbolic links referencing existing nodes are 
encountered during the traversal, the @code{cfg_info}
field of the returned CFGENT structure describes the
target node pointed to by the link instead of the 
link itself, unless the target node does not exist. 
If the target node has children, the pre-order return,
followed by the return of structures referencing all of
its descendants, followed by a post-order return, is done.
                    
@item CFG_PHYSICAL
When symbolic links are encountered during the traversal,
the @code{cfg_info} field is used to describe the symbolic 
link.

@end table
                    

Any combination of the remaining flags can be specified in the value of 
@code{options}

@table @b

@item CFG_COMFOLLOW
When symbolic links referencing existing nodes are
specified in the @code{pathnames} argument, the 
@code{cfg_info} field of the returned CFGENT structure
describes the target node pointed to by the link
instead of the link itself, unless the target node does
not exist.  If the target node has children, the 
pre-order return, followed by the return of structures
referencing all its descendants, followed by a post-order
return, is done.

@item CFG_XDEV
The configuration space functions do not return a
CFGENT structure for any node in a different configuration
space than the configuration space of the nodes identified 
by the CFGENT structures for the @code{pathnames} argument.

@end table

The @code{cfg_open()} argument @code{compar} is either a NULL or point
to a function that is called with two pointers to pointers to CFGENT 
structures that returns less than, equal to , or greater than zero if 
the node referenced by the first argument is considered to be respectively
less than, equal to, or greater than the node referenced by the second.
The CFGENT structure fields provided to the comparison routine is as 
described with the exception that the contents of the @code{cfg_path} and
@code{cfg_pathlen} fields are unspecified.

This comparison routine is used to determine the order in which nodes in
directories encountered during the traversal are returned, and the order
of traversal when more than one node is specified in the @code{pathnames}
argument to @code{cfg_open()}.  If a comparison routine is specified, the
order of traversal is from the least to the greatest.  If the @code{compar}
argument is NULL, the order of traversal shall is listed in the 
@code{pathnames} argument. 

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_read - Read a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_read(  
  CFG           *cfgp,
  CFGENT       **node
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_read()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EACCES
Search permission is denied for any component of a pathname.

@item EBADF
The @code{cfgp} argument does not refer to an open configuration
space.

@item ELOOP
A loop exists in symbolic links encountered during resolution
of a pathname.

@item ENOENT
A named @code{node} does not exist.

@item ENOMEM
Not enough memory is available to create the necessary structures.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the pathnames argument, the length of the
substituted pathname string exceeded @code{PATH_MATH}.

@end table

@subheading DESCRIPTION:

The @code{cfg_read()} function returns a pointer to a CFGENT structure
representing a node in the configuration space to which @code{cfgp}
refers.  The returned pointer is stored at the location indicated 
by the @code{node} argument.

The child nodes of each node in the configuration tree is returned
by @code{cfg_read()}.  If a comparison routine was specified to the
@code{cfg_open()} function, the order of return of the child nodes is
as specified by the @code{compar} routine, from least to greatest.  
Otherwise, the order of return is unspecified.

Structures referencing nodes with children is returned by the 
function @code{cfg_read()} at least twice [unless the application
specifies otherwise with @code{cfg_mark()}]-once immediately before
the structures representing their descendants, are returned 
(pre-order), and once immediately after structures representing all
of their descendants, if any, are returned (post-order).  The 
CFGENT structure returned in post-order (with the exception of the 
@code{cfg_info} field) is identical to that returned in pre-order.
Structures referencing nodes of other types is returned at least
once.

The fields of the CFGENT structure contains the following 
information:

@table @b

@item cfg_parent
A pointer to the structure returned by the 
@code{cfg_read()} function for the node that contains
the entry for the current node.  A @code{cfg_parent}
structure is provided for the node(s) specified by
the @code{pathnames} argument to the @code{cfg_open()}
function, but the contents of other than its 
@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
and @code{cfg_parent}, and @code{cfg_level} fields are
unspecified.  Its @code{cfg_link} field is unspecified.

@item cfg_link
Upon return from the @code{cfg_children()} function, the
@code{cfg_link} field points to the next CFGENT structure 
in a NULL-terminated linked list of CFGENT structures.  
Otherwise, the content of the @code{cfg_link} field is 
unspecified.

@item cfg_cycle
If the structure being returned by @code{cfg_read()} 
represents a node that appears in the @code{cfg_parent}
linked list tree, the @code{cfg_cycle} field shall point 
to the structure representing that entry from the 
@code{cfg_parent} linked list.  Otherwise the content of
the @code{cfg_cycle} field is unspecified.

@item cfg_number
The @code{cfg_number} field is provided for use by the 
application program.  It is initialized to zero for 
each new node returned by the @code{cfg_read()} function, 
but is not further modified by the configuration space
routines.

@item cfg_pointer
The @code{cfg_pointer} field is provided for use by the
application program.  It is initialized to NULL for
each new node returned by the @code{cfg_read()} function, 
but is not further modified by the configuration 
space routines.

@item cfg_path
A pathname for the node including and relative to the 
argument supplied to the @code{cfg_open()} routine for this
configuration space.  This pathname may be longer than
@code{PATH_MAX} bytes.  This pathname is NULL-terminated.

@item cfg_name
The nodename of the node.

@item cfg_pathlen
The length of the string pointed at by the @code{cfg_path}
field when returned by @code{cfg_read()}.

@item cfg_namelen
The length of the string pointed at by the @code{cfg_name}
field.

@item cfg_level
The depth of the current entry in the configuration space.
The @code{cfg_level} field of the @code{cfg_parent} 
structure for each of the node(s) specified in the 
@code{pathnames} argument to the @code{cfg_open()} function
is set to 0, and this number is incremented for each
node level descendant.

@item cfg_info
This field contains one of the values listed below.  If
an object can have more than one info value, the first 
appropriate value listed below is returned. 

@table @b

@item CFG_D
The structure represents a node with children in
pre-order.

@item CFG_DC
The structure represents a node that is a parent
of the node most recently returned by @code{cfg_read()}.
The @code{cfg_cycle} field references the structure 
previously returned by @code{cfg_read} that is the
same as the returned structure.

@item CFG_DEFAULT
The structure represents a node that is not 
represented by one of the other node types

@item CFG_DNR
The structure represents a node, not of type symlink,
that is unreadable.  The variable @code{cfg_errno}
is set to the appropriate value.

@item CFG_DP
The structure represents a node with children in
post-order.  This value occurs only if CFG_D 
has previously been returned for this entry.

@item CFG_ERR
The structure represents a node for which an error has 
occurred.  The variable @code{cfg_errno} is set to the
appropriate value.

@item CFG_F
The structure represents a node without children.

@item CFG_SL
The structure represents a node of type symbolic link.

@item CFG_SLNONET
The structure represents a node of type symbolic link
with a target node for which node characteristic
information cannot be obtained.

@end table

@end table

Structures returned by @code{cfg_read()} with a @code{cfg_info} field equal
to CFG_D is accessible until a subsequent call, on the same
configuration traversal stream, to @code{cfg_close()}, or to @code{cfg_read()}
after they have been returned by the @code{cfg_read} function in
post-order.  Structures returned by @code{cfg_read()} with an
@code{cfg_info} field not equal to CFG_D is accessible until a subsequent
call, on the same configuration traversal stream, to @code{cfg_close()}
or @code{cfg_read()}. 

The content of the @code{cfg_path} field is specified only for the
structure most recently returned by @code{cfg_read()}. 

The specified fields in structures in the list representing nodes for
which structures have previously been returned by @code{cfg_children()},
is identical to those returned by @code{cfg_children()}, except that
the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
unspecified. 
         
@subheading NOTES: 

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_children - Get Node Entries

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_children(
  CFG           *cfgp,
  int            options,
  CFGENT       **children
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_children()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EACCES
Search permission is denied for any component of a pathname

@item EBADF
The @code{cfgp} argument does not refer to an open configuration space.

@item ELOOP
A loop exists in symbolic links encountered during resolution of 
a pathname.

@item ENAMETOOLONG
The length of a pathname exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
in effect.

@item EINVAL
The specified value of the @code{options} argument is invalid.

@item ENOENT
The named node does not exist.

@item ENOMEM
Not enough memory is available to create the necessary structures.

@end table

@subheading DESCRIPTION:

The first @code{cfg_children()} call after a @code{cfg_read()} returns 
information about the first node without children under the node
returned by @code{cfg_read()}.  Subsequent calls to @code{cfg_children()}
without the intervening @code{cfg_read()} shall return information
about the remaining nodes without children under that same node.

If @code{cfg_read()} has not yet been called for the configuration
traversal stream represented by @code{cfgp}, @code{cfg_children()}
returns a pointer to the first entry in a list of the nodes 
represented by the @code{pathnames} argument to @code{cfg_open()}.

In either case, the list is NULL-terminated, ordered by the 
user-specified comparison function, if any, and linked through the
@code{cfg_link} field.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_mark - Set Configuration Space Options

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_mark(
  CFG           *cfgp,
  CFGENT        *f,
  int            options
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_mark()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EINVAL
The specified combination of the @code{cfgp} and @code{f} arguments is not 
supported by the implementation.

@item EINVAL
The specified value of the @code{options} argument is invalid.

@end table

@subheading DESCRIPTION:

The @code{cfg_mark()} function modifies the subsequent behavior of
the @code{cfg} functions with regard to the node referenced by the structure
pointed to by the argument @code{f} or the configuration space referenced 
by the structure pointed to by the argument @code{cfgp}.

Exactly one of the @code{f} argument and the @code{cfgp} argument is NULL.

The value of the @code{options} argument is exactly one of the flags
specified in the following list: 

@table @b

@item CFG_AGAIN
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not the one most recently returned by @code{cfg_read()},
@code{cfg_mark()} returns an error.  Otherwise, the next 
call to the @code{cfg_read()} function returns the structure
referenced by @code{f} with the @code{cfg_info} field
reinitialized.  Subsequent behavior of the @code{cfg}
functions are based on the reinitialized value of 
@code{cfg_info}.

@item CFG_SKIP
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not one of those specified as accessible, or the structure
referenced by @code{f} is not for a node of type pre-order 
node, @code{cfg_mark()} returns an error.  Otherwise, no 
more structures for the node referenced by @code{f} or its 
descendants are returned by the @code{cfg_read()} function.

@item CFG_FOLLOW
If the @code{cfgp} argument is non-NULL, or the @code{f} 
argument is NULL, or the structure referenced by @code{f}
is not one of those specified as accessible, or the structure
referenced by @code{f} is not for a node of type symbolic link,
@code{cfg_mark()} returns an error.  Otherwise, the next
call to the @code{cfg_read()} function returns the structure
referenced by @code{f} with the @code{cfg_info} field reset
to reflect the target of the symbolic link instead of the 
symbolic link itself.  If the target of the link is node with
children, the pre-order return, followed by the return of 
structures referencing all of its descendants, followed by a 
post-order return, shall be done.

@end table

If the target of the symbolic link does not exist, the fields
of the structure by @code{cfg_read()} shall be unmodified, except
that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_close - Close a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_close(
  CFG           *cfgp
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_close()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EBADF
The @code{cfgp} argument does not refer to an open configuration space
traversal stream.

@end table

@subheading DESCRIPTION:

The @code{cfg_close()} function closes a configuration space transversal
stream represented by the CFG structure pointed at by the @code{cfgp}
argument.  All system resources allocated for this configuration space
traversal stream should be deallocated.  Upon return, the value of 
@code{cfgp} need not point to an accessible object of type CFG.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_readdir - Reads a directory

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/types.h>
#include <dirent.h>

struct dirent *cfg_readdir(
  DIR   *dirp
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
Invalid file descriptor

@end table

@subheading DESCRIPTION:

The @code{cfg_readdir()} function returns a pointer to a structure @code{dirent}
representing the next directory entry from the directory stream pointed to
by @code{dirp}.  On end-of-file, NULL is returned.

The @code{cfg_readdir()} function may (or may not) return entries for . or .. Your
program should tolerate reading dot and dot-dot but not require them.

The data pointed to be @code{cfg_readdir()} may be overwritten by another call to
@code{readdir()} for the same directory stream.  It will not be overwritten by 
a call for another directory.

@subheading NOTES:

If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or 
@code{realloc()} or has been deallocated with @code{free()} or @code{realloc()}, 
the results are not portable and are probably disastrous.

This function is not defined in the POSIX specification.  It is an extension 
provided by this implementation.

@page
@subsection cfg_umask - Sets a file creation mask.

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/types.h>
#include <sys/stat.h>

mode_t cfg_umask(
  mode_t cmask
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@subheading DESCRIPTION:

The @code{cfg_umask()} function sets the process node creation mask to @code{cmask}.
The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()},
@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument.
Bit positions that are set in @code{cmask} are cleared in the mode of the
created file.

The file creation mask is inherited across @code{fork()} and @code{exec()} calls.
This makes it possible to alter the default permission bits of created files.

@subheading NOTES: None

The @code{cmask} argument should have only permission bits set.  All other 
bits should be zero.

@page
@subsection cfg_chmod - Changes file mode.

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/types.h>
#include <sys/stat.h>

int cfg_chmod(
  const char *path,
  mode_t      mode
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_chmod()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EACCES
Search permission is denied for a directory in a file's path prefix
@item ENAMETOOLONG
Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
effect.
@item ENOENT
A file or directory does not exist.
@item ENOTDIR
A component of the specified pathname was not a directory when a directory
was expected.
@item EPERM
Operation is not permitted.  Process does not have the appropriate priviledges
or permissions to perform the requested operations.
@item EROFS
Read-only file system.

@end table

@subheading DESCRIPTION:

Set the file permission bits, the set user ID bit, and the set group ID bit 
for the file named by @code{path} to @code{mode}.  If the effective user ID 
does not match the owner of the node and the calling process does not have 
the appropriate privileges, @code{cfg_chmod()} returns -1 and sets @code{errno} to
@code{EPERM}.

@subheading NOTES:

@page
@subsection cfg_chown - Changes the owner and/or group of a file.

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/types.h>
#include <unistd.h>

int cfg_chown(
  const char *path,
  uid_t       owner,
  gid_t       group
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

A successful call to @code{cfg_chown()} returns a value of zero
and an unsuccessful call returns the @code{errno}.

@table @b
@item EACCES
Search permission is denied for a directory in a file's path prefix
@item EINVAL
Invalid argument
@item ENAMETOOLONG
Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
effect.
@item ENOENT
A file or directory does not exist.
@item ENOTDIR
A component of the specified pathname was not a directory when a directory
was expected.
@item EPERM
Operation is not permitted.  Process does not have the appropriate priviledges
or permissions to perform the requested operations.
@item EROFS
Read-only file system.

@end table

@subheading DESCRIPTION:

The user ID and group ID of the file named by @code{path} are set to 
@code{owner} and @code{path}, respectively.

For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
bits are cleared.

Some systems consider it a security violation to allow the owner of a file to
be changed,  If users are billed for disk space usage, loaning a file to 
another user could result in incorrect billing.  The @code{cfg_chown()} function
may be restricted to privileged users for some or all files.  The group ID can
still be changed to one of the supplementary group IDs.

@subheading NOTES:

This function may be restricted for some file.  The @code{pathconf} function
can be used to test the _PC_CHOWN_RESTRICTED flag.