Changeset 3f9da79 in rtems


Ignore:
Timestamp:
Aug 12, 1998, 4:57:27 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
9693fac4
Parents:
4f38b713
Message:

Updated the description section of the cfg_open and cfg_read routines

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/confspace.t

    r4f38b713 r3f9da79  
    577577   following lists.  Applications shall supply exactly one of the first two
    578578   values below in @code{options}.
    579       CFG_LOGICAL
    580       CFG_PHYSICAL
     579
     580      CFG_LOGICAL   - When symbolic links referencing existing nodes are
     581                      encountered during the traversal, the @code{cfg_info}
     582                      field of the returned CFGENT structure shall describe
     583                      the target node pointed to by the link instead of the
     584                      link itself, unless the target node does not exist.
     585                      If the target node has children, the pre-order return,
     586                      followed by the return of structures referenceing all of
     587                      its descendants, followed by a post-order return, shall
     588                      be done.
     589                   
     590      CFG_PHYSICAL  - When symbolic links are encountered during the traversal,
     591                      the @codce{cfg_info} field shall describe the symbolic
     592                      link.
     593                   
    581594
    582595   Any combination of the remaining flags can be specified in the value of
    583596   @code{options}
    584       CFG_COMFOLLOW
    585       CFG_XDEV
     597
     598      CFG_COMFOLLOW - When symbolic links referencing existing nodes are
     599                      specified in the @code{pathnames} argument, the
     600                      @code{cfg_info} field of the returned CFGENT structure
     601                      shall describe the target node pointed to by the link
     602                      instead of the link itself, unless the target node does
     603                      not exist.  If the target node has children, the
     604                      pre-order return, followed by the return of structures
     605                      referencing all its descendants, followed by a post-order
     606                      return, shall be done.
     607
     608      CFG_XDEV      - The configuration space functions shall not return a
     609                      CFGENT structure for any node in a different configuration
     610                      space than the configuration spacce of the nodes identified
     611                      by the CFGENT structures for the @code{pathnames} argument.
    586612
    587613   The @code{cfg_open} argument @code{compar} shall either be NULL or point
     
    680706   The fields of the CFGENT structure shall contain the following
    681707   informatation:
    682       cfg_parent
    683       cfg_link
    684       cfg_cycle
    685       cfg_number
    686       cfg_pointer
    687       cfg_path
    688       cfg_name
    689       cfg_pathlen
    690       cfg_namelen
    691       cfg_level
    692       cfg_info
    693  
     708      cfg_parent  - A pointer to the structure returned by the
     709                    @code{cfg_read} function for the node that contains
     710                    the entry for the current node.  A @code{cfg_parent}
     711                    structure shall be provided for the node(s) specified
     712                    by the @code{pathnames} argument to the @code{cfg_open}
     713                    function, but the contents of other than its
     714                    @code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
     715                    and @code{cfg_parent}, and @code{cfg_level} fields are
     716                    unspecified.  Its @code{cfg_link} field is unspecified.
     717      cfg_link    - Upon return from the @code{cfg_children} function, the
     718                    @code{cfg_link} field points to the next CFGENT structure
     719                    in a NULL-terminated linked list of CFGENT structures. 
     720                    Otherwise, the content of the @code{cfg_link} field is
     721                    unspecified.
     722      cfg_cycle   - If the structure being returned by @code{cfg_read}
     723                    represents a node that appears in the @code{cfg_parent}
     724                    linked list tree, the @code{cfg_cycle} field shall point
     725                    to the structure representing that entry from the
     726                    @code{cfg_parent} linked list.  Otherwise the content of
     727                    the @code{cfg_cycle} field is unspecified.
     728      cfg_number  - The @code{cfg_number} field is provided for use by the
     729                    application program.  It shall be initialized to zero for
     730                    each new node returned by the @code{cfg_read} function,
     731                    but shall not be further modified the configuration space
     732                    routines.
     733      cfg_pointer - The @code{cfg_pointer} field is provided for use by the
     734                    application program.  It shall be initialized to NULL for
     735                    each new node returned by the @code{cfg_read} function,
     736                    but shall not be further modified by the configuration
     737                    space routines.
     738      cfg_path    - A pathname for the node including and relative to the
     739                    argument supplied to the @code{cfg_open} routine for this
     740                    configuration space.  This pathname may be logner than
     741                    {PATH_MAX} bytes.  This patname shall be NULL-terminated.
     742      cfg_name    - The nodename of the node.
     743      cfg_pathlen - The length of the string pointed at by the @code{cfg_path}
     744                    field when returned by @code{cfg_read}.
     745      cfg_namelen - The length of the string pointed at by the @code{cfg_name}
     746                    field.
     747      cfg_level   - The depth of the current entry in the configuration space.
     748                    The @code{cfg_level} field of the @code{cfg_partent}
     749                    structure for each of the node(s) specified in the
     750                    @code{pathnames} argument to the @code{cfg_open} function
     751                    shall be set to 0, and this number shall be incremented for
     752                    for each node level descendant.
     753      cfg_info    - This field shall contain one of the values listed below.  If
     754                    an object can have more than one info value, the first
     755                    appropriate value listed below shall be returned.
     756
     757                    CFG_D       - The structure represents a node with children in
     758                                  pre-order.
     759                    CFG_DC      - The structure represents a node that is a parent
     760                                  of the node most recently returned by @code{cfg_read}.
     761                                  The @code{cfg_cycle} field shall reference the
     762                                  structure previously returned by @code{cfg_read} that
     763                                  is the same as the returned structure.
     764                    CFG_DEFAULT - The structure represents a node that is not
     765                                  represented by one of the other node types
     766                    CFG_DNR     - The structure represents a node, not of type symlink,
     767                                  that is unreadable.   The variable @code{cfg_errno}
     768                                  shall be set to the appropriate value.
     769                    CFG_DP      - The structure represents a node with children in
     770                                  post-order.  This value shall occur only if CFG_D
     771                                  has previously been returned for this entry.
     772                    CFG_ERR     - The structure represents a node for which an error has
     773                                  occurred.  The variable @code{cfg_errno} shall be set
     774                                  to the appropriate value.
     775                    CFG_F       - The structure represents a node without children.
     776                    CFG_SL      - The structure represents a node of type symbolic link.
     777                    CFG_SLNONET - The structure represents a node of type symbolic link
     778                                  with a target node for which node characteristic
     779                                  information cannot be obtained.
     780
     781   Structurres returned by @code{cfg_read} with a @code{cfg_info} field equal to CFG_D
     782   shall be accessible until a subsequent call, on the same configuration traversal
     783   stream, to @code{cfg_close}, or to @code{cfg_read} after they have been returned by
     784   the @code{cfg_read} function in post-order.  Structures returnded by @code{cfg_read}
     785   with an @code{cfg_info} field not equal to CFG_D shall be accessible until a
     786   subsequent call, on the same configuration traversal stream, to @code{cfg_close} or
     787   @code{cfg_read}.
     788
     789   The content of the @code{cfg_path} field is specified only for the structure most
     790   recently returned by @code{cfg_read}.
     791
     792   The specified fields in structures in the list representing nodes for which structures
     793   have previously been returned by @code{cfg_children}, shall be identical to those
     794   returned by @code{cfg_children}, except that the contents of the @code{cfg_path} and
     795   @code{cfg_pathlen} fields are unspecified.
     796         
    694797Otherwise:
    695798
     
    811914
    812915   The value of the @code{options} argument shall be exactly one of the
    813    flags specified in the following list:
    814       CFG_AGAIN
    815       CFG_SKIP
    816       CFG_FOLLOW
     916   flags specified in the following list:
     917
     918      CFG_AGAIN  - If the @code{cfgp} argument is non-NULL, or the @code{f}
     919                   argument is NULL, or the structure referenced by @code{f}
     920                   is not the one most recently returned by @code{cfg_read},
     921                   @code{cfg_mark} ahall return an error.  Otherwise, the next
     922                   call to teh @code{cfg_read} function shall return the
     923                   structure referenced by @code{f} with the @code{cfg_info}
     924                   field reinitialized.  Subsequent behavior of the @code{cfg}
     925                   functions shall be based on the reinitialized value of
     926                   @code{cfg_ingo}.
     927
     928      CFG_SKIP   - If the @code{cfgp} argument is non-NULL, or the @code{f}
     929                   argument is NULL, or the structure referenced by @code{f}
     930                   is not one of those specified as accessible, or the structure
     931                   referenced by @code{f} is not for a node of type pre-order
     932                   node, @code{cfg_mark} shall return an error.  Otherwise, no
     933                   more structures for the node referenced by @code{f} or its
     934                   descendants shall be returned by the @code{cfg_read} function.
     935
     936      CFG_FOLLOW - If the @code{cfgp} argument is non-NULL, or the @code{f}
     937                   argument is NULL, or the structure referenced by @code{f}
     938                   is not one of those specified as accessible, or the structure
     939                   referenced by @code{f} is not for a node of type symbolic link,
     940                   @code{cfg_mark} shall return an error.  Otherwise, the next
     941                   call to the @code{cfg_read} function shall return the structure
     942                   referenced by @code{f} with the @code{cfg_info} field reset
     943                   to reflect the target of the symbolic link instead of the
     944                   symbolic link itself.  If the target of the link is node with
     945                   children, the pre-order return, followed by the return of
     946                   structures referencing all of its descendants, followed by a
     947                   post-order return, shall be don.
     948
     949                   If the target of the symbolic link does not exist, the fields
     950                   of the structure by @code{cfg_read} shall be unmodified, except
     951                   that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
    817952
    818953Otherwise:
Note: See TracChangeset for help on using the changeset viewer.