From 3f9da79a0ae505c8824694c9df95f097d5c65100 Mon Sep 17 00:00:00 2001 From: Wade A Smith Date: Wed, 12 Aug 1998 16:57:27 +0000 Subject: Updated the description section of the cfg_open and cfg_read routines --- doc/new_chapters/confspace.t | 175 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 155 insertions(+), 20 deletions(-) (limited to 'doc/new_chapters/confspace.t') 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: -- cgit v1.2.3