Changeset e6bfa70 in rtems


Ignore:
Timestamp:
Aug 10, 1998, 2:44:39 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
8c82d8d1
Parents:
0c0419a1
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/confspace.t

    r0c0419a1 re6bfa70  
    1818@itemize @bullet
    1919@item @code{cfg_mount} - Mount a Configuration Space
    20 @item @code{cfg_unmount} -
    21 @item @code{cfg_mknod} -
    22 @item @code{cfg_get} -
    23 @item @code{cfg_set} -
    24 @item @code{cfg_link} -
    25 @item @code{cfg_unlink} -
    26 @item @code{cfg_open} -
    27 @item @code{cfg_read} -
    28 @item @code{cfg_children} -
    29 @item @code{cfg_mark} -
    30 @item @code{cfg_close} -
     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
    3131@end itemize
    3232
     
    5353  const char     *cfgpath,
    5454  log_facility_t  notification,
    55   int             logdes
    5655);
    5756@end example
     
    6665@item EPERM
    6766The caller does not have the appropriate privilege.
    68 
    69 @end table
    70 
    71 @subheading DESCRIPTION:
    72 
    73 @subheading NOTES:
    74 
    75 @page
    76 @subsection cfg_unmount -
     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
    7796
    7897@subheading CALLING SEQUENCE:
     
    81100@example
    82101int cfg_unmount(
    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 E
    94 The
    95 
    96 @end table
    97 
    98 @subheading DESCRIPTION:
    99 
    100 @subheading NOTES:
    101 
    102 @page
    103 @subsection cfg_mknod -
     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
    104151
    105152@subheading CALLING SEQUENCE:
     
    108155@example
    109156int cfg_mknod(
    110 );
    111 @end example
    112 @end ifset
    113 
    114 @ifset is-Ada
    115 @end ifset
    116 
    117 @subheading STATUS CODES:
    118 
    119 @table @b
    120 @item E
    121 The
    122 
    123 @end table
    124 
    125 @subheading DESCRIPTION:
    126 
    127 @subheading NOTES:
    128 
    129 @page
    130 @subsection cfg_get -
     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
    131211
    132212@subheading CALLING SEQUENCE:
     
    135215@example
    136216int cfg_get(
    137 );
    138 @end example
    139 @end ifset
    140 
    141 @ifset is-Ada
    142 @end ifset
    143 
    144 @subheading STATUS CODES:
    145 
    146 @table @b
    147 @item E
    148 The
    149 
    150 @end table
    151 
    152 @subheading DESCRIPTION:
    153 
    154 @subheading NOTES:
    155 
    156 @page
    157 @subsection cfg_set -
     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
    158260
    159261@subheading CALLING SEQUENCE:
     
    162264@example
    163265int cfg_set(
    164 );
    165 @end example
    166 @end ifset
    167 
    168 @ifset is-Ada
    169 @end ifset
    170 
    171 @subheading STATUS CODES:
    172 
    173 @table @b
    174 @item E
    175 The
    176 
    177 @end table
    178 
    179 @subheading DESCRIPTION:
    180 
    181 @subheading NOTES:
    182 
    183 @page
    184 @subsection cfg_link -
     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
    185309
    186310@subheading CALLING SEQUENCE:
     
    189313@example
    190314int cfg_link(
    191 );
    192 @end example
    193 @end ifset
    194 
    195 @ifset is-Ada
    196 @end ifset
    197 
    198 @subheading STATUS CODES:
    199 
    200 @table @b
    201 @item E
    202 The
    203 
    204 @end table
    205 
    206 @subheading DESCRIPTION:
    207 
    208 @subheading NOTES:
    209 
    210 @page
    211 @subsection cfg_unlink -
     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
    212380
    213381@subheading CALLING SEQUENCE:
     
    216384@example
    217385int cfg_unlink(
    218 );
    219 @end example
    220 @end ifset
    221 
    222 @ifset is-Ada
    223 @end ifset
    224 
    225 @subheading STATUS CODES:
    226 
    227 @table @b
    228 @item E
    229 The
    230 
    231 @end table
    232 
    233 @subheading DESCRIPTION:
    234 
    235 @subheading NOTES:
    236 
    237 @page
    238 @subsection cfg_open -
     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
    239444
    240445@subheading CALLING SEQUENCE:
     
    243448@example
    244449int cfg_open(
    245 );
    246 @end example
    247 @end ifset
    248 
    249 @ifset is-Ada
    250 @end ifset
    251 
    252 @subheading STATUS CODES:
    253 
    254 @table @b
    255 @item E
    256 The
    257 
    258 @end table
    259 
    260 @subheading DESCRIPTION:
    261 
    262 @subheading NOTES:
    263 
    264 @page
    265 @subsection cfg_read -
    266 
    267 @subheading CALLING SEQUENCE:
    268 
    269 @ifset is-C
    270 @example
    271 int cfg_read(
    272 );
    273 @end example
    274 @end ifset
    275 
    276 @ifset is-Ada
    277 @end ifset
    278 
    279 @subheading STATUS CODES:
    280 
    281 @table @b
    282 @item E
    283 The
    284 
    285 @end table
    286 
    287 @subheading DESCRIPTION:
    288 
    289 @subheading NOTES:
    290 
    291 @page
    292 @subsection cfg_children -
     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
    293549
    294550@subheading CALLING SEQUENCE:
     
    297553@example
    298554int cfg_children(
    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 E
    310 The
    311 
    312 @end table
    313 
    314 @subheading DESCRIPTION:
    315 
    316 @subheading NOTES:
    317 
    318 @page
    319 @subsection cfg_mark -
     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
    320596
    321597@subheading CALLING SEQUENCE:
     
    324600@example
    325601int cfg_mark(
    326 );
    327 @end example
    328 @end ifset
    329 
    330 @ifset is-Ada
    331 @end ifset
    332 
    333 @subheading STATUS CODES:
    334 
    335 @table @b
    336 @item E
    337 The
    338 
    339 @end table
    340 
    341 @subheading DESCRIPTION:
    342 
    343 @subheading NOTES:
    344 
    345 @page
    346 @subsection cfg_close -
     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
    347636
    348637@subheading CALLING SEQUENCE:
     
    351640@example
    352641int cfg_close(
    353 );
    354 @end example
    355 @end ifset
    356 
    357 @ifset is-Ada
    358 @end ifset
    359 
    360 @subheading STATUS CODES:
    361 
    362 @table @b
    363 @item E
    364 The
    365 
    366 @end table
    367 
    368 @subheading DESCRIPTION:
    369 
    370 @subheading NOTES:
    371 
     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 TracChangeset for help on using the changeset viewer.