summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters/confspace.t
diff options
context:
space:
mode:
authorWade A Smith <warm38@juno.com>1998-08-10 22:01:23 +0000
committerWade A Smith <warm38@juno.com>1998-08-10 22:01:23 +0000
commitdf8d36014c619fa6ed006743f0af0ce36c6d811c (patch)
tree6623db33d2d262dc622a87d18b2a42ef8e95fc25 /doc/new_chapters/confspace.t
parent7344fba988145038deadd47b158d5e842d8df466 (diff)
downloadrtems-df8d36014c619fa6ed006743f0af0ce36c6d811c.tar.bz2
Updated the Description section for the Configuration Space Management
routines.
Diffstat (limited to 'doc/new_chapters/confspace.t')
-rw-r--r--doc/new_chapters/confspace.t317
1 files changed, 224 insertions, 93 deletions
diff --git a/doc/new_chapters/confspace.t b/doc/new_chapters/confspace.t
index 4d02c51bd6..a4655c2cd5 100644
--- a/doc/new_chapters/confspace.t
+++ b/doc/new_chapters/confspace.t
@@ -86,21 +86,28 @@ The cfg_mount() function is not supported by this implementation.
@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 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.
+
+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:
@@ -153,10 +160,16 @@ resolution of the cfgpath argument
@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{cfgpatah} configuration pathname. All system resources
-allocated for this configuration space should be deallocated.
+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:
@@ -215,12 +228,18 @@ The named node resides on a read-only configuration space.
@subheading DESCRIPTION:
-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}.
+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:
@@ -267,9 +286,16 @@ resolution of the cfgpath argument.
@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.
+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:
@@ -316,9 +342,16 @@ resolution of the cfgpath argument.
@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.
+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:
@@ -386,17 +419,23 @@ resolution of the cfgpath argument.
@subheading DESCRIPTION:
-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 {_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.
+ 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.
+ 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:
@@ -457,13 +496,19 @@ resolution of the cfgpath argument.
@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{cfgpaht}, and shall decrement the link count
-of the @code{cfgpath} node.
+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:
-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.
+ The @code{unlink} function shall fail.
@subheading NOTES:
@@ -519,40 +564,46 @@ the substituted pathname string exceeded {PATH_MAX}.
@subheading DESCRIPTION:
-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.
+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:
@@ -602,13 +653,47 @@ substituted pathname string exceeded {PATH_MATH}.
@subheading DESCRIPTION:
-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 {_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:
@@ -657,6 +742,28 @@ The function cfg_children() is not supported by this implementation.
@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
@@ -692,10 +799,25 @@ The function cfg_mark() is not supported by this implementation.
@subheading DESCRIPTION:
-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 f or the configuration space referenced by
-the structure pointed to by the argument @code{cfgp}.
+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:
@@ -728,8 +850,17 @@ The function cfg_close() is not supported by this implementatioin.
@subheading DESCRIPTION:
-The @code{cfg_close} function closes a configuration space transversal
-stream.
+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: