source: rtems/doc/new_chapters/confspace.t @ c7cb6bbb

4.104.114.84.95
Last change on this file since c7cb6bbb was c7cb6bbb, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 9, 1998 at 6:09:23 PM

Added section on format of the configuration space file.

  • Property mode set to 100644
File size: 30.1 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Configuration Space Manager
10
11@section Introduction
12
13The configuration space manager provides a portable
14interface for manipulating configuration data.
15The capabilities in this manager were defined in the POSIX
161003.1h/D3 proposed standard titled @b{Services for Reliable,
17Available, and Serviceable Systems}.
18
19The directives provided by the configuration space manager are:
20
21@itemize @bullet
22@item @code{cfg_mount} - Mount a Configuration Space
23@item @code{cfg_unmount} - Unmount a Configuration Space
24@item @code{cfg_mknod} - Create a Configuration Node
25@item @code{cfg_get} - Get Configuration Node Value
26@item @code{cfg_set} - Set Configuration Node Value
27@item @code{cfg_link} - Create a Configuration Link
28@item @code{cfg_unlink} - Remove a Configuration Link
29@item @code{cfg_open} - Open a Configuration Space
30@item @code{cfg_read} - Read a Configuration Space
31@item @code{cfg_children} - Get Node Entries
32@item @code{cfg_mark} - Set Configuration Space Option
33@item @code{cfg_close} - Close a Configuration Space
34@end itemize
35
36@section Background
37
38@subsection Configuration Nodes
39
40@subsection Configuration Space
41
42@subsection Format of a Configuration Space File
43
44@section Operations
45
46@subsection Mount and Unmounting
47
48@subsection Creating a Configuration Node
49
50@subsection Removing a Configuration Node
51
52@subsection Manipulating a Configuration Node
53
54@subsection Traversing a Configuration Space
55
56@section Directives
57
58This section details the configuration space manager's directives.
59A subsection is dedicated to each of this manager's directives
60and describes the calling sequence, related constants, usage,
61and status codes.
62
63@page
64@subsection cfg_mount - Mount a Configuration Space
65
66@subheading CALLING SEQUENCE:
67
68@ifset is-C
69@example
70#include <cfg.h>
71
72int cfg_mount(
73  const char     *file,
74  const char     *cfgpath,
75  log_facility_t  notification,
76);
77@end example
78@end ifset
79
80@ifset is-Ada
81@end ifset
82
83@subheading STATUS CODES:
84
85@table @b
86@item EPERM
87The caller does not have the appropriate privilege.
88
89@item EACCES
90Search permission is denied for a component of the path prefix.
91
92@item EEXIST
93The file specified by the file argument does not exist
94
95@item ENAMETOOLONG
96A component of a pathname exceeded @code{NAME_MAX} characters,
97or an entire path name exceed @code{PATH_MAX} characters while
98@code{_POSIX_NO_TRUNC} is in effect.
99
100@item ENOENT
101A component of cfgpath does not exist.
102
103@item ENOTDIR
104A component of the file path prefix is not a directory.
105
106@item EBUSY
107The configuration space defined by file is already mounted.
108
109@item EINVAL
110The notification argument specifies an invalid log facility.
111
112@end table
113
114@subheading DESCRIPTION:
115
116The @code{cfg_mount} function maps a configuration space defined
117by the file identified by the the @code{file} argument.  The
118distinguished node of the mapped configuration space shall be
119mounted in the active space at the point identified by the
120@code{cfgpath} configuration pathname.
121
122The @code{notification} argument specifies how changes to the
123mapped configuration space shall be communicated to the application.
124If the @code{notification} argument is NULL, no notification shall
125be performed for the mapped configuration space.  If the Event
126Logging option is defined, the notification argument defines the
127facility to which changes in the mapped configuration space shall
128be logged.  Otherwise, the @code{notification} argument shall
129specify an implementation defined method of notifying the application
130of changes to the mapped configuration space.
131
132@subheading NOTES:
133
134The @code{_POSIX_CFG} feature flag is defined to indicate
135this service is available.
136
137@page
138@subsection cfg_unmount - Unmount a Configuration Space
139
140@subheading CALLING SEQUENCE:
141
142@ifset is-C
143@example
144#include <cfg.h>
145
146int cfg_unmount(
147  const char     *cfgpath
148);
149@end example
150@end ifset
151
152@ifset is-Ada
153@end ifset
154
155@subheading STATUS CODES:
156
157@table @b
158@item EPERM
159The caller does not have the appropriate privileges.
160
161@item EACCES
162Search permission is denied for a component of the path prefix.
163
164@item ENOENT
165A component of cfgpath does not exist.
166
167@item ENAMETOOLONG
168A component of a pathname exceeded @code{NAME_MAX} characters,
169or an entire path name exceed @code{PATH_MAX} characters while
170@code{_POSIX_NO_TRUNC} is in effect.
171
172@item EINVAL
173The requested node is not the distinguished node of a mounted
174configuration space.
175
176@item EBUSY
177One or more processes has an open configuration traversal
178stream for the configuration space whose distinguished node is
179referenced by the cfgpath argument.
180
181@item ELOOP
182A node appears more than once in the path specified by the
183cfg_path argument
184
185@item ELOOP
186More than @code{SYMLOOP_MAX} symbolic links were encountered during
187resolution of the cfgpath argument
188
189@end table
190
191@subheading DESCRIPTION:
192
193The @code{cfg_umount} function unmaps the configuration space whose
194distinguished node is mapped in the active space at the location defined
195by @code{cfgpath} configuration pathname.  All system resources
196allocated for this configuration space should be deallocated.
197
198@subheading NOTES:
199
200The @code{_POSIX_CFG} feature flag is defined to indicate
201this service is available.
202
203@page
204@subsection cfg_mknod - Create a Configuration Node
205
206@subheading CALLING SEQUENCE:
207
208@ifset is-C
209@example
210#include <cfg.h>
211
212int cfg_mknod(
213  const char   *cfgpath,
214  mode_t        mode,
215  cfg_type_t    type         
216);
217@end example
218@end ifset
219
220@ifset is-Ada
221@end ifset
222
223@subheading STATUS CODES:
224
225@table @b
226@item ENAMETOOLONG
227A component of a pathname exceeded @code{NAME_MAX} characters,
228or an entire path name exceed @code{PATH_MAX} characters while
229@code{_POSIX_NO_TRUNC} is in effect.
230
231@item ENOENT
232A component of the path prefix does not exist.
233
234@item EACCES
235Search permission is denied for a component of the path prefix.
236
237@item ELOOP
238Too many symbolic links were encountered in translating the
239pathname.
240
241@item EPERM
242The calling process does not have the appropriate privilege.
243
244@item EEXIST
245The named node exists.
246
247@item EINVAL
248The value of mode is invalid.
249
250@item EINVAL
251The value of type is invalid.
252
253@item ELOOP
254A node appears more than once in the path specified by the
255cfg_path argument
256
257@item ELOOP
258More than @code{SYMLOOP_MAX} symbolic links were encountered during
259resolution of the cfgpath argument.
260
261@item EROFS
262The named node resides on a read-only configuration space.
263
264@end table
265
266@subheading DESCRIPTION:
267
268The @code{cfg_mknod} function creates a new node in the configuration
269space which contains the pathname prefix of @code{cfgpath}.  T he node
270name shall be defined by the pathname suffix of @code{cfgpath}.  The
271node name shall be defined by the pathname suffix of @code{cfgpath}.
272The node permissions shall be specified by the value of @code{mode}.
273The node type shall be specified by the value of @code{type}.
274
275@subheading NOTES:
276
277The @code{_POSIX_CFG} feature flag is defined to indicate
278this service is available.
279
280@page
281@subsection cfg_get - Get Configuration Node Value
282
283@subheading CALLING SEQUENCE:
284
285@ifset is-C
286@example
287#include <cfg.h>
288
289int cfg_get(
290  const char  *cfgpath
291  cfg_value_t *value
292);
293@end example
294@end ifset
295
296@ifset is-Ada
297@end ifset
298
299@subheading STATUS CODES:
300
301@table @b
302@item ENAMETOOLONG
303A component of a pathname exceeded @code{NAME_MAX} characters,
304or an entire path name exceed @code{PATH_MAX} characters while
305@code{_POSIX_NO_TRUNC} is in effect.
306
307@item ENOENT
308A component of cfgpath does not exist.
309
310@item EACCES
311Search permission is denied for a component of the path prefix.
312
313@item EPERM
314The calling process does not have the appropriate privileges.
315
316@item ELOOP
317A node appears more than once in the path specified by the
318cfg_path argument
319
320@item ELOOP
321More than @code{SYMLOOP_MAX} symbolic links were encountered during
322resolution of the cfgpath argument.
323
324@end table
325
326@subheading DESCRIPTION:
327
328The @code{cfg_get} function stores the value attribute of the
329configuration node identified by @code{cfgpath}, into the buffer
330described by the @code{value} pointer.
331
332@subheading NOTES:
333
334The @code{_POSIX_CFG} feature flag is defined to indicate
335this service is available.
336
337@page
338@subsection cfg_set - Set Configuration Node Value
339
340@subheading CALLING SEQUENCE:
341
342@ifset is-C
343@example
344#include <cfg.h>
345
346int cfg_set(
347  const char  *cfgpath
348  cfg_value_t *value
349);
350@end example
351@end ifset
352
353@ifset is-Ada
354@end ifset
355
356@subheading STATUS CODES:
357
358@table @b
359@item ENAMETOOLONG
360A component of a pathname exceeded @code{NAME_MAX} characters,
361or an entire path name exceed @code{PATH_MAX} characters while
362@code{_POSIX_NO_TRUNC} is in effect.
363
364@item ENOENT
365A component of cfgpath does not exist
366
367@item EACCES
368Search permission is denied for a component of the path prefix.
369
370@item EPERM
371The calling process does not have the appropriate privilege.
372
373@item ELOOP
374A node appears more than once in the path specified by the
375cfg-path argument.
376
377@item ELOOP
378More than @code{SYMLOOP_MAX} symbolic links were encountered during
379resolution of the cfgpath argument.
380
381@end table
382
383@subheading DESCRIPTION:
384
385The @code{cfg_set} function stores the value specified by the
386@code{value} argument in the configuration node defined by the
387@code{cfgpath} argument.
388
389@subheading NOTES:
390
391The @code{_POSIX_CFG} feature flag is defined to indicate
392this service is available.
393
394@page
395@subsection cfg_link - Create a Configuration Link
396
397@subheading CALLING SEQUENCE:
398
399@ifset is-C
400@example
401#include <cfg.h>
402
403int cfg_link(
404  const char *src
405  const char *dest
406);
407@end example
408@end ifset
409
410@ifset is-Ada
411@end ifset
412
413@subheading STATUS CODES:
414
415@table @b
416@item ENAMETOOLONG
417A component of a pathname exceeded @code{NAME_MAX} characters,
418or an entire path name exceed @code{PATH_MAX} characters while
419@code{_POSIX_NO_TRUNC} is in effect.
420
421@item ENOENT
422A component of either path prefix does not exist.
423
424@item EACCES
425A component of either path prefix denies search permission.
426
427@item EACCES
428The requested link requires writing in a node with a mode that
429denies write permission.
430
431@item ENOENT
432The node named by src does not exist.
433
434@item EEXIST
435The node named by dest does exist.
436
437@item EPERM
438The calling process does not have the appropriate privilege to
439modify the node indicated by the src argument.
440
441@item EXDEV
442The link named by dest and the node named by src are from different
443configuration spaces.
444
445@item ENOSPC
446The node in which the entry for the new link is being placed
447cannot be extended because there is no space left on the
448configuration space containing the node.
449
450@item EIO
451An I/O error occurred while reading from or writing to the
452configuration space to make the link entry.
453
454@item EROFS
455The requested link requires writing in a node on a read-only
456configuration space.
457
458@item ELOOP
459A node appears more than once in the path specified by the
460cfg-path argument.
461
462@item ELOOP
463More than @code{SYMLOOP_MAX} symbolic links were encountered during
464resolution of the cfgpath argument.
465
466@end table
467
468@subheading DESCRIPTION:
469
470The @code{src} and @code{dest}arguments point to pathnames which
471name existing nodes.  The @code{cfg_link} function shall atomically
472create a link between specified nodes, and increment by one the link
473count of the node specified by the @code{src} argument.
474
475If the @code{cfg_link} function fails, no link shall be created, and
476the link count of the node shall remain unchanged by this function
477call.
478
479This implementation may require that the calling process has permission
480to access the specified nodes.
481
482@subheading NOTES:
483
484The @code{_POSIX_CFG} feature flag is defined to indicate
485this service is available.
486
487@page
488@subsection cfg_unlink - Remove a Configuration Link
489
490@subheading CALLING SEQUENCE:
491
492@ifset is-C
493@example
494#include <cfg.h>
495
496int cfg_unlink(
497  const char    *cfgpath
498);
499@end example
500@end ifset
501
502@ifset is-Ada
503@end ifset
504
505@subheading STATUS CODES:
506
507@table @b
508@item ENAMETOOLONG
509A component of a pathname exceeded @code{NAME_MAX} characters,
510or an entire path name exceed @code{PATH_MAX} characters.
511
512@item ENOENT
513The named  node does not exist.
514
515@item EACCES
516Search permission is denied on the node containing the link to
517be removed.
518
519@item EACCES
520Write permission is denied on the node containing the link to
521be removed.
522
523@item ENOENT
524A component of cfgpath does not exist.
525
526@item EPERM
527The calling process does not have the appropriate privilege to
528modify the node indicated by the path prefix of the cfgpath
529argument.
530
531@item EBUSY
532The node to be unlinked is the distinguished node of a mounted
533configuration space.
534
535@item EIO
536An I/O error occurred while deleting the link entry or deallocating
537the node.
538
539@item EROFS
540The named node resides in a read-only configuration space.
541
542@item ELOOP
543A node appears more than once in the path specified by the
544cfg-path argument.
545
546@item ELOOP
547More than @code{SYMLOOP_MAX} symbolic links were encountered during
548resolution of the cfgpath argument.
549
550@end table
551
552@subheading DESCRIPTION:
553
554The @code{cfg_unlink} function removes the link between the node
555specified by the @code{cfgpath} path prefix and the parent node
556specified by @code{cfgpath}, and shall decrement the link count
557of the @code{cfgpath} node.
558
559When the link count of the node becomes zero, the space occupied
560by the node shall be freed and the node shall no longer be accessible.
561
562@subheading NOTES:
563
564The @code{_POSIX_CFG} feature flag is defined to indicate
565this service is available.
566
567@page
568@subsection cfg_open - Open a Configuration Space
569
570@subheading CALLING SEQUENCE:
571
572@ifset is-C
573@example
574#include <cfg.h>
575
576int cfg_open(
577  const char     *pathnames[],
578  int             options,
579  int           (*compar)(const CFGENT **f1, const CFGENT **f2),
580  CFG           **cfgstream
581);
582@end example
583@end ifset
584
585@ifset is-Ada
586@end ifset
587
588@subheading STATUS CODES:
589
590@table @b
591@item EACCES
592Search permission is denied for any component of a pathname.
593
594@item ELOOP
595A loop exists in symbolic links encountered during resolution
596of a pathname.
597
598@item ENAMETOOLONG
599The length of a pathname exceeds @code{PATH_MAX}, or a pathname
600component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}
601
602@item ENOENT
603The pathname argument is an empty string or the named node
604does not exist.
605
606@item EINVAL
607Either both or neither of CFG_LOGICAL and CFG_PHYSICAL are
608specified by the options argument ???????????
609
610@item ENOMEM
611Not enough memory is available to create the necessary structures.
612
613@item ELOOP
614More than @code{SYMLOOP_MAX} symbolic links were encountered during
615resolution of the pathnames argument.
616
617@item ENAMETOOLONG
618As a result of encountering a symbolic link in resolution of the
619pathname specified by the pathnames argument, the length of
620the substituted pathname string exceeded @code{PATH_MAX}.
621
622@end table
623
624@subheading DESCRIPTION:
625
626The @code{cfg_open} function shall open a configuration traversal stream
627rooted in the configuration nodes name by the @code{pathnames} argument.
628It shall store a pointer to a CFG object that represents that stream at
629the location identified the @code{cfgstream} pointer.  The @code{pathnames}
630argument is an array of character pointers to NULL-terminated strings.
631The last member of this array shall be a NULL pointer.
632
633The value of @code{options} is the bitwise inclusive OR of values from the
634following lists.  Applications shall supply exactly one of the first two
635values below in @code{options}.
636
637@table @b
638
639@item CFG_LOGICAL
640When symbolic links referencing existing nodes are
641encountered during the traversal, the @code{cfg_info}
642field of the returned CFGENT structure shall describe
643the target node pointed to by the link instead of the
644link itself, unless the target node does not exist.
645If the target node has children, the pre-order return,
646followed by the return of structures referencing all of
647its descendants, followed by a post-order return, shall
648be done.
649                   
650@item CFG_PHYSICAL
651When symbolic links are encountered during the traversal,
652the @code{cfg_info} field shall describe the symbolic
653link.
654
655@end table
656                   
657
658Any combination of the remaining flags can be specified in the value of
659@code{options}
660
661@table @b
662
663@item CFG_COMFOLLOW
664When symbolic links referencing existing nodes are
665specified in the @code{pathnames} argument, the
666@code{cfg_info} field of the returned CFGENT structure
667shall describe the target node pointed to by the link
668instead of the link itself, unless the target node does
669not exist.  If the target node has children, the
670pre-order return, followed by the return of structures
671referencing all its descendants, followed by a post-order
672return, shall be done.
673
674@item CFG_XDEV
675The configuration space functions shall not return a
676CFGENT structure for any node in a different configuration
677space than the configuration space of the nodes identified
678by the CFGENT structures for the @code{pathnames} argument.
679
680@end table
681
682The @code{cfg_open} argument @code{compar} shall either be NULL or point
683to a function that shall be called with two pointers to pointers to CFGENT
684structures that shall return less than, equal to , or greater than zero if
685the node referenced by the first argument is considered to be respectively
686less than, equal to, or greater than the node referenced by the second.
687The CFGENT structure fields provided to the comparison routine shall be as
688described with the exception that the contents of the @code{cfg_path} and
689@code{cfg_pathlen} fields are unspecified.
690
691This comparison routine is used to determine the order in which nodes in
692directories encountered during the traversal are returned, and the order
693of traversal when more than one node is specified in the @code{pathnames}
694argument to @code{cfg_open}.  If a comparison routine is specified, the
695order of traversal shall be from the least to the greatest.  If the
696@code{compar} argument is NULL, the order of traversal shall be as listed
697in the @code{pathnames} argument.
698
699@subheading NOTES:
700
701The @code{_POSIX_CFG} feature flag is defined to indicate
702this service is available.
703
704@page
705@subsection cfg_read - Read a Configuration Space
706
707@subheading CALLING SEQUENCE:
708
709@ifset is-C
710@example
711#include <cfg.h>
712
713int cfg_read( 
714  CFG           *cfgp,
715  CFGENT       **node
716);
717@end example
718@end ifset
719
720@ifset is-Ada
721@end ifset
722
723@subheading STATUS CODES:
724
725@table @b
726@item EACCES
727Search permission is denied for any component of a pathname.
728
729@item EBADF
730The cfgp argument does not refer to an open configuration
731space.
732
733@item ELOOP
734A loop exists in symbolic links encountered during resolution
735of a pathname.
736
737@item ENOENT
738A named node does not exist.
739
740@item ENOMEM
741Not enough memory is available to create the necessary structures.
742
743@item ELOOP
744More than @code{SYMLOOP_MAX} symbolic links were encountered during
745resolution of the cfgpath argument.
746
747@item ENAMETOOLONG
748As a result of encountering a symbolic link in resolution of the
749pathname specified by the pathnames argument, the length of the
750substituted pathname string exceeded @code{PATH_MATH}.
751
752@end table
753
754@subheading DESCRIPTION:
755
756The @code{cfg_read} function returns a pointer to a CFGENT structure
757representing a node in the configuration space to which @code{cfgp}
758refers.  The returned pointer shall be stored at the location
759indicated by the @code{node} argument.
760
761The child nodes of each node in the configuration tree is returned
762by @code{cfg_read}.  If a comparison routine is specified to the
763@code{cfg_open} function, the order of return of the child nodes shall
764be as specified by the routine, from least to greatest.  Otherwise
765the order of return is unspecified.
766
767Structures referencing nodes with children shall be returned by the
768function @code{cfg_read} at least twice [unless the application
769specifies otherwise with @code{cfg_mark}]-once immediately before
770the structures representing their descendants, are returned
771(pre-order), and once immediately after structures representing all
772of their descendants, if any, are returned (post-order).  The
773CFGENT structure returned in post-order (with the exception of the
774@code{cfg_info} field) shall be identical to that returned in pre-order.
775Structures referencing nodes of other types shall be returned at least
776once.
777
778The fields of the CFGENT structure shall contain the following
779information:
780
781@table @b
782
783@item cfg_parent
784A pointer to the structure returned by the
785@code{cfg_read} function for the node that contains
786the entry for the current node.  A @code{cfg_parent}
787structure shall be provided for the node(s) specified
788by the @code{pathnames} argument to the @code{cfg_open}
789function, but the contents of other than its
790@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
791and @code{cfg_parent}, and @code{cfg_level} fields are
792unspecified.  Its @code{cfg_link} field is unspecified.
793
794@item cfg_link
795Upon return from the @code{cfg_children} function, the
796@code{cfg_link} field points to the next CFGENT structure
797in a NULL-terminated linked list of CFGENT structures. 
798Otherwise, the content of the @code{cfg_link} field is
799unspecified.
800
801@item cfg_cycle
802If the structure being returned by @code{cfg_read}
803represents a node that appears in the @code{cfg_parent}
804linked list tree, the @code{cfg_cycle} field shall point
805to the structure representing that entry from the
806@code{cfg_parent} linked list.  Otherwise the content of
807the @code{cfg_cycle} field is unspecified.
808
809@item cfg_number
810The @code{cfg_number} field is provided for use by the
811application program.  It shall be initialized to zero for
812each new node returned by the @code{cfg_read} function,
813but shall not be further modified the configuration space
814routines.
815
816@item cfg_pointer
817The @code{cfg_pointer} field is provided for use by the
818application program.  It shall be initialized to NULL for
819each new node returned by the @code{cfg_read} function,
820but shall not be further modified by the configuration
821space routines.
822
823@item cfg_path
824A pathname for the node including and relative to the
825argument supplied to the @code{cfg_open} routine for this
826configuration space.  This pathname may be longer than
827@code{PATH_MAX} bytes.  This pathname shall be NULL-terminated.
828
829@item cfg_name
830The nodename of the node.
831
832@item cfg_pathlen
833The length of the string pointed at by the @code{cfg_path}
834field when returned by @code{cfg_read}.
835
836@item cfg_namelen
837The length of the string pointed at by the @code{cfg_name}
838field.
839
840@item cfg_level
841The depth of the current entry in the configuration space.
842The @code{cfg_level} field of the @code{cfg_parent}
843structure for each of the node(s) specified in the
844@code{pathnames} argument to the @code{cfg_open} function
845shall be set to 0, and this number shall be incremented for
846for each node level descendant.
847
848@item cfg_info
849This field shall contain one of the values listed below.  If
850an object can have more than one info value, the first
851appropriate value listed below shall be returned.
852
853@table @b
854
855@item CFG_D
856The structure represents a node with children in
857pre-order.
858
859@item CFG_DC
860The structure represents a node that is a parent
861of the node most recently returned by @code{cfg_read}.
862The @code{cfg_cycle} field shall reference the
863structure previously returned by @code{cfg_read} that
864is the same as the returned structure.
865
866@item CFG_DEFAULT
867The structure represents a node that is not
868represented by one of the other node types
869
870@item CFG_DNR
871The structure represents a node, not of type symlink,
872that is unreadable.  The variable @code{cfg_errno}
873shall be set to the appropriate value.
874
875@item CFG_DP
876The structure represents a node with children in
877post-order.  This value shall occur only if CFG_D
878has previously been returned for this entry.
879
880@item CFG_ERR
881The structure represents a node for which an error has
882occurred.  The variable @code{cfg_errno} shall be set
883to the appropriate value.
884
885@item CFG_F
886The structure represents a node without children.
887
888@item CFG_SL
889The structure represents a node of type symbolic link.
890
891@item CFG_SLNONET
892The structure represents a node of type symbolic link
893with a target node for which node characteristic
894information cannot be obtained.
895
896@end table
897
898@end table
899
900Structures returned by @code{cfg_read} with a @code{cfg_info} field equal
901to CFG_D shall be accessible until a subsequent call, on the same
902configuration traversal stream, to @code{cfg_close}, or to @code{cfg_read}
903after they have been returned by the @code{cfg_read} function in
904post-order.  Structures returned by @code{cfg_read} with an
905@code{cfg_info} field not equal to CFG_D shall be accessible until a
906subsequent call, on the same configuration traversal stream, to
907@code{cfg_close} or @code{cfg_read}.
908
909The content of the @code{cfg_path} field is specified only for the
910structure most recently returned by @code{cfg_read}.
911
912The specified fields in structures in the list representing nodes for
913which structures have previously been returned by @code{cfg_children},
914shall be identical to those returned by @code{cfg_children}, except that
915the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
916unspecified.
917         
918@subheading NOTES:
919
920The @code{_POSIX_CFG} feature flag is defined to indicate
921this service is available.
922
923@page
924@subsection cfg_children - Get Node Entries
925
926@subheading CALLING SEQUENCE:
927
928@ifset is-C
929@example
930#include <cfg.h>
931
932int cfg_children(
933  CFG           *cfgp,
934  int            options,
935  CFGENT       **children
936);
937@end example
938@end ifset
939
940@ifset is-Ada
941@end ifset
942
943@subheading STATUS CODES:
944
945@table @b
946@item EACCES
947Search permission is denied for any component of a pathname
948
949@item EBADF
950The cfgp argument does not refer to an open configuration space.
951
952@item ELOOP
953A loop exists in symbolic links encountered during resolution of
954a pathname.
955
956@item ENAMETOOLONG
957The length of a pathname exceeds @code{PATH_MAX}, or a pathname
958component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
959in effect.
960
961@item EINVAL
962The specified value of the options argument is invalid.
963
964@item ENOENT
965The named node does not exist.
966
967@item ENOMEM
968Not enough memory is available to create the necessary structures.
969
970@end table
971
972@subheading DESCRIPTION:
973
974The first @code{cfg_children} call after a @code{cfg_read} shall
975return information about the first node without children under the
976node returned by @code{cfg_read}.  Subsequent calls to
977@code{cfg_children} without the intervening @code{cfg_read} shall
978return information about the remaining nodes without children under
979that same node.
980
981If @code{cfg_read} has not yet been called for the configuration
982traversal stream represented by @code{cfgp}, @code{cfg_children}
983shall return a pointer to the first entry in a list of the nodes
984represented by the @code{pathnames} argument to @code{cfg_open}.
985
986In either case, the list shall be NULL-terminated, ordered by the
987user-specified comparison function, if any, and linked through the
988cfg_link field.
989
990@subheading NOTES:
991
992The @code{_POSIX_CFG} feature flag is defined to indicate
993this service is available.
994
995@page
996@subsection cfg_mark - Set Configuration Space Options
997
998@subheading CALLING SEQUENCE:
999
1000@ifset is-C
1001@example
1002#include <cfg.h>
1003
1004int cfg_mark(
1005  CFG           *cfgp,
1006  CFGENT        *f,
1007  int            options
1008);
1009@end example
1010@end ifset
1011
1012@ifset is-Ada
1013@end ifset
1014
1015@subheading STATUS CODES:
1016
1017@table @b
1018@item EINVAL
1019The specified combination of the cfgp and f arguments is not
1020supported by the implementation.
1021
1022@item EINVAL
1023The specified value of the options argument is invalid.
1024
1025@end table
1026
1027@subheading DESCRIPTION:
1028
1029The @code{cfg_mark} function modifies the subsequent behavior of
1030the cfg functions with regard to the node referenced by the structure
1031pointed to by the argument @code{f} or the configuration space referenced
1032by the structure pointed to by the argument @code{cfgp}.
1033
1034Exactly one of the @code{f} argument and the @code{cfgp} argument shall
1035be NULL.
1036
1037The value of the @code{options} argument shall be exactly one of the
1038flags specified in the following list:
1039
1040@table @b
1041
1042@item CFG_AGAIN
1043If the @code{cfgp} argument is non-NULL, or the @code{f}
1044argument is NULL, or the structure referenced by @code{f}
1045is not the one most recently returned by @code{cfg_read},
1046@code{cfg_mark} shall return an error.  Otherwise, the next
1047call to the @code{cfg_read} function shall return the
1048structure referenced by @code{f} with the @code{cfg_info}
1049field reinitialized.  Subsequent behavior of the @code{cfg}
1050functions shall be based on the reinitialized value of
1051@code{cfg_info}.
1052
1053@item CFG_SKIP
1054If the @code{cfgp} argument is non-NULL, or the @code{f}
1055argument is NULL, or the structure referenced by @code{f}
1056is not one of those specified as accessible, or the structure
1057referenced by @code{f} is not for a node of type pre-order
1058node, @code{cfg_mark} shall return an error.  Otherwise, no
1059more structures for the node referenced by @code{f} or its
1060descendants shall be returned by the @code{cfg_read} function.
1061
1062@item CFG_FOLLOW
1063If the @code{cfgp} argument is non-NULL, or the @code{f}
1064argument is NULL, or the structure referenced by @code{f}
1065is not one of those specified as accessible, or the structure
1066referenced by @code{f} is not for a node of type symbolic link,
1067@code{cfg_mark} shall return an error.  Otherwise, the next
1068call to the @code{cfg_read} function shall return the structure
1069referenced by @code{f} with the @code{cfg_info} field reset
1070to reflect the target of the symbolic link instead of the
1071symbolic link itself.  If the target of the link is node with
1072children, the pre-order return, followed by the return of
1073structures referencing all of its descendants, followed by a
1074post-order return, shall be done.
1075
1076@end table
1077
1078If the target of the symbolic link does not exist, the fields
1079of the structure by @code{cfg_read} shall be unmodified, except
1080that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
1081
1082@subheading NOTES:
1083
1084The @code{_POSIX_CFG} feature flag is defined to indicate
1085this service is available.
1086
1087@page
1088@subsection cfg_close - Close a Configuration Space
1089
1090@subheading CALLING SEQUENCE:
1091
1092@ifset is-C
1093@example
1094#include <cfg.h>
1095
1096int cfg_close(
1097  CFG           *cfgp
1098);
1099@end example
1100@end ifset
1101
1102@ifset is-Ada
1103@end ifset
1104
1105@subheading STATUS CODES:
1106
1107@table @b
1108@item EBADF
1109The cfgp argument does not refer to an open configuration space
1110traversal stream.
1111
1112@end table
1113
1114@subheading DESCRIPTION:
1115
1116The @code{cfg_close} function closes a configuration space transversal
1117stream represented by the CFG structure pointed at by the @code{cfgp}
1118argument.  All system resources allocated for this configuration space
1119traversal stream should be deallocated.  Upon return, the value of
1120@code{cfgp} need not point to an accessible object of type CFG.
1121
1122@subheading NOTES:
1123
1124The @code{_POSIX_CFG} feature flag is defined to indicate
1125this service is available.
Note: See TracBrowser for help on using the repository browser.