source: rtems/doc/new_chapters/confspace.t @ 4be3f4d

4.104.114.84.95
Last change on this file since 4be3f4d was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on 01/17/02 at 21:47:47

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • Property mode set to 100644
File size: 36.3 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
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_readdir} - Reads a directory
34@item @code{cfg_umask} - Sets a file creation mask
35@item @code{cfg_chmod} - Changes file mode
36@item @code{cfg_chown} - Changes the owner and/or group of a file
37@end itemize
38
39@section Background
40
41@subsection Configuration Nodes
42
43@subsection Configuration Space
44
45@subsection Format of a Configuration Space File
46
47@section Operations
48
49@subsection Mount and Unmounting
50
51@subsection Creating a Configuration Node
52
53@subsection Removing a Configuration Node
54
55@subsection Manipulating a Configuration Node
56
57@subsection Traversing a Configuration Space
58
59@section Directives
60
61This section details the configuration space manager's directives.
62A subsection is dedicated to each of this manager's directives
63and describes the calling sequence, related constants, usage,
64and status codes.
65
66@page
67@subsection cfg_mount - Mount a Configuration Space
68
69@subheading CALLING SEQUENCE:
70
71@ifset is-C
72@example
73#include <cfg.h>
74
75int cfg_mount(
76  const char     *file,
77  const char     *cfgpath,
78  log_facility_t  notification,
79);
80@end example
81@end ifset
82
83@ifset is-Ada
84@end ifset
85
86@subheading STATUS CODES:
87
88A successful call to @code{cfg_mount()} returns a value of zero
89and an unsuccessful call returns the @code{errno}.
90
91@table @b
92@item EPERM
93The caller does not have the appropriate privilege.
94
95@item EACCES
96Search permission is denied for a component of the path prefix.
97
98@item EEXIST
99The file specified by the @code{file} argument does not exist
100
101@item ENAMETOOLONG
102A component of a pathname exceeded @code{NAME_MAX} characters,
103or an entire path name exceed @code{PATH_MAX} characters while
104@code{_POSIX_NO_TRUNC} is in effect.
105
106@item ENOENT
107A component of @code{cfgpath} does not exist.
108
109@item ENOTDIR
110A component of the @code{file} path prefix is not a directory.
111
112@item EBUSY
113The configuration space defined by @code{file} is already mounted.
114
115@item EINVAL
116The notification argument specifies an invalid log facility.
117
118@end table
119
120@subheading DESCRIPTION:
121
122The @code{cfg_mount()} function maps a configuration space defined
123by the file identified by the the @code{file} argument.  The
124distinguished node of the mapped configuration space is
125mounted in the active space at the point identified by the
126@code{cfgpath} configuration pathname.
127
128The @code{notification} argument specifies how changes to the
129mapped configuration space are communicated to the application.
130If the @code{notification} argument is NULL, no notification will be
131be performed for the mapped configuration space.  If the Event
132Logging option is defined, the notification argument defines the
133facility to which changes in the mapped configuration space are
134logged.  Otherwise, the @code{notification} argument specifies
135an implementation defined method of notifying the application
136of changes to the mapped configuration space.
137
138@subheading NOTES:
139
140The @code{_POSIX_CFG} feature flag is defined to indicate
141this service is available.
142
143@page
144@subsection cfg_unmount - Unmount a Configuration Space
145
146@subheading CALLING SEQUENCE:
147
148@ifset is-C
149@example
150#include <cfg.h>
151
152int cfg_unmount(
153  const char     *cfgpath
154);
155@end example
156@end ifset
157
158@ifset is-Ada
159@end ifset
160
161@subheading STATUS CODES:
162
163A successful call to @code{cfg_umount()} returns a value of zero
164and an unsuccessful call returns the @code{errno}.
165
166@table @b
167@item EPERM
168The caller does not have the appropriate privileges.
169
170@item EACCES
171Search permission is denied for a component of the path prefix.
172
173@item ENOENT
174A component of @code{cfgpath} does not exist.
175
176@item ENAMETOOLONG
177A component of a pathname exceeded @code{NAME_MAX} characters,
178or an entire path name exceed @code{PATH_MAX} characters while
179@code{_POSIX_NO_TRUNC} is in effect.
180
181@item EINVAL
182The requested node is not the distinguished node of a mounted
183configuration space.
184
185@item EBUSY
186One or more processes has an open configuration traversal
187stream for the configuration space whose distinguished node is
188referenced by the cfgpath argument.
189
190@item ELOOP
191A node appears more than once in the path specified by the
192@code{cfgpath} argument
193
194@item ELOOP
195More than @code{SYMLOOP_MAX} symbolic links were encountered during
196resolution of the cfgpath argument
197
198@end table
199
200@subheading DESCRIPTION:
201
202The @code{cfg_umount()} function unmaps the configuration space whose
203distinguished node is mapped in the active space at the location defined
204by @code{cfgpath} configuration pathname.  All system resources
205allocated for this configuration space should be deallocated.
206
207@subheading NOTES:
208
209The @code{_POSIX_CFG} feature flag is defined to indicate
210this service is available.
211
212@page
213@subsection cfg_mknod - Create a Configuration Node
214
215@subheading CALLING SEQUENCE:
216
217@ifset is-C
218@example
219#include <cfg.h>
220
221int cfg_mknod(
222  const char   *cfgpath,
223  mode_t        mode,
224  cfg_type_t    type         
225);
226@end example
227@end ifset
228
229@ifset is-Ada
230@end ifset
231
232@subheading STATUS CODES:
233
234A successful call to @code{cfg_mknod()} returns a value of zero
235and an unsuccessful call returns the @code{errno}.
236
237@table @b
238@item ENAMETOOLONG
239A component of a pathname exceeded @code{NAME_MAX} characters,
240or an entire path name exceed @code{PATH_MAX} characters while
241@code{_POSIX_NO_TRUNC} is in effect.
242
243@item ENOENT
244A component of the path prefix does not exist.
245
246@item EACCES
247Search permission is denied for a component of the path prefix.
248
249
250@item EPERM
251The calling process does not have the appropriate privilege.
252
253@item EEXIST
254The named node exists.
255
256@item EINVAL
257The value of @code{mode} is invalid.
258
259@item EINVAL
260The value of @code{type} is invalid.
261
262@item ELOOP
263A node appears more than once in the path specified by the
264@code{cfg_path} argument
265
266@item ELOOP
267More than @code{SYMLOOP_MAX} symbolic links were encountered during
268resolution of the @code{cfgpath} argument.
269
270@item EROFS
271The named @code{node} resides on a read-only configuration space.
272
273@end table
274
275@subheading DESCRIPTION:
276
277The @code{cfg_mknod()} function creates a new node in the configuration
278space which contains the pathname prefix of @code{cfgpath}.  The node
279name is defined by the pathname suffix of @code{cfgpath}. The node
280permissions are specified by the value of @code{mode}.  The node type
281is specified by the value of @code{type}.
282
283@subheading NOTES:
284
285The @code{_POSIX_CFG} feature flag is defined to indicate
286this service is available.
287
288@page
289@subsection cfg_get - Get Configuration Node Value
290
291@subheading CALLING SEQUENCE:
292
293@ifset is-C
294@example
295#include <cfg.h>
296
297int cfg_get(
298  const char  *cfgpath
299  cfg_value_t *value
300);
301@end example
302@end ifset
303
304@ifset is-Ada
305@end ifset
306
307@subheading STATUS CODES:
308
309A successful call to @code{cfg_get()} returns a value of zero
310and an unsuccessful call returns the @code{errno}.
311
312@table @b
313@item ENAMETOOLONG
314A component of a pathname exceeded @code{NAME_MAX} characters,
315or an entire path name exceed @code{PATH_MAX} characters while
316@code{_POSIX_NO_TRUNC} is in effect.
317
318@item ENOENT
319A component of @code{cfgpath} does not exist.
320
321@item EACCES
322Search permission is denied for a component of the path prefix.
323
324@item EPERM
325The calling process does not have the appropriate privileges.
326
327@item ELOOP
328A node appears more than once in the path specified by the
329@code{cfgpath} argument
330
331@item ELOOP
332More than @code{SYMLOOP_MAX} symbolic links were encountered during
333resolution of the @code{cfgpath} argument.
334
335@end table
336
337@subheading DESCRIPTION:
338
339The @code{cfg_get()} function stores the value attribute of the
340configuration node identified by @code{cfgpath}, into the buffer
341described by the @code{value} pointer.
342
343@subheading NOTES:
344
345The @code{_POSIX_CFG} feature flag is defined to indicate
346this service is available.
347
348@page
349@subsection cfg_set - Set Configuration Node Value
350
351@subheading CALLING SEQUENCE:
352
353@ifset is-C
354@example
355#include <cfg.h>
356
357int cfg_set(
358  const char  *cfgpath
359  cfg_value_t *value
360);
361@end example
362@end ifset
363
364@ifset is-Ada
365@end ifset
366
367@subheading STATUS CODES:
368
369A successful call to @code{cfg_set()} returns a value of zero
370and an unsuccessful call returns the @code{errno}.
371
372@table @b
373@item ENAMETOOLONG
374A component of a pathname exceeded @code{NAME_MAX} characters,
375or an entire path name exceed @code{PATH_MAX} characters while
376@code{_POSIX_NO_TRUNC} is in effect.
377
378@item ENOENT
379A component of @code{cfgpath} does not exist
380
381@item EACCES
382Search permission is denied for a component of the path prefix.
383
384@item EPERM
385The calling process does not have the appropriate privilege.
386
387@item ELOOP
388A node appears more than once in the path specified by the
389@code{cfgpath} argument.
390
391@item ELOOP
392More than @code{SYMLOOP_MAX} symbolic links were encountered during
393resolution of the cfgpath argument.
394
395@end table
396
397@subheading DESCRIPTION:
398
399The @code{cfg_set()} function stores the value specified by the
400@code{value} argument in the configuration node defined by the
401@code{cfgpath} argument.
402
403@subheading NOTES:
404
405The @code{_POSIX_CFG} feature flag is defined to indicate
406this service is available.
407
408@page
409@subsection cfg_link - Create a Configuration Link
410
411@subheading CALLING SEQUENCE:
412
413@ifset is-C
414@example
415#include <cfg.h>
416
417int cfg_link(
418  const char *src
419  const char *dest
420);
421@end example
422@end ifset
423
424@ifset is-Ada
425@end ifset
426
427@subheading STATUS CODES:
428
429A successful call to @code{cfg_link()} returns a value of zero
430and an unsuccessful call returns the @code{errno}.
431
432@table @b
433@item ENAMETOOLONG
434A component of a pathname exceeded @code{NAME_MAX} characters,
435or an entire path name exceed @code{PATH_MAX} characters while
436@code{_POSIX_NO_TRUNC} is in effect.
437
438@item ENOENT
439A component of either path prefix does not exist.
440
441@item EACCES
442A component of either path prefix denies search permission.
443
444@item EACCES
445The requested link requires writing in a node with a mode that
446denies write permission.
447
448@item ENOENT
449The node named by @code{src} does not exist.
450
451@item EEXIST
452The node named by @code{dest} does exist.
453
454@item EPERM
455The calling process does not have the appropriate privilege to
456modify the node indicated by the @code{src} argument.
457
458@item EXDEV
459The link named by @code{dest} and the node named by @code{src} are from different
460configuration spaces.
461
462@item ENOSPC
463The node in which the entry for the new link is being placed
464cannot be extended because there is no space left on the
465configuration space containing the node.
466
467@item EIO
468An I/O error occurred while reading from or writing to the
469configuration space to make the link entry.
470
471@item EROFS
472The requested link requires writing in a node on a read-only
473configuration space.
474
475@end table
476
477@subheading DESCRIPTION:
478
479The @code{src} and @code{dest} arguments point to pathnames which
480name existing nodes.  The @code{cfg_link()} function atomically creates
481a link between specified nodes, and increment by one the link count
482of the node specified by the @code{src} argument.
483
484If the @code{cfg_link()} function fails, no link is created, and the
485link count of the node remains unchanged by this function call.
486
487
488@subheading NOTES:
489
490The @code{_POSIX_CFG} feature flag is defined to indicate
491this service is available.
492
493@page
494@subsection cfg_unlink - Remove a Configuration Link
495
496@subheading CALLING SEQUENCE:
497
498@ifset is-C
499@example
500#include <cfg.h>
501
502int cfg_unlink(
503  const char    *cfgpath
504);
505@end example
506@end ifset
507
508@ifset is-Ada
509@end ifset
510
511@subheading STATUS CODES:
512
513A successful call to @code{cfg_unlink()} returns a value of zero
514and an unsuccessful call returns the @code{errno}.
515
516@table @b
517@item ENAMETOOLONG
518A component of a pathname exceeded @code{NAME_MAX} characters,
519or an entire path name exceed @code{PATH_MAX} characters.
520
521@item EACCES
522Search permission is denied on the node containing the link to
523be removed.
524
525@item EACCES
526Write permission is denied on the node containing the link to
527be removed.
528
529@item ENOENT
530A component of @code{cfgpath} does not exist.
531
532@item EPERM
533The calling process does not have the appropriate privilege to
534modify the node indicated by the path prefix of the @code{cfgpath}
535argument.
536
537@item EBUSY
538The node to be unlinked is the distinguished node of a mounted
539configuration space.
540
541@item EIO
542An I/O error occurred while deleting the link entry or deallocating
543the node.
544
545@item EROFS
546The named node resides in a read-only configuration space.
547
548@item ELOOP
549A node appears more than once in the path specified by the
550@code{cfgpath} argument.
551
552@item ELOOP
553More than @code{SYMLOOP_MAX} symbolic links were encountered during
554resolution of the cfgpath argument.
555
556@end table
557
558@subheading DESCRIPTION:
559
560The @code{cfg_unlink()} function removes the link between the node
561specified by the @code{cfgpath} path prefix and the parent node
562specified by @code{cfgpath}, and decrements the link count
563of the @code{cfgpath} node.
564
565When the link count of the node becomes zero, the space occupied
566by the node is freed and the node is no longer be accessible.
567
568@subheading NOTES:
569
570The @code{_POSIX_CFG} feature flag is defined to indicate
571this service is available.
572
573@page
574@subsection cfg_open - Open a Configuration Space
575
576@subheading CALLING SEQUENCE:
577
578@ifset is-C
579@example
580#include <cfg.h>
581
582int cfg_open(
583  const char     *pathnames[],
584  int             options,
585  int           (*compar)(const CFGENT **f1, const CFGENT **f2),
586  CFG           **cfgstream
587);
588@end example
589@end ifset
590
591@ifset is-Ada
592@end ifset
593
594@subheading STATUS CODES:
595
596A successful call to @code{cfg_open()} returns a value of zero
597and an unsuccessful call returns the @code{errno}.
598
599@table @b
600@item EACCES
601Search permission is denied for any component of a pathname.
602
603@item ELOOP
604A loop exists in symbolic links encountered during resolution
605of a pathname.
606
607@item ENAMETOOLONG
608The length of a pathname exceeds @code{PATH_MAX}, or a pathname
609component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}
610
611@item ENOENT
612The pathname argument is an empty string or the named node
613does not exist.
614
615@item EINVAL
616Either both or neither of @code{CFG_LOGICAL} and @code{CFG_PHYSICAL} are
617specified by the @code{options} argument
618
619@item ENOMEM
620Not enough memory is available to create the necessary structures.
621
622@item ELOOP
623More than @code{SYMLOOP_MAX} symbolic links were encountered during
624resolution of the @code{pathnames} argument.
625
626@item ENAMETOOLONG
627As a result of encountering a symbolic link in resolution of the
628pathname specified by the @code{pathnames} argument, the length of
629the substituted pathname string exceeded @code{PATH_MAX}.
630
631@end table
632
633@subheading DESCRIPTION:
634
635The @code{cfg_open()} function opens a configuration traversal stream
636rooted in the configuration nodes name by the @code{pathnames} argument.
637It stores a pointer to a CFG object that represents that stream at
638the location identified the @code{cfgstream} pointer.  The @code{pathnames}
639argument is an array of character pointers to NULL-terminated strings.
640The last member of this array is a NULL pointer.
641
642The value of @code{options} is the bitwise inclusive OR of values from the
643following lists.  Applications supply exactly one of the first two values
644below in @code{options}.
645
646@table @b
647
648@item CFG_LOGICAL
649When symbolic links referencing existing nodes are
650encountered during the traversal, the @code{cfg_info}
651field of the returned CFGENT structure describes the
652target node pointed to by the link instead of the
653link itself, unless the target node does not exist.
654If the target node has children, the pre-order return,
655followed by the return of structures referencing all of
656its descendants, followed by a post-order return, is done.
657                   
658@item CFG_PHYSICAL
659When symbolic links are encountered during the traversal,
660the @code{cfg_info} field is used to describe the symbolic
661link.
662
663@end table
664                   
665
666Any combination of the remaining flags can be specified in the value of
667@code{options}
668
669@table @b
670
671@item CFG_COMFOLLOW
672When symbolic links referencing existing nodes are
673specified in the @code{pathnames} argument, the
674@code{cfg_info} field of the returned CFGENT structure
675describes the target node pointed to by the link
676instead of the link itself, unless the target node does
677not exist.  If the target node has children, the
678pre-order return, followed by the return of structures
679referencing all its descendants, followed by a post-order
680return, is done.
681
682@item CFG_XDEV
683The configuration space functions do not return a
684CFGENT structure for any node in a different configuration
685space than the configuration space of the nodes identified
686by the CFGENT structures for the @code{pathnames} argument.
687
688@end table
689
690The @code{cfg_open()} argument @code{compar} is either a NULL or point
691to a function that is called with two pointers to pointers to CFGENT
692structures that returns less than, equal to , or greater than zero if
693the node referenced by the first argument is considered to be respectively
694less than, equal to, or greater than the node referenced by the second.
695The CFGENT structure fields provided to the comparison routine is as
696described with the exception that the contents of the @code{cfg_path} and
697@code{cfg_pathlen} fields are unspecified.
698
699This comparison routine is used to determine the order in which nodes in
700directories encountered during the traversal are returned, and the order
701of traversal when more than one node is specified in the @code{pathnames}
702argument to @code{cfg_open()}.  If a comparison routine is specified, the
703order of traversal is from the least to the greatest.  If the @code{compar}
704argument is NULL, the order of traversal shall is listed in the
705@code{pathnames} argument.
706
707@subheading NOTES:
708
709The @code{_POSIX_CFG} feature flag is defined to indicate
710this service is available.
711
712@page
713@subsection cfg_read - Read a Configuration Space
714
715@subheading CALLING SEQUENCE:
716
717@ifset is-C
718@example
719#include <cfg.h>
720
721int cfg_read( 
722  CFG           *cfgp,
723  CFGENT       **node
724);
725@end example
726@end ifset
727
728@ifset is-Ada
729@end ifset
730
731@subheading STATUS CODES:
732
733A successful call to @code{cfg_read()} returns a value of zero
734and an unsuccessful call returns the @code{errno}.
735
736@table @b
737@item EACCES
738Search permission is denied for any component of a pathname.
739
740@item EBADF
741The @code{cfgp} argument does not refer to an open configuration
742space.
743
744@item ELOOP
745A loop exists in symbolic links encountered during resolution
746of a pathname.
747
748@item ENOENT
749A named @code{node} does not exist.
750
751@item ENOMEM
752Not enough memory is available to create the necessary structures.
753
754@item ELOOP
755More than @code{SYMLOOP_MAX} symbolic links were encountered during
756resolution of the cfgpath argument.
757
758@item ENAMETOOLONG
759As a result of encountering a symbolic link in resolution of the
760pathname specified by the pathnames argument, the length of the
761substituted pathname string exceeded @code{PATH_MATH}.
762
763@end table
764
765@subheading DESCRIPTION:
766
767The @code{cfg_read()} function returns a pointer to a CFGENT structure
768representing a node in the configuration space to which @code{cfgp}
769refers.  The returned pointer is stored at the location indicated
770by the @code{node} argument.
771
772The child nodes of each node in the configuration tree is returned
773by @code{cfg_read()}.  If a comparison routine was specified to the
774@code{cfg_open()} function, the order of return of the child nodes is
775as specified by the @code{compar} routine, from least to greatest. 
776Otherwise, the order of return is unspecified.
777
778Structures referencing nodes with children is returned by the
779function @code{cfg_read()} at least twice [unless the application
780specifies otherwise with @code{cfg_mark()}]-once immediately before
781the structures representing their descendants, are returned
782(pre-order), and once immediately after structures representing all
783of their descendants, if any, are returned (post-order).  The
784CFGENT structure returned in post-order (with the exception of the
785@code{cfg_info} field) is identical to that returned in pre-order.
786Structures referencing nodes of other types is returned at least
787once.
788
789The fields of the CFGENT structure contains the following
790information:
791
792@table @b
793
794@item cfg_parent
795A pointer to the structure returned by the
796@code{cfg_read()} function for the node that contains
797the entry for the current node.  A @code{cfg_parent}
798structure is provided for the node(s) specified by
799the @code{pathnames} argument to the @code{cfg_open()}
800function, but the contents of other than its
801@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
802and @code{cfg_parent}, and @code{cfg_level} fields are
803unspecified.  Its @code{cfg_link} field is unspecified.
804
805@item cfg_link
806Upon return from the @code{cfg_children()} function, the
807@code{cfg_link} field points to the next CFGENT structure
808in a NULL-terminated linked list of CFGENT structures. 
809Otherwise, the content of the @code{cfg_link} field is
810unspecified.
811
812@item cfg_cycle
813If the structure being returned by @code{cfg_read()}
814represents a node that appears in the @code{cfg_parent}
815linked list tree, the @code{cfg_cycle} field shall point
816to the structure representing that entry from the
817@code{cfg_parent} linked list.  Otherwise the content of
818the @code{cfg_cycle} field is unspecified.
819
820@item cfg_number
821The @code{cfg_number} field is provided for use by the
822application program.  It is initialized to zero for
823each new node returned by the @code{cfg_read()} function,
824but is not further modified by the configuration space
825routines.
826
827@item cfg_pointer
828The @code{cfg_pointer} field is provided for use by the
829application program.  It is initialized to NULL for
830each new node returned by the @code{cfg_read()} function,
831but is not further modified by the configuration
832space routines.
833
834@item cfg_path
835A pathname for the node including and relative to the
836argument supplied to the @code{cfg_open()} routine for this
837configuration space.  This pathname may be longer than
838@code{PATH_MAX} bytes.  This pathname is NULL-terminated.
839
840@item cfg_name
841The nodename of the node.
842
843@item cfg_pathlen
844The length of the string pointed at by the @code{cfg_path}
845field when returned by @code{cfg_read()}.
846
847@item cfg_namelen
848The length of the string pointed at by the @code{cfg_name}
849field.
850
851@item cfg_level
852The depth of the current entry in the configuration space.
853The @code{cfg_level} field of the @code{cfg_parent}
854structure for each of the node(s) specified in the
855@code{pathnames} argument to the @code{cfg_open()} function
856is set to 0, and this number is incremented for each
857node level descendant.
858
859@item cfg_info
860This field contains one of the values listed below.  If
861an object can have more than one info value, the first
862appropriate value listed below is returned.
863
864@table @b
865
866@item CFG_D
867The structure represents a node with children in
868pre-order.
869
870@item CFG_DC
871The structure represents a node that is a parent
872of the node most recently returned by @code{cfg_read()}.
873The @code{cfg_cycle} field references the structure
874previously returned by @code{cfg_read} that is the
875same as the returned structure.
876
877@item CFG_DEFAULT
878The structure represents a node that is not
879represented by one of the other node types
880
881@item CFG_DNR
882The structure represents a node, not of type symlink,
883that is unreadable.  The variable @code{cfg_errno}
884is set to the appropriate value.
885
886@item CFG_DP
887The structure represents a node with children in
888post-order.  This value occurs only if CFG_D
889has previously been returned for this entry.
890
891@item CFG_ERR
892The structure represents a node for which an error has
893occurred.  The variable @code{cfg_errno} is set to the
894appropriate value.
895
896@item CFG_F
897The structure represents a node without children.
898
899@item CFG_SL
900The structure represents a node of type symbolic link.
901
902@item CFG_SLNONET
903The structure represents a node of type symbolic link
904with a target node for which node characteristic
905information cannot be obtained.
906
907@end table
908
909@end table
910
911Structures returned by @code{cfg_read()} with a @code{cfg_info} field equal
912to CFG_D is accessible until a subsequent call, on the same
913configuration traversal stream, to @code{cfg_close()}, or to @code{cfg_read()}
914after they have been returned by the @code{cfg_read} function in
915post-order.  Structures returned by @code{cfg_read()} with an
916@code{cfg_info} field not equal to CFG_D is accessible until a subsequent
917call, on the same configuration traversal stream, to @code{cfg_close()}
918or @code{cfg_read()}.
919
920The content of the @code{cfg_path} field is specified only for the
921structure most recently returned by @code{cfg_read()}.
922
923The specified fields in structures in the list representing nodes for
924which structures have previously been returned by @code{cfg_children()},
925is identical to those returned by @code{cfg_children()}, except that
926the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
927unspecified.
928         
929@subheading NOTES:
930
931The @code{_POSIX_CFG} feature flag is defined to indicate
932this service is available.
933
934@page
935@subsection cfg_children - Get Node Entries
936
937@subheading CALLING SEQUENCE:
938
939@ifset is-C
940@example
941#include <cfg.h>
942
943int cfg_children(
944  CFG           *cfgp,
945  int            options,
946  CFGENT       **children
947);
948@end example
949@end ifset
950
951@ifset is-Ada
952@end ifset
953
954@subheading STATUS CODES:
955
956A successful call to @code{cfg_children()} returns a value of zero
957and an unsuccessful call returns the @code{errno}.
958
959@table @b
960@item EACCES
961Search permission is denied for any component of a pathname
962
963@item EBADF
964The @code{cfgp} argument does not refer to an open configuration space.
965
966@item ELOOP
967A loop exists in symbolic links encountered during resolution of
968a pathname.
969
970@item ENAMETOOLONG
971The length of a pathname exceeds @code{PATH_MAX}, or a pathname
972component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
973in effect.
974
975@item EINVAL
976The specified value of the @code{options} argument is invalid.
977
978@item ENOENT
979The named node does not exist.
980
981@item ENOMEM
982Not enough memory is available to create the necessary structures.
983
984@end table
985
986@subheading DESCRIPTION:
987
988The first @code{cfg_children()} call after a @code{cfg_read()} returns
989information about the first node without children under the node
990returned by @code{cfg_read()}.  Subsequent calls to @code{cfg_children()}
991without the intervening @code{cfg_read()} shall return information
992about the remaining nodes without children under that same node.
993
994If @code{cfg_read()} has not yet been called for the configuration
995traversal stream represented by @code{cfgp}, @code{cfg_children()}
996returns a pointer to the first entry in a list of the nodes
997represented by the @code{pathnames} argument to @code{cfg_open()}.
998
999In either case, the list is NULL-terminated, ordered by the
1000user-specified comparison function, if any, and linked through the
1001@code{cfg_link} field.
1002
1003@subheading NOTES:
1004
1005The @code{_POSIX_CFG} feature flag is defined to indicate
1006this service is available.
1007
1008@page
1009@subsection cfg_mark - Set Configuration Space Options
1010
1011@subheading CALLING SEQUENCE:
1012
1013@ifset is-C
1014@example
1015#include <cfg.h>
1016
1017int cfg_mark(
1018  CFG           *cfgp,
1019  CFGENT        *f,
1020  int            options
1021);
1022@end example
1023@end ifset
1024
1025@ifset is-Ada
1026@end ifset
1027
1028@subheading STATUS CODES:
1029
1030A successful call to @code{cfg_mark()} returns a value of zero
1031and an unsuccessful call returns the @code{errno}.
1032
1033@table @b
1034@item EINVAL
1035The specified combination of the @code{cfgp} and @code{f} arguments is not
1036supported by the implementation.
1037
1038@item EINVAL
1039The specified value of the @code{options} argument is invalid.
1040
1041@end table
1042
1043@subheading DESCRIPTION:
1044
1045The @code{cfg_mark()} function modifies the subsequent behavior of
1046the @code{cfg} functions with regard to the node referenced by the structure
1047pointed to by the argument @code{f} or the configuration space referenced
1048by the structure pointed to by the argument @code{cfgp}.
1049
1050Exactly one of the @code{f} argument and the @code{cfgp} argument is NULL.
1051
1052The value of the @code{options} argument is exactly one of the flags
1053specified in the following list:
1054
1055@table @b
1056
1057@item CFG_AGAIN
1058If the @code{cfgp} argument is non-NULL, or the @code{f}
1059argument is NULL, or the structure referenced by @code{f}
1060is not the one most recently returned by @code{cfg_read()},
1061@code{cfg_mark()} returns an error.  Otherwise, the next
1062call to the @code{cfg_read()} function returns the structure
1063referenced by @code{f} with the @code{cfg_info} field
1064reinitialized.  Subsequent behavior of the @code{cfg}
1065functions are based on the reinitialized value of
1066@code{cfg_info}.
1067
1068@item CFG_SKIP
1069If the @code{cfgp} argument is non-NULL, or the @code{f}
1070argument is NULL, or the structure referenced by @code{f}
1071is not one of those specified as accessible, or the structure
1072referenced by @code{f} is not for a node of type pre-order
1073node, @code{cfg_mark()} returns an error.  Otherwise, no
1074more structures for the node referenced by @code{f} or its
1075descendants are returned by the @code{cfg_read()} function.
1076
1077@item CFG_FOLLOW
1078If the @code{cfgp} argument is non-NULL, or the @code{f}
1079argument is NULL, or the structure referenced by @code{f}
1080is not one of those specified as accessible, or the structure
1081referenced by @code{f} is not for a node of type symbolic link,
1082@code{cfg_mark()} returns an error.  Otherwise, the next
1083call to the @code{cfg_read()} function returns the structure
1084referenced by @code{f} with the @code{cfg_info} field reset
1085to reflect the target of the symbolic link instead of the
1086symbolic link itself.  If the target of the link is node with
1087children, the pre-order return, followed by the return of
1088structures referencing all of its descendants, followed by a
1089post-order return, shall be done.
1090
1091@end table
1092
1093If the target of the symbolic link does not exist, the fields
1094of the structure by @code{cfg_read()} shall be unmodified, except
1095that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
1096
1097@subheading NOTES:
1098
1099The @code{_POSIX_CFG} feature flag is defined to indicate
1100this service is available.
1101
1102@page
1103@subsection cfg_close - Close a Configuration Space
1104
1105@subheading CALLING SEQUENCE:
1106
1107@ifset is-C
1108@example
1109#include <cfg.h>
1110
1111int cfg_close(
1112  CFG           *cfgp
1113);
1114@end example
1115@end ifset
1116
1117@ifset is-Ada
1118@end ifset
1119
1120@subheading STATUS CODES:
1121
1122A successful call to @code{cfg_close()} returns a value of zero
1123and an unsuccessful call returns the @code{errno}.
1124
1125@table @b
1126@item EBADF
1127The @code{cfgp} argument does not refer to an open configuration space
1128traversal stream.
1129
1130@end table
1131
1132@subheading DESCRIPTION:
1133
1134The @code{cfg_close()} function closes a configuration space transversal
1135stream represented by the CFG structure pointed at by the @code{cfgp}
1136argument.  All system resources allocated for this configuration space
1137traversal stream should be deallocated.  Upon return, the value of
1138@code{cfgp} need not point to an accessible object of type CFG.
1139
1140@subheading NOTES:
1141
1142The @code{_POSIX_CFG} feature flag is defined to indicate
1143this service is available.
1144
1145@page
1146@subsection cfg_readdir - Reads a directory
1147
1148@subheading CALLING SEQUENCE:
1149
1150@ifset is-C
1151@example
1152#include <sys/types.h>
1153#include <dirent.h>
1154
1155struct dirent *cfg_readdir(
1156  DIR   *dirp
1157);
1158@end example
1159@end ifset
1160
1161@ifset is-Ada
1162@end ifset
1163
1164@subheading STATUS CODES:
1165
1166@table @b
1167@item EBADF
1168Invalid file descriptor
1169
1170@end table
1171
1172@subheading DESCRIPTION:
1173
1174The @code{cfg_readdir()} function returns a pointer to a structure @code{dirent}
1175representing the next directory entry from the directory stream pointed to
1176by @code{dirp}.  On end-of-file, NULL is returned.
1177
1178The @code{cfg_readdir()} function may (or may not) return entries for . or .. Your
1179program should tolerate reading dot and dot-dot but not require them.
1180
1181The data pointed to be @code{cfg_readdir()} may be overwritten by another call to
1182@code{readdir()} for the same directory stream.  It will not be overwritten by
1183a call for another directory.
1184
1185@subheading NOTES:
1186
1187If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or
1188@code{realloc()} or has been deallocated with @code{free()} or @code{realloc()},
1189the results are not portable and are probably disastrous.
1190
1191This function is not defined in the POSIX specification.  It is an extension
1192provided by this implementation.
1193
1194@page
1195@subsection cfg_umask - Sets a file creation mask.
1196
1197@subheading CALLING SEQUENCE:
1198
1199@ifset is-C
1200@example
1201#include <sys/types.h>
1202#include <sys/stat.h>
1203
1204mode_t cfg_umask(
1205  mode_t cmask
1206);
1207@end example
1208@end ifset
1209
1210@ifset is-Ada
1211@end ifset
1212
1213@subheading STATUS CODES:
1214
1215@subheading DESCRIPTION:
1216
1217The @code{cfg_umask()} function sets the process node creation mask to @code{cmask}.
1218The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()},
1219@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument.
1220Bit positions that are set in @code{cmask} are cleared in the mode of the
1221created file.
1222
1223The file creation mask is inherited across @code{fork()} and @code{exec()} calls.
1224This makes it possible to alter the default permission bits of created files.
1225
1226@subheading NOTES: None
1227
1228The @code{cmask} argument should have only permission bits set.  All other
1229bits should be zero.
1230
1231@page
1232@subsection cfg_chmod - Changes file mode.
1233
1234@subheading CALLING SEQUENCE:
1235
1236@ifset is-C
1237@example
1238#include <sys/types.h>
1239#include <sys/stat.h>
1240
1241int cfg_chmod(
1242  const char *path,
1243  mode_t      mode
1244);
1245@end example
1246@end ifset
1247
1248@ifset is-Ada
1249@end ifset
1250
1251@subheading STATUS CODES:
1252
1253A successful call to @code{cfg_chmod()} returns a value of zero
1254and an unsuccessful call returns the @code{errno}.
1255
1256@table @b
1257@item EACCES
1258Search permission is denied for a directory in a file's path prefix
1259@item ENAMETOOLONG
1260Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1261effect.
1262@item ENOENT
1263A file or directory does not exist.
1264@item ENOTDIR
1265A component of the specified pathname was not a directory when a directory
1266was expected.
1267@item EPERM
1268Operation is not permitted.  Process does not have the appropriate priviledges
1269or permissions to perform the requested operations.
1270@item EROFS
1271Read-only file system.
1272
1273@end table
1274
1275@subheading DESCRIPTION:
1276
1277Set the file permission bits, the set user ID bit, and the set group ID bit
1278for the file named by @code{path} to @code{mode}.  If the effective user ID
1279does not match the owner of the node and the calling process does not have
1280the appropriate privileges, @code{cfg_chmod()} returns -1 and sets @code{errno} to
1281@code{EPERM}.
1282
1283@subheading NOTES:
1284
1285@page
1286@subsection cfg_chown - Changes the owner and/or group of a file.
1287
1288@subheading CALLING SEQUENCE:
1289
1290@ifset is-C
1291@example
1292#include <sys/types.h>
1293#include <unistd.h>
1294
1295int cfg_chown(
1296  const char *path,
1297  uid_t       owner,
1298  gid_t       group
1299);
1300@end example
1301@end ifset
1302
1303@ifset is-Ada
1304@end ifset
1305
1306@subheading STATUS CODES:
1307
1308A successful call to @code{cfg_chown()} returns a value of zero
1309and an unsuccessful call returns the @code{errno}.
1310
1311@table @b
1312@item EACCES
1313Search permission is denied for a directory in a file's path prefix
1314@item EINVAL
1315Invalid argument
1316@item ENAMETOOLONG
1317Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1318effect.
1319@item ENOENT
1320A file or directory does not exist.
1321@item ENOTDIR
1322A component of the specified pathname was not a directory when a directory
1323was expected.
1324@item EPERM
1325Operation is not permitted.  Process does not have the appropriate priviledges
1326or permissions to perform the requested operations.
1327@item EROFS
1328Read-only file system.
1329
1330@end table
1331
1332@subheading DESCRIPTION:
1333
1334The user ID and group ID of the file named by @code{path} are set to
1335@code{owner} and @code{path}, respectively.
1336
1337For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
1338bits are cleared.
1339
1340Some systems consider it a security violation to allow the owner of a file to
1341be changed,  If users are billed for disk space usage, loaning a file to
1342another user could result in incorrect billing.  The @code{cfg_chown()} function
1343may be restricted to privileged users for some or all files.  The group ID can
1344still be changed to one of the supplementary group IDs.
1345
1346@subheading NOTES:
1347
1348This function may be restricted for some file.  The @code{pathconf} function
1349can be used to test the _PC_CHOWN_RESTRICTED flag.
1350
1351
Note: See TracBrowser for help on using the repository browser.