summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters/confspace.t
diff options
context:
space:
mode:
authorWade A Smith <warm38@juno.com>1998-08-12 16:57:27 +0000
committerWade A Smith <warm38@juno.com>1998-08-12 16:57:27 +0000
commit3f9da79a0ae505c8824694c9df95f097d5c65100 (patch)
tree886215b08bc5e4f464f29707a40cad9752c1989a /doc/new_chapters/confspace.t
parent4f38b713975f1424f802ac725f566b850b07b821 (diff)
downloadrtems-3f9da79a0ae505c8824694c9df95f097d5c65100.tar.bz2
Updated the description section of the cfg_open and cfg_read routines
Diffstat (limited to 'doc/new_chapters/confspace.t')
-rw-r--r--doc/new_chapters/confspace.t175
1 files changed, 155 insertions, 20 deletions
diff --git a/doc/new_chapters/confspace.t b/doc/new_chapters/confspace.t
index a4655c2cd5..d42f8b944a 100644
--- a/doc/new_chapters/confspace.t
+++ b/doc/new_chapters/confspace.t
@@ -576,13 +576,39 @@ If {_POSIX_CFG} is defined:
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
+
+ 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
@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
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
informatation:
- cfg_parent
- cfg_link
- cfg_cycle
- cfg_number
- cfg_pointer
- cfg_path
- cfg_name
- cfg_pathlen
- cfg_namelen
- cfg_level
- cfg_info
-
+ 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 shall be 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.
+ 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.
+ 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:
The @code{cfg_read} function shall fail.
@@ -810,10 +913,42 @@ If {_POSIX_CF} is defined:
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
+ flags specified in the following list:
+
+ 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} 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: