summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters/confspace.t
blob: 9fcbb5f63db161976852e36eb63644472ac17365 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved. 
@c
@c  $Id$
@c

@chapter Configuration Space Manager

@section Introduction

The configuration space manager provides a portable
interface for manipulating configuration data.
The capabilities in this manager were defined in the POSIX
1003.1h/D3 proposed standard titled @b{Services for Reliable,
Available, and Serviceable Systems}.

The directives provided by the configuration space manager are:

@itemize @bullet
@item @code{cfg_mount} - Mount a Configuration Space
@item @code{cfg_unmount} - Unmount a Configuration Space
@item @code{cfg_mknod} - Create a Configuration Node
@item @code{cfg_get} - Get Configuration Node Value
@item @code{cfg_set} - Set Configuration Node Value
@item @code{cfg_link} - Create a Configuration Link
@item @code{cfg_unlink} - Remove a Configuration Link
@item @code{cfg_open} - Open a Configuration Space
@item @code{cfg_read} - Read a Configuration Space
@item @code{cfg_children} - Get Node Entries
@item @code{cfg_mark} - Set Configuration Space Option
@item @code{cfg_close} - Close a Configuration Space
@end itemize

@section Background

@subsection Configuration Nodes

@subsection Configuration Space

@subsection Format of a Configuration Space File

@section Operations

@subsection Mount and Unmounting

@subsection Creating a Configuration Node

@subsection Removing a Configuration Node

@subsection Manipulating a Configuration Node

@subsection Traversing a Configuration Space

@section Directives

This section details the configuration space manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.

