source: rtems/doc/new_chapters/confspace.t @ 571a915

4.104.114.84.95
Last change on this file since 571a915 was 571a915, checked in by Joel Sherrill <joel.sherrill@…>, on 08/25/98 at 22:09:13

Added some background and operations subsections.

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