forked from Imagelibrary/rtems
Updated the description section of the cfg_open and cfg_read routines
This commit is contained in:
Wade A Smith
@@ -576,13 +576,39 @@ If {_POSIX_CFG} is defined:
|
|||||||
The value of @code{options} is the bitwise inclusive OR of values from the
|
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
|
following lists. Applications shall supply exactly one of the first two
|
||||||
values below in @code{options}.
|
values below in @code{options}.
|
||||||
CFG_LOGICAL
|
|
||||||
CFG_PHYSICAL
|
CFG_LOGICAL - When symbolic links referencing existing nodes are
|
||||||
|
encountered during the traversal, the @code{cfg_info}
|
||||||
|
field of the returned CFGENT structure shall describe
|
||||||
|
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 referenceing all of
|
||||||
|
its descendants, followed by a post-order return, shall
|
||||||
|
be done.
|
||||||
|
|
||||||
|
CFG_PHYSICAL - When symbolic links are encountered during the traversal,
|
||||||
|
the @codce{cfg_info} field shall describe the symbolic
|
||||||
|
link.
|
||||||
|
|
||||||
|
|
||||||
Any combination of the remaining flags can be specified in the value of
|
Any combination of the remaining flags can be specified in the value of
|
||||||
@code{options}
|
@code{options}
|
||||||
CFG_COMFOLLOW
|
|
||||||
CFG_XDEV
|
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
|
||||||
|
shall describe 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, shall be done.
|
||||||
|
|
||||||
|
CFG_XDEV - The configuration space functions shall not return a
|
||||||
|
CFGENT structure for any node in a different configuration
|
||||||
|
space than the configuration spacce of the nodes identified
|
||||||
|
by the CFGENT structures for the @code{pathnames} argument.
|
||||||
|
|
||||||
The @code{cfg_open} argument @code{compar} shall either be NULL or point
|
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
|
to a function that shall be called with two pointers to pointers to CFGENT
|
||||||
@@ -679,18 +705,95 @@ if {_POSIX_CFG} is defined:
|
|||||||
|
|
||||||
The fields of the CFGENT structure shall contain the following
|
The fields of the CFGENT structure shall contain the following
|
||||||
informatation:
|
informatation:
|
||||||
cfg_parent
|
cfg_parent - A pointer to the structure returned by the
|
||||||
cfg_link
|
@code{cfg_read} function for the node that contains
|
||||||
cfg_cycle
|
the entry for the current node. A @code{cfg_parent}
|
||||||
cfg_number
|
structure shall be provided for the node(s) specified
|
||||||
cfg_pointer
|
by the @code{pathnames} argument to the @code{cfg_open}
|
||||||
cfg_path
|
function, but the contents of other than its
|
||||||
cfg_name
|
@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
|
||||||
cfg_pathlen
|
and @code{cfg_parent}, and @code{cfg_level} fields are
|
||||||
cfg_namelen
|
unspecified. Its @code{cfg_link} field is unspecified.
|
||||||
cfg_level
|
cfg_link - Upon return from the @code{cfg_children} function, the
|
||||||
cfg_info
|
@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.
|
||||||
|
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.
|
||||||
|
cfg_number - The @code{cfg_number} field is provided for use by the
|
||||||
|
application program. It shall be initialized to zero for
|
||||||
|
each new node returned by the @code{cfg_read} function,
|
||||||
|
but shall not be further modified the configuration space
|
||||||
|
routines.
|
||||||
|
cfg_pointer - The @code{cfg_pointer} field is provided for use by the
|
||||||
|
application program. It shall be initialized to NULL for
|
||||||
|
each new node returned by the @code{cfg_read} function,
|
||||||
|
but shall not be further modified by the configuration
|
||||||
|
space routines.
|
||||||
|
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 logner than
|
||||||
|
{PATH_MAX} bytes. This patname shall be NULL-terminated.
|
||||||
|
cfg_name - The nodename of the node.
|
||||||
|
cfg_pathlen - The length of the string pointed at by the @code{cfg_path}
|
||||||
|
field when returned by @code{cfg_read}.
|
||||||
|
cfg_namelen - The length of the string pointed at by the @code{cfg_name}
|
||||||
|
field.
|
||||||
|
cfg_level - The depth of the current entry in the configuration space.
|
||||||
|
The @code{cfg_level} field of the @code{cfg_partent}
|
||||||
|
structure for each of the node(s) specified in the
|
||||||
|
@code{pathnames} argument to the @code{cfg_open} function
|
||||||
|
shall be set to 0, and this number shall be incremented for
|
||||||
|
for each node level descendant.
|
||||||
|
cfg_info - This field shall contain one of the values listed below. If
|
||||||
|
an object can have more than one info value, the first
|
||||||
|
appropriate value listed below shall be returned.
|
||||||
|
|
||||||
|
CFG_D - The structure represents a node with children in
|
||||||
|
pre-order.
|
||||||
|
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 shall reference the
|
||||||
|
structure previously returned by @code{cfg_read} that
|
||||||
|
is the same as the returned structure.
|
||||||
|
CFG_DEFAULT - The structure represents a node that is not
|
||||||
|
represented by one of the other node types
|
||||||
|
CFG_DNR - The structure represents a node, not of type symlink,
|
||||||
|
that is unreadable. The variable @code{cfg_errno}
|
||||||
|
shall be set to the appropriate value.
|
||||||
|
CFG_DP - The structure represents a node with children in
|
||||||
|
post-order. This value shall occur only if CFG_D
|
||||||
|
has previously been returned for this entry.
|
||||||
|
CFG_ERR - The structure represents a node for which an error has
|
||||||
|
occurred. The variable @code{cfg_errno} shall be set
|
||||||
|
to the appropriate value.
|
||||||
|
CFG_F - The structure represents a node without children.
|
||||||
|
CFG_SL - The structure represents a node of type symbolic link.
|
||||||
|
CFG_SLNONET - The structure represents a node of type symbolic link
|
||||||
|
with a target node for which node characteristic
|
||||||
|
information cannot be obtained.
|
||||||
|
|
||||||
|
Structurres returned by @code{cfg_read} with a @code{cfg_info} field equal to CFG_D
|
||||||
|
shall be 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 returnded by @code{cfg_read}
|
||||||
|
with an @code{cfg_info} field not equal to CFG_D shall be 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}, shall be identical to those
|
||||||
|
returned by @code{cfg_children}, except that the contents of the @code{cfg_path} and
|
||||||
|
@code{cfg_pathlen} fields are unspecified.
|
||||||
|
|
||||||
Otherwise:
|
Otherwise:
|
||||||
|
|
||||||
The @code{cfg_read} function shall fail.
|
The @code{cfg_read} function shall fail.
|
||||||
@@ -810,10 +913,42 @@ If {_POSIX_CF} is defined:
|
|||||||
be NULL.
|
be NULL.
|
||||||
|
|
||||||
The value of the @code{options} argument shall be exactly one of the
|
The value of the @code{options} argument shall be exactly one of the
|
||||||
flags specified in the following list:
|
flags specified in the following list:
|
||||||
CFG_AGAIN
|
|
||||||
CFG_SKIP
|
CFG_AGAIN - If the @code{cfgp} argument is non-NULL, or the @code{f}
|
||||||
CFG_FOLLOW
|
argument is NULL, or the structure referenced by @code{f}
|
||||||
|
is not the one most recently returned by @code{cfg_read},
|
||||||
|
@code{cfg_mark} ahall return an error. Otherwise, the next
|
||||||
|
call to teh @code{cfg_read} function shall return the
|
||||||
|
structure referenced by @code{f} with the @code{cfg_info}
|
||||||
|
field reinitialized. Subsequent behavior of the @code{cfg}
|
||||||
|
functions shall be based on the reinitialized value of
|
||||||
|
@code{cfg_ingo}.
|
||||||
|
|
||||||
|
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} shall return an error. Otherwise, no
|
||||||
|
more structures for the node referenced by @code{f} or its
|
||||||
|
descendants shall be returned by the @code{cfg_read} function.
|
||||||
|
|
||||||
|
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} shall return an error. Otherwise, the next
|
||||||
|
call to the @code{cfg_read} function shall return 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 don.
|
||||||
|
|
||||||
|
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}.
|
||||||
|
|
||||||
Otherwise:
|
Otherwise:
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user