RTEMS Logo

RTEMS 4.6.2 On-Line Library


Configuration Space Manager cfg_open - Open a Configuration Space

PREV UP NEXT Bookshelf New Chapters

3.4.8: cfg_open - Open a Configuration Space

CALLING SEQUENCE:

#include <cfg.h>

int cfg_open(
  const char     *pathnames[],
  int             options,
  int           (*compar)(const CFGENT **f1, const CFGENT **f2),
  CFG           **cfgstream
);

STATUS CODES:

A successful call to cfg_open() returns a value of zero and an unsuccessful call returns the errno.

EACCES
Search permission is denied for any component of a pathname.
ELOOP
A loop exists in symbolic links encountered during resolution of a pathname.
ENAMETOOLONG
The length of a pathname exceeds PATH_MAX, or a pathname component is longer than NAME_MAX while _POSIX_NO_TRUNC
ENOENT
The pathname argument is an empty string or the named node does not exist.
EINVAL
Either both or neither of CFG_LOGICAL and CFG_PHYSICAL are specified by the options argument
ENOMEM
Not enough memory is available to create the necessary structures.
ELOOP
More than SYMLOOP_MAX symbolic links were encountered during resolution of the pathnames argument.
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 PATH_MAX.

DESCRIPTION:

The cfg_open() function opens a configuration traversal stream rooted in the configuration nodes name by the pathnames argument. It stores a pointer to a CFG object that represents that stream at the location identified the cfgstream pointer. The 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 options is the bitwise inclusive OR of values from the following lists. Applications supply exactly one of the first two values below in options.

CFG_LOGICAL
When symbolic links referencing existing nodes are encountered during the traversal, the 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.
CFG_PHYSICAL
When symbolic links are encountered during the traversal, the cfg_info field is used to describe the symbolic link.

Any combination of the remaining flags can be specified in the value of options

CFG_COMFOLLOW
When symbolic links referencing existing nodes are specified in the pathnames argument, the 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.
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 pathnames argument.

The cfg_open() argument 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 cfg_path and 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 pathnames argument to cfg_open(). If a comparison routine is specified, the order of traversal is from the least to the greatest. If the compar argument is NULL, the order of traversal shall is listed in the pathnames argument.

NOTES:

The _POSIX_CFG feature flag is defined to indicate this service is available.


PREV UP NEXT Bookshelf New Chapters

Copyright © 1988-2004 OAR Corporation