From d0eabc94b0c6239dffbcdc1388697b3a80067e91 Mon Sep 17 00:00:00 2001 From: Ralf Corsepius Date: Thu, 19 Jan 2006 06:20:07 +0000 Subject: Remove. --- doc/new_chapters/confspace.t | 1351 ------------------------------------------ 1 file changed, 1351 deletions(-) delete mode 100644 doc/new_chapters/confspace.t (limited to 'doc') diff --git a/doc/new_chapters/confspace.t b/doc/new_chapters/confspace.t deleted file mode 100644 index fd5660a018..0000000000 --- a/doc/new_chapters/confspace.t +++ /dev/null @@ -1,1351 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@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 provides a portable -interface for manipulating configuration data. -The capabilities in this manager were defined in the POSIX -1003.1h/D3 proposed standard titled @b{Services for Reliable, -Available, and Serviceable Systems}. - -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_readdir} - Reads a directory -@item @code{cfg_umask} - Sets a file creation mask -@item @code{cfg_chmod} - Changes file mode -@item @code{cfg_chown} - Changes the owner and/or group of a file -@end itemize - -@section Background - -@subsection Configuration Nodes - -@subsection Configuration Space - -@subsection Format of a Configuration Space File - -@section Operations - -@subsection Mount and Unmounting - -@subsection Creating a Configuration Node - -@subsection Removing a Configuration Node - -@subsection Manipulating a Configuration Node - -@subsection Traversing a Configuration Space - -@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 -#include - -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: - -A successful call to @code{cfg_mount()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@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 @code{file} argument does not exist - -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters while -@code{_POSIX_NO_TRUNC} is in effect. - -@item ENOENT -A component of @code{cfgpath} does not exist. - -@item ENOTDIR -A component of the @code{file} path prefix is not a directory. - -@item EBUSY -The configuration space defined by @code{file} is already mounted. - -@item EINVAL -The notification argument specifies an invalid log facility. - -@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 is -mounted in the active space at the point identified by the -@code{cfgpath} configuration pathname. - -The @code{notification} argument specifies how changes to the -mapped configuration space are communicated to the application. -If the @code{notification} argument is NULL, no notification will be -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 are -logged. Otherwise, the @code{notification} argument specifies -an implementation defined method of notifying the application -of changes to the mapped configuration space. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_unmount - Unmount a Configuration Space - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_unmount( - const char *cfgpath -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_umount()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@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 @code{cfgpath} does not exist. - -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters while -@code{_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 ELOOP -A node appears more than once in the path specified by the -@code{cfgpath} argument - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the cfgpath argument - -@end table - -@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{cfgpath} configuration pathname. All system resources -allocated for this configuration space should be deallocated. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_mknod - Create a Configuration Node - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -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: - -A successful call to @code{cfg_mknod()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters while -@code{_POSIX_NO_TRUNC} is in effect. - -@item ENOENT -A component of the path prefix 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 EEXIST -The named node exists. - -@item EINVAL -The value of @code{mode} is invalid. - -@item EINVAL -The value of @code{type} is invalid. - -@item ELOOP -A node appears more than once in the path specified by the -@code{cfg_path} argument - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the @code{cfgpath} argument. - -@item EROFS -The named @code{node} resides on a read-only configuration space. - -@end table - -@subheading DESCRIPTION: - -The @code{cfg_mknod()} function creates a new node in the configuration -space which contains the pathname prefix of @code{cfgpath}. The node -name is defined by the pathname suffix of @code{cfgpath}. The node -permissions are specified by the value of @code{mode}. The node type -is specified by the value of @code{type}. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_get - Get Configuration Node Value - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_get( - const char *cfgpath - cfg_value_t *value -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_get()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters while -@code{_POSIX_NO_TRUNC} is in effect. - -@item ENOENT -A component of @code{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 privileges. - -@item ELOOP -A node appears more than once in the path specified by the -@code{cfgpath} argument - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the @code{cfgpath} argument. - -@end table - -@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. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_set - Set Configuration Node Value - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_set( - const char *cfgpath - cfg_value_t *value -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_set()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters while -@code{_POSIX_NO_TRUNC} is in effect. - -@item ENOENT -A component of @code{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 ELOOP -A node appears more than once in the path specified by the -@code{cfgpath} argument. - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the cfgpath argument. - -@end table - -@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. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_link - Create a Configuration Link - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_link( - const char *src - const char *dest -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_link()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters while -@code{_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 @code{src} does not exist. - -@item EEXIST -The node named by @code{dest} does exist. - -@item EPERM -The calling process does not have the appropriate privilege to -modify the node indicated by the @code{src} argument. - -@item EXDEV -The link named by @code{dest} and the node named by @code{src} are from different -configuration spaces. - -@item ENOSPC -The node in which the entry for the new link is being 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. - -@end table - -@subheading DESCRIPTION: - -The @code{src} and @code{dest} arguments point to pathnames which -name existing nodes. The @code{cfg_link()} function atomically creates -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_link()} function fails, no link is created, and the -link count of the node remains unchanged by this function call. - - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_unlink - Remove a Configuration Link - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_unlink( - const char *cfgpath -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_unlink()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item ENAMETOOLONG -A component of a pathname exceeded @code{NAME_MAX} characters, -or an entire path name exceed @code{PATH_MAX} characters. - -@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 @code{cfgpath} does not exist. - -@item EPERM -The calling process does not have the appropriate privilege to -modify the node indicated by the path prefix of the @code{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-only configuration space. - -@item ELOOP -A node appears more than once in the path specified by the -@code{cfgpath} argument. - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the cfgpath argument. - -@end table - -@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{cfgpath}, and decrements the link count -of the @code{cfgpath} node. - -When the link count of the node becomes zero, the space occupied -by the node is freed and the node is no longer be accessible. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_open - Open a Configuration Space - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_open( - const char *pathnames[], - int options, - int (*compar)(const CFGENT **f1, const CFGENT **f2), - CFG **cfgstream -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_open()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@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 @code{PATH_MAX}, or a pathname -component is longer than @code{NAME_MAX} while @code{_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 @code{CFG_LOGICAL} and @code{CFG_PHYSICAL} are -specified by the @code{options} argument - -@item ENOMEM -Not enough memory is available to create the necessary structures. - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the @code{pathnames} argument. - -@item ENAMETOOLONG -As a result of encountering a symbolic link in resolution of the -pathname specified by the @code{pathnames} argument, the length of -the substituted pathname string exceeded @code{PATH_MAX}. - -@end table - -@subheading DESCRIPTION: - -The @code{cfg_open()} function opens a configuration traversal stream -rooted in the configuration nodes name by the @code{pathnames} argument. -It stores 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 is a NULL pointer. - -The value of @code{options} is the bitwise inclusive OR of values from the -following lists. Applications supply exactly one of the first two values -below in @code{options}. - -@table @b - -@item CFG_LOGICAL -When symbolic links referencing existing nodes are -encountered during the traversal, the @code{cfg_info} -field of the returned CFGENT structure describes 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 of -its descendants, followed by a post-order return, is done. - -@item CFG_PHYSICAL -When symbolic links are encountered during the traversal, -the @code{cfg_info} field is used to describe the symbolic -link. - -@end table - - -Any combination of the remaining flags can be specified in the value of -@code{options} - -@table @b - -@item 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 -describes 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, is done. - -@item CFG_XDEV -The configuration space functions do not return a -CFGENT structure for any node in a different configuration -space than the configuration space of the nodes identified -by the CFGENT structures for the @code{pathnames} argument. - -@end table - -The @code{cfg_open()} argument @code{compar} is either a NULL or point -to a function that is called with two pointers to pointers to CFGENT -structures that returns 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 is 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 is from the least to the greatest. If the @code{compar} -argument is NULL, the order of traversal shall is listed in the -@code{pathnames} argument. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_read - Read a Configuration Space - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_read( - CFG *cfgp, - CFGENT **node -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_read()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item EACCES -Search permission is denied for any component of a pathname. - -@item EBADF -The @code{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 @code{node} does not exist. - -@item ENOMEM -Not enough memory is available to create the necessary structures. - -@item ELOOP -More than @code{SYMLOOP_MAX} symbolic links were encountered during -resolution of the cfgpath argument. - -@item ENAMETOOLONG -As a result of encountering a symbolic link in resolution of the -pathname specified by the pathnames argument, the length of the -substituted pathname string exceeded @code{PATH_MATH}. - -@end table - -@subheading DESCRIPTION: - -The @code{cfg_read()} function returns a pointer to a CFGENT structure -representing a node in the configuration space to which @code{cfgp} -refers. The returned pointer is 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 was specified to the -@code{cfg_open()} function, the order of return of the child nodes is -as specified by the @code{compar} routine, from least to greatest. -Otherwise, the order of return is unspecified. - -Structures referencing nodes with children is 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-order (with the exception of the -@code{cfg_info} field) is identical to that returned in pre-order. -Structures referencing nodes of other types is returned at least -once. - -The fields of the CFGENT structure contains the following -information: - -@table @b - -@item 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 is 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. - -@item 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. - -@item 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. - -@item cfg_number -The @code{cfg_number} field is provided for use by the -application program. It is initialized to zero for -each new node returned by the @code{cfg_read()} function, -but is not further modified by the configuration space -routines. - -@item cfg_pointer -The @code{cfg_pointer} field is provided for use by the -application program. It is initialized to NULL for -each new node returned by the @code{cfg_read()} function, -but is not further modified by the configuration -space routines. - -@item 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 longer than -@code{PATH_MAX} bytes. This pathname is NULL-terminated. - -@item cfg_name -The nodename of the node. - -@item cfg_pathlen -The length of the string pointed at by the @code{cfg_path} -field when returned by @code{cfg_read()}. - -@item cfg_namelen -The length of the string pointed at by the @code{cfg_name} -field. - -@item cfg_level -The depth of the current entry in the configuration space. -The @code{cfg_level} field of the @code{cfg_parent} -structure for each of the node(s) specified in the -@code{pathnames} argument to the @code{cfg_open()} function -is set to 0, and this number is incremented for each -node level descendant. - -@item cfg_info -This field contains one of the values listed below. If -an object can have more than one info value, the first -appropriate value listed below is returned. - -@table @b - -@item CFG_D -The structure represents a node with children in -pre-order. - -@item 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 references the structure -previously returned by @code{cfg_read} that is the -same as the returned structure. - -@item CFG_DEFAULT -The structure represents a node that is not -represented by one of the other node types - -@item CFG_DNR -The structure represents a node, not of type symlink, -that is unreadable. The variable @code{cfg_errno} -is set to the appropriate value. - -@item CFG_DP -The structure represents a node with children in -post-order. This value occurs only if CFG_D -has previously been returned for this entry. - -@item CFG_ERR -The structure represents a node for which an error has -occurred. The variable @code{cfg_errno} is set to the -appropriate value. - -@item CFG_F -The structure represents a node without children. - -@item CFG_SL -The structure represents a node of type symbolic link. - -@item CFG_SLNONET -The structure represents a node of type symbolic link -with a target node for which node characteristic -information cannot be obtained. - -@end table - -@end table - -Structures returned by @code{cfg_read()} with a @code{cfg_info} field equal -to CFG_D is 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 returned by @code{cfg_read()} with an -@code{cfg_info} field not equal to CFG_D is 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()}, -is identical to those returned by @code{cfg_children()}, except that -the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are -unspecified. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_children - Get Node Entries - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_children( - CFG *cfgp, - int options, - CFGENT **children -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_children()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item EACCES -Search permission is denied for any component of a pathname - -@item EBADF -The @code{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 @code{PATH_MAX}, or a pathname -component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is -in effect. - -@item EINVAL -The specified value of the @code{options} argument is invalid. - -@item ENOENT -The named node does not exist. - -@item ENOMEM -Not enough memory is available to create the necessary structures. - -@end table - -@subheading DESCRIPTION: - -The first @code{cfg_children()} call after a @code{cfg_read()} returns -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()} -returns 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 is NULL-terminated, ordered by the -user-specified comparison function, if any, and linked through the -@code{cfg_link} field. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_mark - Set Configuration Space Options - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_mark( - CFG *cfgp, - CFGENT *f, - int options -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_mark()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item EINVAL -The specified combination of the @code{cfgp} and @code{f} arguments is not -supported by the implementation. - -@item EINVAL -The specified value of the @code{options} argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{cfg_mark()} function modifies the subsequent behavior of -the @code{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 is NULL. - -The value of the @code{options} argument is exactly one of the flags -specified in the following list: - -@table @b - -@item 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()} returns an error. Otherwise, the next -call to the @code{cfg_read()} function returns the structure -referenced by @code{f} with the @code{cfg_info} field -reinitialized. Subsequent behavior of the @code{cfg} -functions are based on the reinitialized value of -@code{cfg_info}. - -@item 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()} returns an error. Otherwise, no -more structures for the node referenced by @code{f} or its -descendants are returned by the @code{cfg_read()} function. - -@item 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()} returns an error. Otherwise, the next -call to the @code{cfg_read()} function returns 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 done. - -@end table - -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}. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_close - Close a Configuration Space - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int cfg_close( - CFG *cfgp -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_close()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item EBADF -The @code{cfgp} argument does not refer to an open configuration space -traversal stream. - -@end table - -@subheading DESCRIPTION: - -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 -traversal stream should be deallocated. Upon return, the value of -@code{cfgp} need not point to an accessible object of type CFG. - -@subheading NOTES: - -The @code{_POSIX_CFG} feature flag is defined to indicate -this service is available. - -@page -@subsection cfg_readdir - Reads a directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -struct dirent *cfg_readdir( - DIR *dirp -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EBADF -Invalid file descriptor - -@end table - -@subheading DESCRIPTION: - -The @code{cfg_readdir()} function returns a pointer to a structure @code{dirent} -representing the next directory entry from the directory stream pointed to -by @code{dirp}. On end-of-file, NULL is returned. - -The @code{cfg_readdir()} function may (or may not) return entries for . or .. Your -program should tolerate reading dot and dot-dot but not require them. - -The data pointed to be @code{cfg_readdir()} may be overwritten by another call to -@code{readdir()} for the same directory stream. It will not be overwritten by -a call for another directory. - -@subheading NOTES: - -If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or -@code{realloc()} or has been deallocated with @code{free()} or @code{realloc()}, -the results are not portable and are probably disastrous. - -This function is not defined in the POSIX specification. It is an extension -provided by this implementation. - -@page -@subsection cfg_umask - Sets a file creation mask. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -mode_t cfg_umask( - mode_t cmask -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@subheading DESCRIPTION: - -The @code{cfg_umask()} function sets the process node creation mask to @code{cmask}. -The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()}, -@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument. -Bit positions that are set in @code{cmask} are cleared in the mode of the -created file. - -The file creation mask is inherited across @code{fork()} and @code{exec()} calls. -This makes it possible to alter the default permission bits of created files. - -@subheading NOTES: None - -The @code{cmask} argument should have only permission bits set. All other -bits should be zero. - -@page -@subsection cfg_chmod - Changes file mode. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int cfg_chmod( - const char *path, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_chmod()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. -@item ENOENT -A file or directory does not exist. -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -Set the file permission bits, the set user ID bit, and the set group ID bit -for the file named by @code{path} to @code{mode}. If the effective user ID -does not match the owner of the node and the calling process does not have -the appropriate privileges, @code{cfg_chmod()} returns -1 and sets @code{errno} to -@code{EPERM}. - -@subheading NOTES: - -@page -@subsection cfg_chown - Changes the owner and/or group of a file. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int cfg_chown( - const char *path, - uid_t owner, - gid_t group -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{cfg_chown()} returns a value of zero -and an unsuccessful call returns the @code{errno}. - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix -@item EINVAL -Invalid argument -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. -@item ENOENT -A file or directory does not exist. -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -The user ID and group ID of the file named by @code{path} are set to -@code{owner} and @code{path}, respectively. - -For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID) -bits are cleared. - -Some systems consider it a security violation to allow the owner of a file to -be changed, If users are billed for disk space usage, loaning a file to -another user could result in incorrect billing. The @code{cfg_chown()} function -may be restricted to privileged users for some or all files. The group ID can -still be changed to one of the supplementary group IDs. - -@subheading NOTES: - -This function may be restricted for some file. The @code{pathconf} function -can be used to test the _PC_CHOWN_RESTRICTED flag. - - -- cgit v1.2.3