RTEMS Logo

RTEMS 4.6.2 On-Line Library


Configuration Space Manager cfg_read - Read a Configuration Space

PREV UP NEXT Bookshelf New Chapters

3.4.9: cfg_read - Read a Configuration Space

CALLING SEQUENCE:

#include <cfg.h>

int cfg_read(
  CFG           *cfgp,
  CFGENT       **node
);

STATUS CODES:

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

EACCES
Search permission is denied for any component of a pathname.
EBADF
The cfgp argument does not refer to an open configuration space.
ELOOP
A loop exists in symbolic links encountered during resolution of a pathname.
ENOENT
A named node does not exist.
ENOMEM
Not enough memory is available to create the necessary structures.
ELOOP
More than SYMLOOP_MAX symbolic links were encountered during resolution of the cfgpath 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_MATH.

DESCRIPTION:

The cfg_read() function returns a pointer to a CFGENT structure representing a node in the configuration space to which cfgp refers. The returned pointer is stored at the location indicated by the node argument.

The child nodes of each node in the configuration tree is returned by cfg_read(). If a comparison routine was specified to the cfg_open() function, the order of return of the child nodes is as specified by the compar routine, from least to greatest. Otherwise, the order of return is unspecified.

Structures referencing nodes with children is returned by the function cfg_read() at least twice [unless the application specifies otherwise with 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 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:

cfg_parent
A pointer to the structure returned by the cfg_read() function for the node that contains the entry for the current node. A cfg_parent structure is provided for the node(s) specified by the pathnames argument to the cfg_open() function, but the contents of other than its cfg_number, cfg_pointer, cfg_parent, and cfg_parent, and cfg_level fields are unspecified. Its cfg_link field is unspecified.
cfg_link
Upon return from the cfg_children() function, the cfg_link field points to the next CFGENT structure in a NULL-terminated linked list of CFGENT structures. Otherwise, the content of the cfg_link field is unspecified.
cfg_cycle
If the structure being returned by cfg_read() represents a node that appears in the cfg_parent linked list tree, the cfg_cycle field shall point to the structure representing that entry from the cfg_parent linked list. Otherwise the content of the cfg_cycle field is unspecified.
cfg_number
The cfg_number field is provided for use by the application program. It is initialized to zero for each new node returned by the cfg_read() function, but is not further modified by the configuration space routines.
cfg_pointer
The cfg_pointer field is provided for use by the application program. It is initialized to NULL for each new node returned by the cfg_read() function, but is not further modified by the configuration space routines.
cfg_path
A pathname for the node including and relative to the argument supplied to the cfg_open() routine for this configuration space. This pathname may be longer than PATH_MAX bytes. This pathname is NULL-terminated.
cfg_name
The nodename of the node.
cfg_pathlen
The length of the string pointed at by the cfg_path field when returned by cfg_read().
cfg_namelen
The length of the string pointed at by the cfg_name field.
cfg_level
The depth of the current entry in the configuration space. The cfg_level field of the cfg_parent structure for each of the node(s) specified in the pathnames argument to the cfg_open() function is set to 0, and this number is incremented for each node level descendant.
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.
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 cfg_read(). The cfg_cycle field references the structure previously returned by 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 cfg_errno is set to the appropriate value.
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.
CFG_ERR
The structure represents a node for which an error has occurred. The variable cfg_errno is 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.

Structures returned by cfg_read() with a cfg_info field equal to CFG_D is accessible until a subsequent call, on the same configuration traversal stream, to cfg_close(), or to cfg_read() after they have been returned by the cfg_read function in post-order. Structures returned by cfg_read() with an cfg_info field not equal to CFG_D is accessible until a subsequent call, on the same configuration traversal stream, to cfg_close() or cfg_read().

The content of the cfg_path field is specified only for the structure most recently returned by cfg_read().

The specified fields in structures in the list representing nodes for which structures have previously been returned by cfg_children(), is identical to those returned by cfg_children(), except that the contents of the cfg_path and cfg_pathlen fields are unspecified.

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