source: rtems/doc/new_chapters/confspace.t @ df8d3601

@c
@c  COPYRIGHT (c) 1988-1998.
@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 is ...

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_close} - Close a Configuration Space
@end itemize

@section Background

@section Operations

@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
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:

@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 file argument does not exist
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters while
{_POSIX_NO_TRUNC} is in effect.
@item ENOENT
A component of cfgpath does not exist.
@item ENOTDIR
A component of the file path prefix is not a directory.
@item EBUSY
The configuration space defined by file is already mounted.
@item EINVAL
The notification argument specifies an invalid log facility.
@item ENOSYS
The cfg_mount() function is not supported by this implementation.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   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 shall be
   mounted in the active space at the point identified bt the
   @code{cfgpath} configuration pathname.

   The @code{notification} argument specifies how changes to the
   mapped configuration space shall be communicated to the application.
   If the @code{notification} argument is NULL, no notification shall
   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 shall
   be logged.  Otherwise, the @code{notification} argument shall
   specify an implementation defined method of notifying the application
   of changes to the mapped configuration space.

Otherwise:

   The @code{cfg_mount} function shall fail.

@subheading NOTES:

@page
@subsection cfg_unmount - Unmount a Configuration Space

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@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 cfgpath does not exist.
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters while
{_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 ENOSYS
The cfg_umount function is not supported by this implementation.
@item ELOOP
A node appears more than once in the path specified by the 
cfg_path argument
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

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

Otherwise:

   The @code{cfg_umount} function shall fail.

@subheading NOTES:

@page
@subsection cfg_mknod - Create a Configuratioin Node

@subheading CALLING SEQUENCE:

@ifset is-C
@example
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:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters while
{_POSIX_NO_TRUNC} is in effect.
@item ENOENT
A compent of the path prefix does not exist.
@item EACCES
Search permission is denied for a component of the path prefix.
@item ELOOP
Too many symbolic links were encountered in translating the 
pathname.
@item EPERM
The calling process does not have the appropriate privilege.
@item EEXIST
The named node exists.
@item EINVAL
The value of mode is invalid.
@item EINVAL
The value of type is invalid.
@item ENOSYS
The function cfg_mknod() is not supported by this implementation.
@item ELOOP
A node appears more than once in the path specified by the 
cfg_path argument
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.
@item EROFS
The named node resides on a read-only configuration space.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   The @code{cfg_mknod} function creates a new node in the configuration
   space which contains the pathname prefix of @cod{cfgpath}.  T he node
   name shall be defined by the pathname suffix of @code{cfgpath}.  The
   node name shall be defined by the pathname suffix of @code{cfgpath}. 
   The node permissions shall be specified by the value of @code{mode}.
   The node type shall be specified by the value of @code{type}.

Otherwise:

   The @code{cfg_mknod} function shall fail.

@subheading NOTES:

@page
@subsection cfg_get - Get Configuration Node Value

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters while
{_POSIX_NO_TRUNC} is in effect.
@item ENOENT
A component of 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 priviledges.
@item ENOSYS
The function cfg_get() is not supported by this implementation
@item ELOOP
A node appears more than once in the path specified by the 
cfg_path argument
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   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.

Otherwise:

   The @code{cfg_get} function shall fail.


@subheading NOTES:

@page
@subsection cfg_set - Set Configuration Node Value

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters while
{_POSIX_NO_TRUNC} is in effect.
@item ENOENT
A component of 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 ENOSYS
The function cfg_set() is not supported by this implementation.
@item ELOOP
A node appears more than once in the path specified by the
cfg-path argument.
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

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

Otherwise:

   The @code{cfg_set} function shall fail.


@subheading NOTES:

@page
@subsection cfg_link - Create a Configuration Link

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters while
{_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 src does not exist.
@item EEXIST
The node named by dest does exist.
@item EPERM
The calling process does not have the appropriate privilege to
modify the node indicated by the src argument.
@item EXDEV
The link named by dest and the node named by src are from different
configuration spaces.
@item ENOSPC
The node in which the entry for the new link is boeing 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.
@item ENOSYS
The function cfg_link() is not supported by this implementation. 
@item ELOOP
A node appears more than once in the path specified by the
cfg-path argument.
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   The @code{src} and @code{dest}arguments point to pathnnames which 
   name existing nodes.  The @code{cfg_link} function shall atomically 
   create 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_lin} function fails, no link shall be created, and
   the link count of the node shall remain unchanged by this function
   call.

   This implementation may require that the calling process has permission 
   to access the specified nodes.

Otherwise:

   The @code{cfg_link} functioin shall fail.

@subheading NOTES:

@page
@subsection cfg_unlink - Remove a Configuration Link

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded {NAME_MAX} characters,
or an entire path name exceed {PATH_MAX} characters.
@item ENOENT
The named  node does not exist.
@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 cfgpath does not exist.
@item EPERM
The calling process does not have the appropriate priviledge to 
modify the node indicated by the path prefix of the 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-opnly configuration space.
@item ENOSYS
The function cfg_unlink() is not supported by this implementation.
@item ELOOP
A node appears more than once in the path specified by the
cfg-path argument.
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   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{cfgpaht}, and shall decrement the link count 
   of the @code{cfgpath} node.

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

Otherwise:

   The @code{unlink} function shall fail.

@subheading NOTES:

@page
@subsection cfg_open - Open a Configuration Space

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@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 {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while {_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 CFG_LOGICAL and CFG_PHYSICAL are
specified by the options argument ???????????
@item ENOMEM
Not enough memory is available to create the necessary structures.
@item ENOSYS
The function cfg_open() is not supported by this implementation.
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the pathnames argument.
@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the pathnames argument, the lenght of
the substituted pathname string exceeded {PATH_MAX}.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   The @code{cfg_open} function shall open a configuration traversal stream
   rooted in the configuration nodes name by the @code{pathnames} argument.
   It shall store 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 shall be a NULL pointer.

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

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

   The @code{cfg_open} argument @code{compar} shall either be NULL or point
   to a function that shall be called with two pointers to pointers to CFGENT 
   structures that shall return 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 shall be 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 shall be from the least to the greatest.  If the 
   @code{compar} argument is NULL, the order of traversal shall be as listed
   in the @code{pathnames} argument. 

Otherwise:

   The @code{cfg_open} shall fail.

@subheading NOTES:

@page
@subsection cfg_read - Read a Configuration Space

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EACCES
Search permission is denied for any component of a pathname.
@item EBADF
The 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 node does not exist.
@item ENOMEM
Not enough memory is available to create the necessary structures.
@item ENOSYS
The function cfg_read() is not suported by this implementation.
@item ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.
@item ENAMETOOLONG
As aresult of encountering a symbolic link in resolution of the
pathname specified by the pathnames argument, the length of the
substituted pathname string exceeded {PATH_MATH}.

@end table

@subheading DESCRIPTION:

if {_POSIX_CFG} is defined:

   The @code{cfg_read} function returns a pointer to a CFGENT sturcture
   representing a node in the configuration space to which @code{cfgp}
   refers.  The returned pointer shall be 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 is specified to the
   @code{cfg_open} function, the order of return of the child nodes shall
   be as specified by the routine, from least to greatest.  Otherwise
   the order of return is unspecified.

   Structures referencing nodes with children shall be 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-porder (with the exception of the 
   @code{cfg_info} field) shall be identical to that returned in pre-order.
   Structures referencing nodes of other types shall be returned at least
   once.

   The fields of the CFGENT structure shall contain the following 
   informatation:
      cfg_parent 
      cfg_link
      cfg_cycle
      cfg_number
      cfg_pointer
      cfg_path
      cfg_name
      cfg_pathlen
      cfg_namelen
      cfg_level
      cfg_info
 
Otherwise:

   The @code{cfg_read} function shall fail.

@subheading NOTES:

@page
@subsection cfg_children - Get Node Entries

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EACCES
Search permission is denied for any component of a pathname
@item EBADF
The 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 {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is
in effect.
@item EINVAL
The specified value of the optiions argument is invalid.
@item ENOENT
The named node does not exist.
@item ENOMEM
Not enough memory is available to create the necessary structures.
@item ENOSYS
The function cfg_children() is not supported by this implementation.

@end table

@subheading DESCRIPTION:

If {_POSIX_CFG} is defined:

   The first @code{cfg_children} call after a @code{cfg_read} shall 
   return 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}
   shall return 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 shall be NULL-terminated, ordered by the 
   user-specified comparison function, if any, and linked through the
   cfg_link field.

Otherwise:

   The @code{cfg_children} function shall fail.

@subheading NOTES:

@page
@subsection cfg_mark - Set Configuration Space Options

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The specified combination of the cfgp and f arguments is not 
supported by the implementation.
@item EINVAL
The specified value of the options argument is invalid.
@item ENOSYS
The function cfg_mark() is not supported by this implementation.

@end table

@subheading DESCRIPTION:

If {_POSIX_CF} is defined:

   The @code{cfg_mark} function modifies the subsequent behavior of
   the 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 shall
   be NULL.

   The value of the @code{options} argument shall be exactly one of the
   flags specified in the following list:
      CFG_AGAIN
      CFG_SKIP
      CFG_FOLLOW

Otherwise:
   
   The @code{cfg_mark} function shall fail.

@subheading NOTES:

@page
@subsection cfg_close - Close a Configuration Space

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
The cfgp argument does not refer to an open configuration space
traversal stream.
@item ENOSYS
The function cfg_close() is not supported by this implementatioin.

@end table

@subheading DESCRIPTION:

if {_POSIX_CFG} is defined:

   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
   travsversal stream should be deallocated.  Upon return, the value of 
   @code{cfgp} need not point to an accessible object of type CFG.

Otherwise:

   The @code{cfg_close} function shall fail.

@subheading NOTES: