source: rtems/doc/new_chapters/confspace.t @ 08142b48

4.104.114.84.95
Last change on this file since 08142b48 was 08142b48, checked in by Wade A Smith <warm38@…>, on Sep 12, 1998 at 3:57:18 PM

Documented the following routines added to the Configuration Space
Management: readdir, open, umask, link, mkdir, unlink, chmod, and chown.,

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