source: rtems/doc/new_chapters/confspace.t @ e6bfa70

4.104.114.84.9
Last change on this file since e6bfa70 was e6bfa70, checked in by Wade A Smith <warm38@…>, on Aug 10, 1998 at 2:44:39 PM

Added documentation for the following Configuration Space Operations:
cfg_mount, cfg_unmount, cfg_mknod, cfg_set, cfg_get, cfg_link, cfg_unlink,
cfg_open, cfg_read, cfg_children, cfg_mark, and cfg_close

  • Property mode set to 100644
File size: 15.7 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
14configuration space manager is ...
15
16The directives provided by the configuration space manager are:
17
18@itemize @bullet
19@item @code{cfg_mount} - Mount a Configuration Space
20@item @code{cfg_unmount} - Unmount a Configuration Space
21@item @code{cfg_mknod} - Create a Configuration Node
22@item @code{cfg_get} - Get Configuration Node Value
23@item @code{cfg_set} - Set Configuration Node Value
24@item @code{cfg_link} - Create a Configuration Link
25@item @code{cfg_unlink} - Remove a Configuration Link
26@item @code{cfg_open} - Open a Configuration Space
27@item @code{cfg_read} - Read a Configuration Space
28@item @code{cfg_children} - Get Node Entries
29@item @code{cfg_mark} - Set Configuration Space Option
30@item @code{cfg_close} - Close a Configuration Space
31@end itemize
32
33@section Background
34
35@section Operations
36
37@section Directives
38
39This section details the configuration space manager's directives.
40A subsection is dedicated to each of this manager's directives
41and describes the calling sequence, related constants, usage,
42and status codes.
43
44@page
45@subsection cfg_mount - Mount a Configuration Space
46
47@subheading CALLING SEQUENCE:
48
49@ifset is-C
50@example
51int cfg_mount(
52  const char     *file,
53  const char     *cfgpath,
54  log_facility_t  notification,
55);
56@end example
57@end ifset
58
59@ifset is-Ada
60@end ifset
61
62@subheading STATUS CODES:
63
64@table @b
65@item EPERM
66The caller does not have the appropriate privilege.
67@item EACCES
68Search permission is denied for a component of the path prefix.
69@item EEXIST
70The file specified by the file argument does not exist
71@item ENAMETOOLONG
72A component of a pathname exceeded {NAME_MAX} characters,
73or an entire path name exceed {PATH_MAX} characters while
74{_POSIX_NO_TRUNC} is in effect.
75@item ENOENT
76A component of cfgpath does not exist.
77@item ENOTDIR
78A component of the file path prefix is not a directory.
79@item EBUSY
80The configuration space defined by file is already mounted.
81@item EINVAL
82The notification argument specifies an invalid log facility.
83@item ENOSYS
84The cfg_mount() function is not supported by this implementation.
85
86@end table
87
88@subheading DESCRIPTION:
89The @code{cfg_mount} function maps a configuration space defined
90by the file identified by the the @code{file} argument.
91
92@subheading NOTES:
93
94@page
95@subsection cfg_unmount - Unmount a Configuration Space
96
97@subheading CALLING SEQUENCE:
98
99@ifset is-C
100@example
101int cfg_unmount(
102  const char     *cfgpath
103);
104@end example
105@end ifset
106
107@ifset is-Ada
108@end ifset
109
110@subheading STATUS CODES:
111
112@table @b
113@item EPERM
114The caller does not have the appropriate privileges.
115@item EACCES
116Search permission is denied for a component of the path prefix.
117@item ENOENT
118A component of cfgpath does not exist.
119@item ENAMETOOLONG
120A component of a pathname exceeded {NAME_MAX} characters,
121or an entire path name exceed {PATH_MAX} characters while
122{_POSIX_NO_TRUNC} is in effect.
123@item EINVAL
124The requested node is not the distinguished node of a mounted
125configuration space.
126@item EBUSY
127One or more processes has an open configuration traversal
128stream for the configuration space whose distinguished node is
129referenced by the cfgpath argument.
130@item ENOSYS
131The cfg_umount function is not supported by this implementation.
132@item ELOOP
133A node appears more than once in the path specified by the
134cfg_path argument
135@item ELOOP
136More than {SYMLOOP_MAX} symbolic links were encountered during
137resolution of the cfgpath argument
138
139@end table
140
141@subheading DESCRIPTION:
142
143The @code{cfg_umount} function unmaps the configuration space whose
144distinguished node is mapped in the active space at the location defined
145by @code{cfgpatah} configuration pathname.
146
147@subheading NOTES:
148
149@page
150@subsection cfg_mknod - Create a Configuratioin Node
151
152@subheading CALLING SEQUENCE:
153
154@ifset is-C
155@example
156int cfg_mknod(
157  const char   *cfgpath,
158  mode_t        mode,
159  cfg_type_t    type         
160);
161@end example
162@end ifset
163
164@ifset is-Ada
165@end ifset
166
167@subheading STATUS CODES:
168
169@table @b
170@item ENAMETOOLONG
171A component of a pathname exceeded {NAME_MAX} characters,
172or an entire path name exceed {PATH_MAX} characters while
173{_POSIX_NO_TRUNC} is in effect.
174@item ENOENT
175A compent of the path prefix does not exist.
176@item EACCES
177Search permission is denied for a component of the path prefix.
178@item ELOOP
179Too many symbolic links were encountered in translating the
180pathname.
181@item EPERM
182The calling process does not have the appropriate privilege.
183@item EEXIST
184The named node exists.
185@item EINVAL
186The value of mode is invalid.
187@item EINVAL
188The value of type is invalid.
189@item ENOSYS
190The function cfg_mknod() is not supported by this implementation.
191@item ELOOP
192A node appears more than once in the path specified by the
193cfg_path argument
194@item ELOOP
195More than {SYMLOOP_MAX} symbolic links were encountered during
196resolution of the cfgpath argument.
197@item EROFS
198The named node resides on a read-only configuration space.
199
200@end table
201
202@subheading DESCRIPTION:
203
204The @code{cfg_mknod} function creates a new node in the configuration
205space which contains the pathname prefix of @cod{cfgpath}.
206
207@subheading NOTES:
208
209@page
210@subsection cfg_get - Get Configuration Node Value
211
212@subheading CALLING SEQUENCE:
213
214@ifset is-C
215@example
216int cfg_get(
217  const char  *cfgpath
218  cfg_value_t *value
219);
220@end example
221@end ifset
222
223@ifset is-Ada
224@end ifset
225
226@subheading STATUS CODES:
227
228@table @b
229@item ENAMETOOLONG
230A component of a pathname exceeded {NAME_MAX} characters,
231or an entire path name exceed {PATH_MAX} characters while
232{_POSIX_NO_TRUNC} is in effect.
233@item ENOENT
234A component of cfgpath does not exist.
235@item EACCES
236Search permission is denied for a component of the path prefix.
237@item EPERM
238The calling process does not have the appropriate priviledges.
239@item ENOSYS
240The function cfg_get() is not supported by this implementation
241@item ELOOP
242A node appears more than once in the path specified by the
243cfg_path argument
244@item ELOOP
245More than {SYMLOOP_MAX} symbolic links were encountered during
246resolution of the cfgpath argument.
247
248@end table
249
250@subheading DESCRIPTION:
251
252The @code{cfg_get} function stores the value attribute of the
253configuration node identified by @code{cfgpath}, into the buffer
254described by the value pointer.
255
256@subheading NOTES:
257
258@page
259@subsection cfg_set - Set Configuration Node Value
260
261@subheading CALLING SEQUENCE:
262
263@ifset is-C
264@example
265int cfg_set(
266  const char  *cfgpath
267  cfg_value_t *value
268);
269@end example
270@end ifset
271
272@ifset is-Ada
273@end ifset
274
275@subheading STATUS CODES:
276
277@table @b
278@item ENAMETOOLONG
279A component of a pathname exceeded {NAME_MAX} characters,
280or an entire path name exceed {PATH_MAX} characters while
281{_POSIX_NO_TRUNC} is in effect.
282@item ENOENT
283A component of cfgpath does not exist
284@item EACCES
285Search permission is denied for a component of the path prefix.
286@item EPERM
287The calling process does not have the appropriate privilege.
288@item ENOSYS
289The function cfg_set() is not supported by this implementation.
290@item ELOOP
291A node appears more than once in the path specified by the
292cfg-path argument.
293@item ELOOP
294More than {SYMLOOP_MAX} symbolic links were encountered during
295resolution of the cfgpath argument.
296
297@end table
298
299@subheading DESCRIPTION:
300
301The @code{cfg_set} function stores the value specified by the
302@code{value} argument in the configuration node defined by the
303@code{cfgpath} argument
304
305@subheading NOTES:
306
307@page
308@subsection cfg_link - Create a Configuration Link
309
310@subheading CALLING SEQUENCE:
311
312@ifset is-C
313@example
314int cfg_link(
315  const char *src
316  const char *dest
317);
318@end example
319@end ifset
320
321@ifset is-Ada
322@end ifset
323
324@subheading STATUS CODES:
325
326@table @b
327@item ENAMETOOLONG
328A component of a pathname exceeded {NAME_MAX} characters,
329or an entire path name exceed {PATH_MAX} characters while
330{_POSIX_NO_TRUNC} is in effect.
331@item ENOENT
332A component of either path prefix does not exist.
333@item EACCES
334A component of either path prefix denies search permission.
335@item EACCES
336The requested link requires writing in a node with a mode that
337denies write permission.
338@item ENOENT
339The node named by src does not exist.
340@item EEXIST
341The node named by dest does exist.
342@item EPERM
343The calling process does not have the appropriate privilege to
344modify the node indicated by the src argument.
345@item EXDEV
346The link named by dest and the node named by src are from different
347configuration spaces.
348@item ENOSPC
349The node in which the entry for the new link is boeing placed
350cannot be extended because there is no space left on the
351configuration space containing the node.
352@item EIO
353An I/O error occurred while reading from or writing to the
354configuration space to make the link entry.
355@item EROFS
356The requested link requires writing in a node on a read-only
357configuration space.
358@item ENOSYS
359The function cfg_link() is not supported by this implementation.
360@item ELOOP
361A node appears more than once in the path specified by the
362cfg-path argument.
363@item ELOOP
364More than {SYMLOOP_MAX} symbolic links were encountered during
365resolution of the cfgpath argument.
366
367@end table
368
369@subheading DESCRIPTION:
370
371The @code{cfg_link} function shall atomically create a link between
372specified nodes, and increment by one the link count of the node
373specified by the @code{src} argument.  The @code{src} and @code{dest}
374arguments point to pathnnames which name existing nodes.
375
376@subheading NOTES:
377
378@page
379@subsection cfg_unlink - Remove a Configuration Link
380
381@subheading CALLING SEQUENCE:
382
383@ifset is-C
384@example
385int cfg_unlink(
386  const char    *cfgpath
387);
388@end example
389@end ifset
390
391@ifset is-Ada
392@end ifset
393
394@subheading STATUS CODES:
395
396@table @b
397@item ENAMETOOLONG
398A component of a pathname exceeded {NAME_MAX} characters,
399or an entire path name exceed {PATH_MAX} characters.
400@item ENOENT
401The named  node does not exist.
402@item EACCES
403Search permission is denied on the node containing the link to
404be removed.
405@item EACCES
406Write permission is denied on the node containing the link to
407be removed.
408@item ENOENT
409A component of cfgpath does not exist.
410@item EPERM
411The calling process does not have the appropriate priviledge to
412modify the node indicated by the path prefix of the cfgpath
413argument.
414@item EBUSY
415The node to be unlinked is the distinguished node of a mounted
416configuration space.
417@item EIO
418An I/O error occurred while deleting the link entry or deallocating
419the node.
420@item EROFS
421The named node resides in a read-opnly configuration space.
422@item ENOSYS
423The function cfg_unlink() is not supported by this implementation.
424@item ELOOP
425A node appears more than once in the path specified by the
426cfg-path argument.
427@item ELOOP
428More than {SYMLOOP_MAX} symbolic links were encountered during
429resolution of the cfgpath argument.
430
431@end table
432
433@subheading DESCRIPTION:
434
435The @code{cfg_unlink} function  removes the link between the node
436specified by the @code{cfgpath} path prefix and the parent node
437specified by @code{cfgpaht}, and shall decrement the link count
438of the @code{cfgpath} node.
439
440@subheading NOTES:
441
442@page
443@subsection cfg_open - Open a Configuration Space
444
445@subheading CALLING SEQUENCE:
446
447@ifset is-C
448@example
449int cfg_open(
450  const char     *pathnames[],
451  int             options,
452  int           (*compar)(const CFGENT **f1, const CFGENT **f2),
453  CFG           **cfgsrteam
454);
455@end example
456@end ifset
457
458@ifset is-Ada
459@end ifset
460
461@subheading STATUS CODES:
462
463@table @b
464@item EACCES
465Search permission is denied for any component of a pathname.
466@item ELOOP
467A loop exists in symbolic links encountered during resolution
468of a pathname.
469@item ENAMETOOLONG
470The length of a pathname exceeds {PATH_MAX}, or a pathname
471component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC}
472@item ENOENT
473The pathname argument is an empty string or the named node
474does not exist.
475@item EINVAL
476Either both or neither of CFG_LOGICAL and CFG_PHYSICAL are
477specified by the options argument ???????????
478@item ENOMEM
479Not enough memory is available to create the necessary structures.
480@item ENOSYS
481The function cfg_open() is not supported by this implementation.
482@item ELOOP
483More than {SYMLOOP_MAX} symbolic links were encountered during
484resolution of the pathnames argument.
485@item ENAMETOOLONG
486As a result of encountering a symbolic link in resolution of the
487pathname specified by the pathnames argument, the lenght of
488the substituted pathname string exceeded {PATH_MAX}.
489
490@end table
491
492@subheading DESCRIPTION:
493
494The @code{cfg_open} function shall open a configuration traversal stream
495rooted in the configuration nodes name by the @code{pathnames} argument.
496
497@subheading NOTES:
498
499@page
500@subsection cfg_read - Read a Configuration Space
501
502@subheading CALLING SEQUENCE:
503
504@ifset is-C
505@example
506int cfg_read( 
507  CFG           *cfgp,
508  CFGENT       **node
509);
510@end example
511@end ifset
512
513@ifset is-Ada
514@end ifset
515
516@subheading STATUS CODES:
517
518@table @b
519@item EACCES
520Search permission is denied for any component of a pathname.
521@item EBADF
522The cfgp argument does not refer to an open configuration
523space.
524@item ELOOP
525A loop exists in symbolic links encountered during resolution
526of a pathname.
527@item ENOENT
528A named node does not exist.
529@item ENOMEM
530Not enough memory is available to create the necessary structures.
531@item ENOSYS
532The function cfg_read() is not suported by this implementation.
533@item ELOOP
534More than {SYMLOOP_MAX} symbolic links were encountered during
535resolution of the cfgpath argument.
536@item ENAMETOOLONG
537As aresult of encountering a symbolic link in resolution of the
538pathname specified by the pathnames argument, the length of the
539substituted pathname string exceeded {PATH_MATH}.
540
541@end table
542
543@subheading DESCRIPTION:
544
545@subheading NOTES:
546
547@page
548@subsection cfg_children - Get Node Entries
549
550@subheading CALLING SEQUENCE:
551
552@ifset is-C
553@example
554int cfg_children(
555  CFG           *cfgp,
556  int            options,
557  CFGENT       **children
558);
559@end example
560@end ifset
561
562@ifset is-Ada
563@end ifset
564
565@subheading STATUS CODES:
566
567@table @b
568@item EACCES
569Search permission is denied for any component of a pathname
570@item EBADF
571The cfgp argument does not refer to an open configuration space.
572@item ELOOP
573A loop exists in symbolic links encountered during resolution of
574a pathname.
575@item ENAMETOOLONG
576The length of a pathname exceeds {PATH_MAX}, or a pathname
577component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is
578in effect.
579@item EINVAL
580The specified value of the optiions argument is invalid.
581@item ENOENT
582The named node does not exist.
583@item ENOMEM
584Not enough memory is available to create the necessary structures.
585@item ENOSYS
586The function cfg_children() is not supported by this implementation.
587
588@end table
589
590@subheading DESCRIPTION:
591
592@subheading NOTES:
593
594@page
595@subsection cfg_mark - Set Configuration Space Options
596
597@subheading CALLING SEQUENCE:
598
599@ifset is-C
600@example
601int cfg_mark(
602  CFG           *cfgp,
603  CFGENT        *f,
604  int            options
605);
606@end example
607@end ifset
608
609@ifset is-Ada
610@end ifset
611
612@subheading STATUS CODES:
613
614@table @b
615@item EINVAL
616The specified combination of the cfgp and f arguments is not
617supported by the implementation.
618@item EINVAL
619The specified value of the options argument is invalid.
620@item ENOSYS
621The function cfg_mark() is not supported by this implementation.
622
623@end table
624
625@subheading DESCRIPTION:
626
627The @code{cfg_mark} function modifies the subsequent behavior of
628the cfg functions with regard to the node referenced by the structure
629pointed to by the argument f or the configuration space referenced by
630the structure pointed to by the argument @code{cfgp}.
631
632@subheading NOTES:
633
634@page
635@subsection cfg_close - Close a Configuration Space
636
637@subheading CALLING SEQUENCE:
638
639@ifset is-C
640@example
641int cfg_close(
642  CFG           *cfgp
643);
644@end example
645@end ifset
646
647@ifset is-Ada
648@end ifset
649
650@subheading STATUS CODES:
651
652@table @b
653@item EBADF
654The cfgp argument does not refer to an open configuration space
655traversal stream.
656@item ENOSYS
657The function cfg_close() is not supported by this implementatioin.
658
659@end table
660
661@subheading DESCRIPTION:
662
663The @code{cfg_close} function closes a configuration space transversal
664stream.
665
666@subheading NOTES:
667
Note: See TracBrowser for help on using the repository browser.