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

4.104.114.84.95
Last change on this file since a99ea16 was a99ea16, checked in by Joel Sherrill <joel.sherrill@…>, on 08/25/98 at 21:02:58

Fixed spelling mistakes.

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