Changeset df8d3601 in rtems


Ignore:
Timestamp:
Aug 10, 1998, 10:01:23 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
3fbd528
Parents:
7344fba9
Message:

Updated the Description section for the Configuration Space Management
routines.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/confspace.t

    r7344fba9 rdf8d3601  
    8787
    8888@subheading DESCRIPTION:
    89 The @code{cfg_mount} function maps a configuration space defined
    90 by the file identified by the the @code{file} argument.  The
    91 distinguished node of the mapped configuration space shall be
    92 mounted in the active space at the point identified bt the
    93 @code{cfgpath} configuration pathname.
    94 
    95 The @code{notification} argument specifies how changes to the
    96 mapped configuration space shall be communicated to the application.
    97 If the @code{notification} argument is NULL, no notification shall
    98 be performed for the mapped configuration space.  If the Event
    99 Logging option is defined, the notification argument defines the
    100 facility to which changes in the mapped configuration space shall
    101 be logged.  Otherwise, the @code{notification} argument shall
    102 specify an implementation defined method of notifying the application
    103 of changes to the mapped configuration space.
     89
     90If {_POSIX_CFG} is defined:
     91
     92   The @code{cfg_mount} function maps a configuration space defined
     93   by the file identified by the the @code{file} argument.  The
     94   distinguished node of the mapped configuration space shall be
     95   mounted in the active space at the point identified bt the
     96   @code{cfgpath} configuration pathname.
     97
     98   The @code{notification} argument specifies how changes to the
     99   mapped configuration space shall be communicated to the application.
     100   If the @code{notification} argument is NULL, no notification shall
     101   be performed for the mapped configuration space.  If the Event
     102   Logging option is defined, the notification argument defines the
     103   facility to which changes in the mapped configuration space shall
     104   be logged.  Otherwise, the @code{notification} argument shall
     105   specify an implementation defined method of notifying the application
     106   of changes to the mapped configuration space.
     107
     108Otherwise:
     109
     110   The @code{cfg_mount} function shall fail.
    104111
    105112@subheading NOTES:
     
    154161@subheading DESCRIPTION:
    155162
    156 The @code{cfg_umount} function unmaps the configuration space whose
    157 distinguished node is mapped in the active space at the location defined
    158 by @code{cfgpatah} configuration pathname.  All system resources
    159 allocated for this configuration space should be deallocated.
     163If {_POSIX_CFG} is defined:
     164
     165   The @code{cfg_umount} function unmaps the configuration space whose
     166   distinguished node is mapped in the active space at the location defined
     167   by @code{cfgpatah} configuration pathname.  All system resources
     168   allocated for this configuration space should be deallocated.
     169
     170Otherwise:
     171
     172   The @code{cfg_umount} function shall fail.
    160173
    161174@subheading NOTES:
     
    216229@subheading DESCRIPTION:
    217230
    218 The @code{cfg_mknod} function creates a new node in the configuration
    219 space which contains the pathname prefix of @cod{cfgpath}.  T he node
    220 name shall be defined by the pathname suffix of @code{cfgpath}.  The
    221 node name shall be defined by the pathname suffix of @code{cfgpath}.
    222 The node permissions shall be specified by the value of @code{mode}.
    223 The node type shall be specified by the value of @code{type}.
     231If {_POSIX_CFG} is defined:
     232
     233   The @code{cfg_mknod} function creates a new node in the configuration
     234   space which contains the pathname prefix of @cod{cfgpath}.  T he node
     235   name shall be defined by the pathname suffix of @code{cfgpath}.  The
     236   node name shall be defined by the pathname suffix of @code{cfgpath}.
     237   The node permissions shall be specified by the value of @code{mode}.
     238   The node type shall be specified by the value of @code{type}.
     239
     240Otherwise:
     241
     242   The @code{cfg_mknod} function shall fail.
    224243
    225244@subheading NOTES:
     
    268287@subheading DESCRIPTION:
    269288
    270 The @code{cfg_get} function stores the value attribute of the
    271 configuration node identified by @code{cfgpath}, into the buffer
    272 described by the @code{value} pointer.
     289If {_POSIX_CFG} is defined:
     290
     291   The @code{cfg_get} function stores the value attribute of the
     292   configuration node identified by @code{cfgpath}, into the buffer
     293   described by the @code{value} pointer.
     294
     295Otherwise:
     296
     297   The @code{cfg_get} function shall fail.
     298
    273299
    274300@subheading NOTES:
     
    317343@subheading DESCRIPTION:
    318344
    319 The @code{cfg_set} function stores the value specified by the
    320 @code{value} argument in the configuration node defined by the
    321 @code{cfgpath} argument.
     345If {_POSIX_CFG} is defined:
     346
     347   The @code{cfg_set} function stores the value specified by the
     348   @code{value} argument in the configuration node defined by the
     349   @code{cfgpath} argument.
     350
     351Otherwise:
     352
     353   The @code{cfg_set} function shall fail.
     354
    322355
    323356@subheading NOTES:
     
    387420@subheading DESCRIPTION:
    388421
    389 The @code{src} and @code{dest}arguments point to pathnnames which
    390 name existing nodes.  The @code{cfg_link} function shall atomically
    391 create a link between specified nodes, and increment by one the link
    392 count of the node specified by the @code{src} argument.
    393 
    394 If the @code{cfg_lin} function fails, no link shall be created, and
    395 the link count of the node shall remain unchanged by this function
    396 call.
    397 
    398 This implementation may require that the calling process has permission
    399 to access the specified nodes.
     422If {_POSIX_CFG} is defined:
     423
     424   The @code{src} and @code{dest}arguments point to pathnnames which
     425   name existing nodes.  The @code{cfg_link} function shall atomically
     426   create a link between specified nodes, and increment by one the link
     427   count of the node specified by the @code{src} argument.
     428
     429   If the @code{cfg_lin} function fails, no link shall be created, and
     430   the link count of the node shall remain unchanged by this function
     431   call.
     432
     433   This implementation may require that the calling process has permission
     434   to access the specified nodes.
     435
     436Otherwise:
     437
     438   The @code{cfg_link} functioin shall fail.
    400439
    401440@subheading NOTES:
     
    458497@subheading DESCRIPTION:
    459498
    460 The @code{cfg_unlink} function  removes the link between the node
    461 specified by the @code{cfgpath} path prefix and the parent node
    462 specified by @code{cfgpaht}, and shall decrement the link count
    463 of the @code{cfgpath} node.
    464 
    465 When the link count of the node becomes zero, the space occupied
    466 by the node shall be freed and the node shall no longer be accessible.
     499If {_POSIX_CFG} is defined:
     500
     501   The @code{cfg_unlink} function removes the link between the node
     502   specified by the @code{cfgpath} path prefix and the parent node
     503   specified by @code{cfgpaht}, and shall decrement the link count
     504   of the @code{cfgpath} node.
     505
     506   When the link count of the node becomes zero, the space occupied
     507   by the node shall be freed and the node shall no longer be accessible.
     508
     509Otherwise:
     510
     511   The @code{unlink} function shall fail.
    467512
    468513@subheading NOTES:
     
    520565@subheading DESCRIPTION:
    521566
    522 The @code{cfg_open} function shall open a configuration traversal stream
    523 rooted in the configuration nodes name by the @code{pathnames} argument.
    524 It shall store a pointer to a CFG object that represents that stream at
    525 the location identified the @code{cfgstream} pointer.  The @code{pathnames}
    526 argument is an array of character pointers to NULL-terminated strings.
    527 The last member of this array shall be a NULL pointer.
    528 
    529 The value of @code{options} is the bitwise inclusive OR of values from the
    530 following lists.  Applications shall supply exactly one of the first two
    531 values below in @code{options}.
    532    CFG_LOGICAL
    533    CFG_PHYSICAL
    534 
    535 Any combination of the remaining flags can be specified in the value of
    536 @code{options}
    537    CFG_COMFOLLOW
    538    CFG_XDEV
    539 
    540 The @code{cfg_open} argument @code{compar} shall either be NULL or point
    541 to a function that shall be called with two pointers to pointers to CFGENT
    542 structures that shall return less than, equal to , or greater than zero if
    543 the node referenced by the first argument is considered to be respectively
    544 less than, equal to, or greater than the node referenced by the second.
    545 The CFGENT structure fields provided to the comparison routine shall be as
    546 described with the exception that the contents of the @code{cfg_path} and
    547 @code{cfg_pathlen} fields are unspecified.
    548 
    549 This comparison routine is used to determine the order in which nodes in
    550 directories encountered during the traversal are returned, and the order
    551 of traversal when more than one node is specified in the @code{pathnames}
    552 argument to @code{cfg_open}.  If a comparison routine is specified, the
    553 order of traversal shall be from the least to the greatest.  If the
    554 @code{compar} argument is NULL, the order of traversal shall be as listed
    555 in the @code{pathnames} argument.
     567If {_POSIX_CFG} is defined:
     568
     569   The @code{cfg_open} function shall open a configuration traversal stream
     570   rooted in the configuration nodes name by the @code{pathnames} argument.
     571   It shall store a pointer to a CFG object that represents that stream at
     572   the location identified the @code{cfgstream} pointer.  The @code{pathnames}
     573   argument is an array of character pointers to NULL-terminated strings.
     574   The last member of this array shall be a NULL pointer.
     575
     576   The value of @code{options} is the bitwise inclusive OR of values from the
     577   following lists.  Applications shall supply exactly one of the first two
     578   values below in @code{options}.
     579      CFG_LOGICAL
     580      CFG_PHYSICAL
     581
     582   Any combination of the remaining flags can be specified in the value of
     583   @code{options}
     584      CFG_COMFOLLOW
     585      CFG_XDEV
     586
     587   The @code{cfg_open} argument @code{compar} shall either be NULL or point
     588   to a function that shall be called with two pointers to pointers to CFGENT
     589   structures that shall return less than, equal to , or greater than zero if
     590   the node referenced by the first argument is considered to be respectively
     591   less than, equal to, or greater than the node referenced by the second.
     592   The CFGENT structure fields provided to the comparison routine shall be as
     593   described with the exception that the contents of the @code{cfg_path} and
     594   @code{cfg_pathlen} fields are unspecified.
     595
     596   This comparison routine is used to determine the order in which nodes in
     597   directories encountered during the traversal are returned, and the order
     598   of traversal when more than one node is specified in the @code{pathnames}
     599   argument to @code{cfg_open}.  If a comparison routine is specified, the
     600   order of traversal shall be from the least to the greatest.  If the
     601   @code{compar} argument is NULL, the order of traversal shall be as listed
     602   in the @code{pathnames} argument.
     603
     604Otherwise:
     605
     606   The @code{cfg_open} shall fail.
    556607
    557608@subheading NOTES:
     
    603654@subheading DESCRIPTION:
    604655
    605 The @code{cfg_read} function returns a pointer to a CFGENT sturcture
    606 representing a node in the configuration space to which @code{cfgp}
    607 refers.  The returned pointer shall be stored at the location
    608 indicated by the @code{node} argument.
    609 
    610 The child nodes of each node in the configuration tree is returned
    611 by @code{cfg_read}.
     656if {_POSIX_CFG} is defined:
     657
     658   The @code{cfg_read} function returns a pointer to a CFGENT sturcture
     659   representing a node in the configuration space to which @code{cfgp}
     660   refers.  The returned pointer shall be stored at the location
     661   indicated by the @code{node} argument.
     662
     663   The child nodes of each node in the configuration tree is returned
     664   by @code{cfg_read}.  If a comparison routine is specified to the
     665   @code{cfg_open} function, the order of return of the child nodes shall
     666   be as specified by the routine, from least to greatest.  Otherwise
     667   the order of return is unspecified.
     668
     669   Structures referencing nodes with children shall be returned by the
     670   function @code{cfg_read} at least twice [unless the application
     671   specifies otherwise with @code{cfg_mark}]-once immediately before
     672   the structures representing their descendants, are returned
     673   (pre-order), and once immediately after structures representing all
     674   of their descendants, if any, are returned (post-order).  The
     675   CFGENT structure returned in post-porder (with the exception of the
     676   @code{cfg_info} field) shall be identical to that returned in pre-order.
     677   Structures referencing nodes of other types shall be returned at least
     678   once.
     679
     680   The fields of the CFGENT structure shall contain the following
     681   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 
     694Otherwise:
     695
     696   The @code{cfg_read} function shall fail.
    612697
    613698@subheading NOTES:
     
    658743@subheading DESCRIPTION:
    659744
     745If {_POSIX_CFG} is defined:
     746
     747   The first @code{cfg_children} call after a @code{cfg_read} shall
     748   return information about the first node without children under the
     749   node returned by @code}{cfg_read}.  Subsequent calls to
     750   @code{cfg_children} without the intervening @code{cfg_read} shall
     751   return information about the remaining nodes without children under
     752   that same node.
     753
     754   If @code{cfg_read} has not yet been called for the configuration
     755   traversal stream represented by @code{cfgp}, @code{cfg_children}
     756   shall return a pointer to the first entry in a list of the nodes
     757   represented by the @code{pathnames} argument to @code{cfg_open}.
     758
     759   In either case, the list shall be NULL-terminated, ordered by the
     760   user-specified comparison function, if any, and linked through the
     761   cfg_link field.
     762
     763Otherwise:
     764
     765   The @code{cfg_children} function shall fail.
     766
    660767@subheading NOTES:
    661768
     
    693800@subheading DESCRIPTION:
    694801
    695 The @code{cfg_mark} function modifies the subsequent behavior of
    696 the cfg functions with regard to the node referenced by the structure
    697 pointed to by the argument f or the configuration space referenced by
    698 the structure pointed to by the argument @code{cfgp}.
     802If {_POSIX_CF} is defined:
     803
     804   The @code{cfg_mark} function modifies the subsequent behavior of
     805   the cfg functions with regard to the node referenced by the structure
     806   pointed to by the argument @code{f} or the configuration space referenced
     807   by the structure pointed to by the argument @code{cfgp}.
     808
     809   Exactly one of the @code{f} argument and the @code{cfgp} argument shall
     810   be NULL.
     811
     812   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
     817
     818Otherwise:
     819   
     820   The @code{cfg_mark} function shall fail.
    699821
    700822@subheading NOTES:
     
    729851@subheading DESCRIPTION:
    730852
    731 The @code{cfg_close} function closes a configuration space transversal
    732 stream.
    733 
    734 @subheading NOTES:
    735 
     853if {_POSIX_CFG} is defined:
     854
     855   The @code{cfg_close} function closes a configuration space transversal
     856   stream represented by the CFG structure pointed at by the @code{cfgp}
     857   argument.  All system resources allocated for this configuration space
     858   travsversal stream should be deallocated.  Upon return, the value of
     859   @code{cfgp} need not point to an accessible object of type CFG.
     860
     861Otherwise:
     862
     863   The @code{cfg_close} function shall fail.
     864
     865@subheading NOTES:
     866
Note: See TracChangeset for help on using the changeset viewer.