@page
@subsection cfg_mount - Mount a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_mount(
  const char     *file,
  const char     *cfgpath,
  log_facility_t  notification,
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EPERM
The caller does not have the appropriate privilege.

@item EACCES
Search permission is denied for a component of the path prefix.

@item EEXIST
The file specified by the file argument does not exist

@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of cfgpath does not exist.

@item ENOTDIR
A component of the file path prefix is not a directory.

@item EBUSY
The configuration space defined by file is already mounted.

@item EINVAL
The notification argument specifies an invalid log facility.

@end table

@subheading DESCRIPTION:

The @code{cfg_mount} function maps a configuration space defined
by the file identified by the the @code{file} argument.  The 
distinguished node of the mapped configuration space shall be
mounted in the active space at the point identified by the
@code{cfgpath} configuration pathname.

The @code{notification} argument specifies how changes to the
mapped configuration space shall be communicated to the application.
If the @code{notification} argument is NULL, no notification shall
be performed for the mapped configuration space.  If the Event
Logging option is defined, the notification argument defines the
facility to which changes in the mapped configuration space shall
be logged.  Otherwise, the @code{notification} argument shall
specify an implementation defined method of notifying the application
of changes to the mapped configuration space.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_unmount - Unmount a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_unmount(
  const char     *cfgpath
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EPERM
The caller does not have the appropriate privileges.

@item EACCES
Search permission is denied for a component of the path prefix.

@item ENOENT
A component of cfgpath does not exist.

@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item EINVAL
The requested node is not the distinguished node of a mounted
configuration space.

@item EBUSY
One or more processes has an open configuration traversal
stream for the configuration space whose distinguished node is
referenced by the cfgpath argument.

@item ELOOP
A node appears more than once in the path specified by the 
cfg_path argument

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument

@end table

@subheading DESCRIPTION:

The @code{cfg_umount} function unmaps the configuration space whose 
distinguished node is mapped in the active space at the location defined
by @code{cfgpath} configuration pathname.  All system resources 
allocated for this configuration space should be deallocated.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_mknod - Create a Configuration Node

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_mknod(
  const char   *cfgpath,
  mode_t        mode,
  cfg_type_t    type         
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of the path prefix does not exist.

@item EACCES
Search permission is denied for a component of the path prefix.

@item ELOOP
Too many symbolic links were encountered in translating the 
pathname.

@item EPERM
The calling process does not have the appropriate privilege.

@item EEXIST
The named node exists.

@item EINVAL
The value of mode is invalid.

@item EINVAL
The value of type is invalid.

@item ELOOP
A node appears more than once in the path specified by the 
cfg_path argument

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@item EROFS
The named node resides on a read-only configuration space.

@end table

@subheading DESCRIPTION:

The @code{cfg_mknod} function creates a new node in the configuration
space which contains the pathname prefix of @code{cfgpath}.  T he node
name shall be defined by the pathname suffix of @code{cfgpath}.  The
node name shall be defined by the pathname suffix of @code{cfgpath}. 
The node permissions shall be specified by the value of @code{mode}.
The node type shall be specified by the value of @code{type}.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_get - Get Configuration Node Value

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_get(
  const char  *cfgpath
  cfg_value_t *value
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of cfgpath does not exist.

@item EACCES
Search permission is denied for a component of the path prefix.

@item EPERM
The calling process does not have the appropriate privileges.

@item ELOOP
A node appears more than once in the path specified by the 
cfg_path argument

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

The @code{cfg_get} function stores the value attribute of the
configuration node identified by @code{cfgpath}, into the buffer
described by the @code{value} pointer.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_set - Set Configuration Node Value

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_set(
  const char  *cfgpath
  cfg_value_t *value
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of cfgpath does not exist

@item EACCES
Search permission is denied for a component of the path prefix.

@item EPERM
The calling process does not have the appropriate privilege.

@item ELOOP
A node appears more than once in the path specified by the
cfg-path argument.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

The @code{cfg_set} function stores the value specified by the
@code{value} argument in the configuration node defined by the 
@code{cfgpath} argument.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_link - Create a Configuration Link

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_link(
  const char *src
  const char *dest
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.

@item ENOENT
A component of either path prefix does not exist.

@item EACCES
A component of either path prefix denies search permission.

@item EACCES
The requested link requires writing in a node with a mode that
denies write permission.

@item ENOENT
The node named by src does not exist.

@item EEXIST
The node named by dest does exist.

@item EPERM
The calling process does not have the appropriate privilege to
modify the node indicated by the src argument.

@item EXDEV
The link named by dest and the node named by src are from different
configuration spaces.

@item ENOSPC
The node in which the entry for the new link is being placed
cannot be extended because there is no space left on the 
configuration space containing the node.

@item EIO
An I/O error occurred while reading from or writing to the 
configuration space to make the link entry.

@item EROFS
The requested link requires writing in a node on a read-only
configuration space.

@item ELOOP
A node appears more than once in the path specified by the
cfg-path argument.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

The @code{src} and @code{dest}arguments point to pathnames which 
name existing nodes.  The @code{cfg_link} function shall atomically 
create a link between specified nodes, and increment by one the link 
count of the node specified by the @code{src} argument. 

If the @code{cfg_link} function fails, no link shall be created, and
the link count of the node shall remain unchanged by this function
call.

This implementation may require that the calling process has permission 
to access the specified nodes.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_unlink - Remove a Configuration Link

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_unlink(
  const char    *cfgpath
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters.

@item ENOENT
The named  node does not exist.

@item EACCES
Search permission is denied on the node containing the link to
be removed.

@item EACCES
Write permission is denied on the node containing the link to 
be removed.

@item ENOENT
A component of cfgpath does not exist.

@item EPERM
The calling process does not have the appropriate privilege to 
modify the node indicated by the path prefix of the cfgpath
argument.

@item EBUSY
The node to be unlinked is the distinguished node of a mounted
configuration space.

@item EIO
An I/O error occurred while deleting the link entry or deallocating
the node.

@item EROFS
The named node resides in a read-only configuration space.

@item ELOOP
A node appears more than once in the path specified by the
cfg-path argument.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@end table

@subheading DESCRIPTION:

The @code{cfg_unlink} function removes the link between the node
specified by the @code{cfgpath} path prefix and the parent node 
specified by @code{cfgpath}, and shall decrement the link count 
of the @code{cfgpath} node.

When the link count of the node becomes zero, the space occupied
by the node shall be freed and the node shall no longer be accessible.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_open - Open a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_open(
  const char     *pathnames[],
  int             options,
  int           (*compar)(const CFGENT **f1, const CFGENT **f2),
  CFG           **cfgstream
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EACCES
Search permission is denied for any component of a pathname.

@item ELOOP
A loop exists in symbolic links encountered during resolution 
of a pathname.

@item ENAMETOOLONG
The length of a pathname exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}

@item ENOENT
The pathname argument is an empty string or the named node
does not exist.

@item EINVAL
Either both or neither of CFG_LOGICAL and CFG_PHYSICAL are
specified by the options argument ???????????

@item ENOMEM
Not enough memory is available to create the necessary structures.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the pathnames argument.

@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the pathnames argument, the length of
the substituted pathname string exceeded @code{PATH_MAX}.

@end table

@subheading DESCRIPTION:

The @code{cfg_open} function shall open a configuration traversal stream
rooted in the configuration nodes name by the @code{pathnames} argument.
It shall store a pointer to a CFG object that represents that stream at 
the location identified the @code{cfgstream} pointer.  The @code{pathnames}
argument is an array of character pointers to NULL-terminated strings. 
The last member of this array shall be a NULL pointer.

The value of @code{options} is the bitwise inclusive OR of values from the 
following lists.  Applications shall supply exactly one of the first two 
values below in @code{options}.

@table @b

@item CFG_LOGICAL
When symbolic links referencing existing nodes are 
encountered during the traversal, the @code{cfg_info}
field of the returned CFGENT structure shall describe
the target node pointed to by the link instead of the 
link itself, unless the target node does not exist. 
If the target node has children, the pre-order return,
followed by the return of structures referencing all of
its descendants, followed by a post-order return, shall
be done.
                    
@item CFG_PHYSICAL
When symbolic links are encountered during the traversal,
the @code{cfg_info} field shall describe the symbolic 
link.

@end table
                    

Any combination of the remaining flags can be specified in the value of 
@code{options}

@table @b

@item CFG_COMFOLLOW
When symbolic links referencing existing nodes are
specified in the @code{pathnames} argument, the 
@code{cfg_info} field of the returned CFGENT structure
shall describe the target node pointed to by the link
instead of the link itself, unless the target node does
not exist.  If the target node has children, the 
pre-order return, followed by the return of structures
referencing all its descendants, followed by a post-order
return, shall be done.

@item CFG_XDEV
The configuration space functions shall not return a
CFGENT structure for any node in a different configuration
space than the configuration space of the nodes identified 
by the CFGENT structures for the @code{pathnames} argument.

@end table

The @code{cfg_open} argument @code{compar} shall either be NULL or point
to a function that shall be called with two pointers to pointers to CFGENT 
structures that shall return less than, equal to , or greater than zero if 
the node referenced by the first argument is considered to be respectively
less than, equal to, or greater than the node referenced by the second.
The CFGENT structure fields provided to the comparison routine shall be as 
described with the exception that the contents of the @code{cfg_path} and
@code{cfg_pathlen} fields are unspecified.

This comparison routine is used to determine the order in which nodes in
directories encountered during the traversal are returned, and the order
of traversal when more than one node is specified in the @code{pathnames}
argument to @code{cfg_open}.  If a comparison routine is specified, the
order of traversal shall be from the least to the greatest.  If the 
@code{compar} argument is NULL, the order of traversal shall be as listed
in the @code{pathnames} argument. 

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_read - Read a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_read(  
  CFG           *cfgp,
  CFGENT       **node
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EACCES
Search permission is denied for any component of a pathname.

@item EBADF
The cfgp argument does not refer to an open configuration
space.

@item ELOOP
A loop exists in symbolic links encountered during resolution
of a pathname.

@item ENOENT
A named node does not exist.

@item ENOMEM
Not enough memory is available to create the necessary structures.

@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.

@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the pathnames argument, the length of the
substituted pathname string exceeded @code{PATH_MATH}.

@end table

@subheading DESCRIPTION:

The @code{cfg_read} function returns a pointer to a CFGENT structure
representing a node in the configuration space to which @code{cfgp}
refers.  The returned pointer shall be stored at the location 
indicated by the @code{node} argument.

The child nodes of each node in the configuration tree is returned
by @code{cfg_read}.  If a comparison routine is specified to the
@code{cfg_open} function, the order of return of the child nodes shall
be as specified by the routine, from least to greatest.  Otherwise
the order of return is unspecified.

Structures referencing nodes with children shall be returned by the 
function @code{cfg_read} at least twice [unless the application
specifies otherwise with @code{cfg_mark}]-once immediately before
the structures representing their descendants, are returned 
(pre-order), and once immediately after structures representing all
of their descendants, if any, are returned (post-order).  The 
CFGENT structure returned in post-order (with the exception of the 
@code{cfg_info} field) shall be identical to that returned in pre-order.
Structures referencing nodes of other types shall be returned at least
once.

The fields of the CFGENT structure shall contain the following 
information:

@table @b

@item cfg_parent
A pointer to the structure returned by the 
@code{cfg_read} function for the node that contains
the entry for the current node.  A @code{cfg_parent}
structure shall be provided for the node(s) specified
by the @code{pathnames} argument to the @code{cfg_open}
function, but the contents of other than its 
@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
and @code{cfg_parent}, and @code{cfg_level} fields are
unspecified.  Its @code{cfg_link} field is unspecified.

@item cfg_link
Upon return from the @code{cfg_children} function, the
@code{cfg_link} field points to the next CFGENT structure 
in a NULL-terminated linked list of CFGENT structures.  
Otherwise, the content of the @code{cfg_link} field is 
unspecified.

@item cfg_cycle
If the structure being returned by @code{cfg_read} 
represents a node that appears in the @code{cfg_parent}
linked list tree, the @code{cfg_cycle} field shall point 
to the structure representing that entry from the 
@code{cfg_parent} linked list.  Otherwise the content of
the @code{cfg_cycle} field is unspecified.

@item cfg_number
The @code{cfg_number} field is provided for use by the 
application program.  It shall be initialized to zero for 
each new node returned by the @code{cfg_read} function, 
but shall not be further modified the configuration space
routines.

@item cfg_pointer
The @code{cfg_pointer} field is provided for use by the
application program.  It shall be initialized to NULL for
each new node returned by the @code{cfg_read} function, 
but shall not be further modified by the configuration 
space routines.

@item cfg_path
A pathname for the node including and relative to the 
argument supplied to the @code{cfg_open} routine for this
configuration space.  This pathname may be longer than
@code{PATH_MAX} bytes.  This pathname shall be NULL-terminated.

@item cfg_name
The nodename of the node.

@item cfg_pathlen
The length of the string pointed at by the @code{cfg_path}
field when returned by @code{cfg_read}.

@item cfg_namelen
The length of the string pointed at by the @code{cfg_name}
field.

@item cfg_level
The depth of the current entry in the configuration space.
The @code{cfg_level} field of the @code{cfg_parent} 
structure for each of the node(s) specified in the 
@code{pathnames} argument to the @code{cfg_open} function
shall be set to 0, and this number shall be incremented for
for each node level descendant.

@item cfg_info
This field shall contain one of the values listed below.  If
an object can have more than one info value, the first 
appropriate value listed below shall be returned. 

@table @b

@item CFG_D
The structure represents a node with children in
pre-order.

@item CFG_DC
The structure represents a node that is a parent
of the node most recently returned by @code{cfg_read}.
The @code{cfg_cycle} field shall reference the 
structure previously returned by @code{cfg_read} that
is the same as the returned structure.

@item CFG_DEFAULT
The structure represents a node that is not 
represented by one of the other node types

@item CFG_DNR
The structure represents a node, not of type symlink,
that is unreadable.  The variable @code{cfg_errno}
shall be set to the appropriate value.

@item CFG_DP
The structure represents a node with children in
post-order.  This value shall occur only if CFG_D 
has previously been returned for this entry.

@item CFG_ERR
The structure represents a node for which an error has 
occurred.  The variable @code{cfg_errno} shall be set
to the appropriate value.

@item CFG_F
The structure represents a node without children.

@item CFG_SL
The structure represents a node of type symbolic link.

@item CFG_SLNONET
The structure represents a node of type symbolic link
with a target node for which node characteristic
information cannot be obtained.

@end table

@end table

Structures returned by @code{cfg_read} with a @code{cfg_info} field equal
to CFG_D shall be accessible until a subsequent call, on the same
configuration traversal stream, to @code{cfg_close}, or to @code{cfg_read}
after they have been returned by the @code{cfg_read} function in
post-order.  Structures returned by @code{cfg_read} with an
@code{cfg_info} field not equal to CFG_D shall be accessible until a
subsequent call, on the same configuration traversal stream, to
@code{cfg_close} or @code{cfg_read}. 

The content of the @code{cfg_path} field is specified only for the
structure most recently returned by @code{cfg_read}. 

The specified fields in structures in the list representing nodes for
which structures have previously been returned by @code{cfg_children},
shall be identical to those returned by @code{cfg_children}, except that
the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
unspecified. 
         
@subheading NOTES: 

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_children - Get Node Entries

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_children(
  CFG           *cfgp,
  int            options,
  CFGENT       **children
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EACCES
Search permission is denied for any component of a pathname

@item EBADF
The cfgp argument does not refer to an open configuration space.

@item ELOOP
A loop exists in symbolic links encountered during resolution of 
a pathname.

@item ENAMETOOLONG
The length of a pathname exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
in effect.

@item EINVAL
The specified value of the options argument is invalid.

@item ENOENT
The named node does not exist.

@item ENOMEM
Not enough memory is available to create the necessary structures.

@end table

@subheading DESCRIPTION:

The first @code{cfg_children} call after a @code{cfg_read} shall 
return information about the first node without children under the
node returned by @code{cfg_read}.  Subsequent calls to 
@code{cfg_children} without the intervening @code{cfg_read} shall
return information about the remaining nodes without children under
that same node.

If @code{cfg_read} has not yet been called for the configuration
traversal stream represented by @code{cfgp}, @code{cfg_children}
shall return a pointer to the first entry in a list of the nodes 
represented by the @code{pathnames} argument to @code{cfg_open}.

In either case, the list shall be NULL-terminated, ordered by the 
user-specified comparison function, if any, and linked through the
cfg_link field.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_mark - Set Configuration Space Options

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_mark(
  CFG           *cfgp,
  CFGENT        *f,
  int            options
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The specified combination of the cfgp and f arguments is not 
supported by the implementation.

@item EINVAL
The specified value of the options argument is invalid.

@end table

@subheading DESCRIPTION:

The @code{cfg_mark} function modifies the subsequent behavior of
the cfg functions with regard to the node referenced by the structure
pointed to by the argument @code{f} or the configuration space referenced 
by the structure pointed to by the argument @code{cfgp}.

Exactly one of the @code{f} argument and the @code{cfgp} argument shall
be NULL.

The value of the @code{options} argument shall be exactly one of the
flags specified in the following list: 

@table @b

@item CFG_AGAIN
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not the one most recently returned by @code{cfg_read},
@code{cfg_mark} shall return an error.  Otherwise, the next 
call to the @code{cfg_read} function shall return the 
structure referenced by @code{f} with the @code{cfg_info}
field reinitialized.  Subsequent behavior of the @code{cfg}
functions shall be based on the reinitialized value of 
@code{cfg_info}.

@item CFG_SKIP
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not one of those specified as accessible, or the structure
referenced by @code{f} is not for a node of type pre-order 
node, @code{cfg_mark} shall return an error.  Otherwise, no 
more structures for the node referenced by @code{f} or its 
descendants shall be returned by the @code{cfg_read} function.

@item CFG_FOLLOW
If the @code{cfgp} argument is non-NULL, or the @code{f} 
argument is NULL, or the structure referenced by @code{f}
is not one of those specified as accessible, or the structure
referenced by @code{f} is not for a node of type symbolic link,
@code{cfg_mark} shall return an error.  Otherwise, the next
call to the @code{cfg_read} function shall return the structure
referenced by @code{f} with the @code{cfg_info} field reset
to reflect the target of the symbolic link instead of the 
symbolic link itself.  If the target of the link is node with
children, the pre-order return, followed by the return of 
structures referencing all of its descendants, followed by a 
post-order return, shall be done.

@end table

If the target of the symbolic link does not exist, the fields
of the structure by @code{cfg_read} shall be unmodified, except
that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.

@page
@subsection cfg_close - Close a Configuration Space

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <cfg.h>

int cfg_close(
  CFG           *cfgp
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
The cfgp argument does not refer to an open configuration space
traversal stream.

@end table

@subheading DESCRIPTION:

The @code{cfg_close} function closes a configuration space transversal
stream represented by the CFG structure pointed at by the @code{cfgp}
argument.  All system resources allocated for this configuration space
traversal stream should be deallocated.  Upon return, the value of 
@code{cfgp} need not point to an accessible object of type CFG.

@subheading NOTES:

The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.