source: rtems/doc/new_chapters/confspace.t @ 6c455f37

4.104.114.84.95
Last change on this file since 6c455f37 was 6c455f37, checked in by Wade A Smith <warm38@…>, on Sep 16, 1998 at 3:15:41 PM

Remove many of the shall verbs and replaced them with present tense verbs

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