source: rtems/doc/new_chapters/confspace.t @ 3e6eb1dd

4.104.114.84.95
Last change on this file since 3e6eb1dd was 3e6eb1dd, checked in by Wade A Smith <warm38@…>, on 08/26/98 at 14:13:48

Incorporated the "#include cfg.h" statement in document

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