Changeset 5431beb in rtems-docs


Ignore:
Timestamp:
Nov 9, 2016, 5:54:02 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, 5, am, master
Children:
9330bfb
Parents:
f7dbf17
Message:

filesystem: Fix header levels.

Location:
filesystem
Files:
12 edited

Legend:

Unmodified
Added
Removed
  • filesystem/call_development.rst

    rf7dbf17 r5431beb  
    66
    77System Call Development Notes
    8 #############################
     8*****************************
    99
    1010This set of routines represents the application's interface to files and
     
    1616#. access()
    1717
    18 # .chdir()
     18#. chdir()
    1919
    2020#. chmod()
     
    7272======
    7373
    74 **File:**
    75 
    76 access.c
    77 
    78 **Processing:**
    79 
    80 This routine is layered on the stat() function. It acquires the current status
    81 information for the specified file and then determines if the caller has the
    82 ability to access the file for read, write or execute according to the mode
    83 argument to this function.
    84 
    85 **Development Comments:**
    86 
    87 This routine is layered on top of the stat() function. As long as the st_mode
    88 element in the returned structure follow the standard UNIX conventions, this
    89 function should support other filesystems without alteration.
     74File:
     75    ``access.c``
     76
     77Processing:
     78    This routine is layered on the stat() function. It acquires the current
     79    status information for the specified file and then determines if the caller
     80    has the ability to access the file for read, write or execute according to
     81    the mode argument to this function.
     82
     83Development Comments:
     84    This routine is layered on top of the stat() function. As long as the
     85    st_mode element in the returned structure follow the standard UNIX
     86    conventions, this function should support other filesystems without
     87    alteration.
    9088
    9189chdir
    9290=====
    9391
    94 **File:**
    95 
    96 chdir.c
    97 
    98 **Processing:**
    99 
    100 This routine will determine if the pathname that we are attempting to make that
    101 current directory exists and is in fact a directory. If these conditions are
    102 met the global indication of the current directory (rtems_filesystem_current)
    103 is set to the rtems_filesystem_location_info_t structure that is returned by
    104 the rtems_filesystem_evaluate_path() routine.
    105 
    106 **Development Comments:**
    107 
    108 This routine is layered on the rtems_filesystem_evaluate_path() routine and the
    109 filesystem specific OP table function node_type().
    110 
    111 The routine ``node_type()`` must be a routine provided for each filesystem
    112 since it must access the filesystems node information to determine which of the
    113 following types the node is:
    114 
    115 - RTEMS_FILESYSTEM_DIRECTORY
    116 
    117 - RTEMS_FILESYSTEM_DEVICE
    118 
    119 - RTEMS_FILESYSTEM_HARD_LINK
    120 
    121 - RTEMS_FILESYSTEM_MEMORY_FILE
    122 
    123 This acknowledges that the form of the node management information can vary
    124 from one filesystem implementation to another.
    125 
    126 RTEMS has a special global structure that maintains the current directory
    127 location. This global variable is of type rtems_filesystem_location_info_t and
    128 is called rtems_filesystem_current. This structure is not always valid. In
    129 order to determine if the structure is valid, you must first test the
    130 node_access element of this structure. If the pointer is NULL, then the
    131 structure does not contain a valid indication of what the current directory is.
     92File:
     93    ``chdir.c``
     94
     95Processing:
     96    This routine will determine if the pathname that we are attempting to make
     97    that current directory exists and is in fact a directory. If these
     98    conditions are met the global indication of the current directory
     99    (rtems_filesystem_current) is set to the rtems_filesystem_location_info_t
     100    structure that is returned by the rtems_filesystem_evaluate_path() routine.
     101
     102Development Comments:
     103    This routine is layered on the rtems_filesystem_evaluate_path() routine and
     104    the filesystem specific OP table function node_type().
     105
     106    The routine ``node_type()`` must be a routine provided for each filesystem
     107    since it must access the filesystems node information to determine which of
     108    the following types the node is:
     109
     110    - RTEMS_FILESYSTEM_DIRECTORY
     111
     112    - RTEMS_FILESYSTEM_DEVICE
     113
     114    - RTEMS_FILESYSTEM_HARD_LINK
     115
     116    - RTEMS_FILESYSTEM_MEMORY_FILE
     117
     118    This acknowledges that the form of the node management information can vary
     119    from one filesystem implementation to another.
     120
     121    RTEMS has a special global structure that maintains the current directory
     122    location. This global variable is of type rtems_filesystem_location_info_t
     123    and is called rtems_filesystem_current. This structure is not always
     124    valid. In order to determine if the structure is valid, you must first test
     125    the node_access element of this structure. If the pointer is NULL, then the
     126    structure does not contain a valid indication of what the current directory
     127    is.
    132128
    133129chmod
    134130=====
    135131
    136 **File:**
    137 
    138 chmod.c
    139 
    140 **Processing:**
    141 
    142 This routine is layered on the ``open()``, ``fchmod()`` and ``close()``
    143 functions. As long as the standard interpretation of the mode_t value is
    144 maintained, this routine should not need modification to support other
    145 filesystems.
    146 
    147 **Development Comments:**
    148 
    149 The routine first determines if the selected file can be open with read/write
    150 access.  This is required to allow modification of the mode associated with the
    151 selected path.
    152 
    153 The ``fchmod()`` function is used to actually change the mode of the path using
    154 the integer file descriptor returned by the ``open()`` function.
    155 
    156 After mode modification, the open file descriptor is closed.
     132File:
     133    ``chmod.c``
     134
     135Processing:
     136    This routine is layered on the ``open()``, ``fchmod()`` and ``close()``
     137    functions. As long as the standard interpretation of the mode_t value is
     138    maintained, this routine should not need modification to support other
     139    filesystems.
     140
     141Development Comments:
     142    The routine first determines if the selected file can be open with
     143    read/write access.  This is required to allow modification of the mode
     144    associated with the selected path.
     145
     146    The ``fchmod()`` function is used to actually change the mode of the path
     147    using the integer file descriptor returned by the ``open()`` function.
     148
     149    After mode modification, the open file descriptor is closed.
    157150
    158151chown
    159152=====
    160153
    161 **File:**
    162 
    163 chown.c
    164 
    165 **Processing:**
    166 
    167 This routine is layered on the ``rtems_filesystem_evaluate_path()`` and the
    168 file system specific ``chown()`` routine that is specified in the OPS table for
    169 the file system.
    170 
    171 **Development Comments:**
    172 
    173 ``rtems_filesystem_evaluate_path()`` is used to determine if the path specified
    174 actually exists. If it does a ``rtems_filesystem_location_info_t`` structure
    175 will be obtained that allows the shell function to locate the OPS table that is
    176 to be used for this filesystem.
    177 
    178 It is possible that the ``chown()`` function that should be in the OPS table is
    179 not defined. A test for a non-NULL OPS table ``chown()`` entry is performed
    180 before the function is called.
    181 
    182 If the ``chown()`` function is defined in the indicated OPS table, the function
    183 is called with the ``rtems_filesystem_location_info_t`` structure returned from
    184 the path evaluation routine, the desired owner, and group information.
     154File:
     155    ``chown.c``
     156
     157Processing:
     158    This routine is layered on the ``rtems_filesystem_evaluate_path()`` and the
     159    file system specific ``chown()`` routine that is specified in the OPS table
     160    for the file system.
     161
     162Development Comments:
     163    ``rtems_filesystem_evaluate_path()`` is used to determine if the path
     164    specified actually exists. If it does a
     165    ``rtems_filesystem_location_info_t`` structure will be obtained that allows
     166    the shell function to locate the OPS table that is to be used for this
     167    filesystem.
     168
     169    It is possible that the ``chown()`` function that should be in the OPS
     170    table is not defined. A test for a non-NULL OPS table ``chown()`` entry is
     171    performed before the function is called.
     172
     173    If the ``chown()`` function is defined in the indicated OPS table, the
     174    function is called with the ``rtems_filesystem_location_info_t`` structure
     175    returned from the path evaluation routine, the desired owner, and group
     176    information.
    185177
    186178close
    187179=====
    188180
    189 **File:**
    190 
    191 close.c
    192 
    193 **Processing:**
    194 
    195 This routine will allow for the closing of both network connections and file
    196 system devices. If the file descriptor is associated with a network device, the
    197 appropriate network function handler will be selected from a table of
    198 previously registered network functions (``rtems_libio_handlers``) and that
    199 function will be invoked.
    200 
    201 If the file descriptor refers to an entry in the filesystem, the appropriate
    202 handler will be selected using information that has been placed in the file
    203 control block for the device (``rtems_libio_t`` structure).
    204 
    205 **Development Comments:**
    206 
    207 ``rtems_file_descriptor_type`` examines some of the upper bits of the file
    208 descriptor index. If it finds that the upper bits are set in the file
    209 descriptor index, the device referenced is a network device.
    210 
    211 Network device handlers are obtained from a special registration table
    212 (``rtems_libio_handlers``) that is set up during network initialization. The
    213 network handler invoked and the status of the network handler will be returned
    214 to the calling process.
    215 
    216 If none of the upper bits are set in the file descriptor index, the file
    217 descriptor refers to an element of the RTEMS filesystem.
    218 
    219 The following sequence will be performed for any filesystem file descriptor:
    220 
    221 #. Use the ``rtems_libio_iop()`` function to obtain the ``rtems_libio_t``
    222    structure for the file descriptor
    223 
    224 #. Range check the file descriptor using ``rtems_libio_check_fd()``
    225 
    226 #. Determine if there is actually a function in the selected handler table that
    227    processes the ``close()`` operation for the filesystem and node type
    228    selected.  This is generally done to avoid execution attempts on functions
    229    that have not been implemented.
    230 
    231 # If the function has been defined it is invoked with the file control
    232    block pointer as its argument.
    233 
    234 #. The file control block that was associated with the open file descriptor is
    235    marked as free using ``rtems_libio_free()``.
    236 
    237 #. The return code from the close handler is then passed back to the calling
    238    program.
    239  
     181File:
     182    ``close.c``
     183
     184Processing:
     185    This routine will allow for the closing of both network connections and
     186    file system devices. If the file descriptor is associated with a network
     187    device, the appropriate network function handler will be selected from a
     188    table of previously registered network functions (``rtems_libio_handlers``)
     189    and that function will be invoked.
     190
     191    If the file descriptor refers to an entry in the filesystem, the
     192    appropriate handler will be selected using information that has been placed
     193    in the file control block for the device (``rtems_libio_t`` structure).
     194
     195Development Comments:
     196    ``rtems_file_descriptor_type`` examines some of the upper bits of the file
     197    descriptor index. If it finds that the upper bits are set in the file
     198    descriptor index, the device referenced is a network device.
     199
     200    Network device handlers are obtained from a special registration table
     201    (``rtems_libio_handlers``) that is set up during network
     202    initialization. The network handler invoked and the status of the network
     203    handler will be returned to the calling process.
     204
     205    If none of the upper bits are set in the file descriptor index, the file
     206    descriptor refers to an element of the RTEMS filesystem.
     207
     208    The following sequence will be performed for any filesystem file descriptor:
     209
     210    #. Use the ``rtems_libio_iop()`` function to obtain the ``rtems_libio_t``
     211       structure for the file descriptor
     212
     213    #. Range check the file descriptor using ``rtems_libio_check_fd()``
     214
     215    #. Determine if there is actually a function in the selected handler table
     216       that processes the ``close()`` operation for the filesystem and node
     217       type selected.  This is generally done to avoid execution attempts on
     218       functions that have not been implemented.
     219
     220    #. If the function has been defined it is invoked with the file control
     221       block pointer as its argument.
     222
     223    #. The file control block that was associated with the open file descriptor
     224       is marked as free using ``rtems_libio_free()``.
     225
     226    #. The return code from the close handler is then passed back to the
     227       calling program.
     228
    240229closedir
    241230========
    242231
    243 **File:**
    244 
    245 closedir.c
    246 
    247 **Processing:**
    248 
    249 The code was obtained from the BSD group. This routine must clean up the memory
    250 resources that are required to track an open directory. The code is layered on
    251 the ``close()`` function and standard memory ``free()`` functions. It should
    252 not require alterations to support other filesystems.
    253 
    254 **Development Comments:**
    255 
    256 The routine alters the file descriptor and the index into the DIR structure to
    257 make it an invalid file descriptor. Apparently the memory that is about to be
    258 freed may still be referenced before it is reallocated.
    259 
    260 The dd_buf structure's memory is reallocated before the control structure that
    261 contains the pointer to the dd_buf region.
    262 
    263 DIR control memory is reallocated.
    264 
    265 The ``close()`` function is used to free the file descriptor index.
     232File:
     233    ``closedir.c``
     234
     235Processing:
     236    The code was obtained from the BSD group. This routine must clean up the
     237    memory resources that are required to track an open directory. The code is
     238    layered on the ``close()`` function and standard memory ``free()``
     239    functions. It should not require alterations to support other filesystems.
     240
     241Development Comments:
     242    The routine alters the file descriptor and the index into the DIR structure
     243    to make it an invalid file descriptor. Apparently the memory that is about
     244    to be freed may still be referenced before it is reallocated.
     245
     246    The dd_buf structure's memory is reallocated before the control structure
     247    that contains the pointer to the dd_buf region.
     248
     249    DIR control memory is reallocated.
     250
     251    The ``close()`` function is used to free the file descriptor index.
    266252
    267253dup()      Unimplemented
    268254========================
    269255
    270 **File:**
    271 
    272 dup.c
    273 
    274 **Processing:**
    275 
    276 **Development Comments:**
     256File:
     257    ``dup.c``
     258
     259Processing:
     260
     261Development Comments:
    277262
    278263dup2()      Unimplemented
    279264=========================
    280265
    281 **File:**
    282 
    283 dup2.c
    284 
    285 **Processing:**
    286 
    287 **Development Comments:**
     266File:
     267    ``dup2.c``
     268
     269Processing:
     270
     271Development Comments:
    288272
    289273fchmod
    290274======
    291275
    292 **File:**
    293 
    294 fchmod.c
    295 
    296 **Processing:**
    297 
    298 This routine will alter the permissions of a node in a filesystem. It is
    299 layered on the following functions and macros:
    300 
    301 - rtems_file_descriptor_type()
    302 
    303 - rtems_libio_iop()
    304 
    305 - rtems_libio_check_fd()
    306 
    307 - rtems_libio_check_permissions()
    308 
    309 - fchmod() function that is referenced by the handler table in the file control
    310   block associated with this file descriptor
    311 
    312 **Development Comments:**
    313 
    314 The routine will test to see if the file descriptor index is associated with a
    315 network connection. If it is, an error is returned from this routine.
    316 
    317 The file descriptor index is used to obtain the associated file control block.
    318 
    319 The file descriptor value is range checked.
    320 
    321 The file control block is examined to determine if it has write permissions to
    322 allow us to alter the mode of the file.
    323 
    324 A test is made to determine if the handler table that is referenced in the file
    325 control block contains an entry for the ``fchmod()`` handler function. If it does
    326 not, an error is returned to the calling routine.
    327 
    328 If the ``fchmod()`` handler function exists, it is called with the file control
    329 block and the desired mode as parameters.
     276File:
     277    ``fchmod.c``
     278
     279Processing:
     280    This routine will alter the permissions of a node in a filesystem. It is
     281    layered on the following functions and macros:
     282
     283    - rtems_file_descriptor_type()
     284
     285    - rtems_libio_iop()
     286
     287    - rtems_libio_check_fd()
     288
     289    - rtems_libio_check_permissions()
     290
     291    - fchmod() function that is referenced by the handler table in the file
     292      control block associated with this file descriptor
     293
     294Development Comments:
     295    The routine will test to see if the file descriptor index is associated
     296    with a network connection. If it is, an error is returned from this
     297    routine.
     298
     299    The file descriptor index is used to obtain the associated file control
     300    block.
     301
     302    The file descriptor value is range checked.
     303
     304    The file control block is examined to determine if it has write permissions
     305    to allow us to alter the mode of the file.
     306
     307    A test is made to determine if the handler table that is referenced in the
     308    file control block contains an entry for the ``fchmod()`` handler
     309    function. If it does not, an error is returned to the calling routine.
     310
     311    If the ``fchmod()`` handler function exists, it is called with the file
     312    control block and the desired mode as parameters.
    330313
    331314fcntl()
    332315=======
    333316
    334 **File:**
    335 
    336 fcntl.c
    337 
    338 **Processing:**
    339 
    340 This routine currently only interacts with the file control block. If the
    341 structure of the file control block and the associated meanings do not change,
    342 the partial implementation of ``fcntl()`` should remain unaltered for other
    343 filesystem implementations.
    344 
    345 **Development Comments:**
    346 
    347 The only commands that have been implemented are the F_GETFD and F_SETFD.  The
    348 commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the``flags`` element
    349 of the file control block associated with the file descriptor index.
    350 
    351 The current implementation of the function performs the sequence of
    352 operations below:
    353 
    354 # Test to see if we are trying to operate on a file descriptor
    355   associated with a network connection
    356 
    357 # Obtain the file control block that is associated with the file
    358   descriptor index
    359 
    360 # Perform a range check on the file descriptor index.
     317File:
     318    ``fcntl.c``
     319
     320Processing:
     321    This routine currently only interacts with the file control block. If the
     322    structure of the file control block and the associated meanings do not
     323    change, the partial implementation of ``fcntl()`` should remain unaltered
     324    for other filesystem implementations.
     325
     326Development Comments:
     327    The only commands that have been implemented are the F_GETFD and F_SETFD.
     328    The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the``flags``
     329    element of the file control block associated with the file descriptor
     330    index.
     331
     332    The current implementation of the function performs the sequence of
     333    operations below:
     334
     335    #. Test to see if we are trying to operate on a file descriptor associated
     336       with a network connection
     337
     338    #. Obtain the file control block that is associated with the file
     339       descriptor index
     340
     341    #. Perform a range check on the file descriptor index.
    361342
    362343fdatasync
    363344=========
    364345
    365 **File:**
    366 
    367 fdatasync.c
    368 
    369 **Processing:**
    370 
    371 This routine is a template in the in memory filesystem that will route us to
    372 the appropriate handler function to carry out the fdatasync() processing. In
    373 the in memory filesystem this function is not necessary. Its function in a disk
    374 based file system that employs a memory cache is to flush all memory based data
    375 buffers to disk. It is layered on the following functions and macros:
    376 
    377 - rtems_file_descriptor_type()
    378 
    379 - rtems_libio_iop()
    380 
    381 - rtems_libio_check_fd()
    382 
    383 - rtems_libio_check_permissions()
    384 
    385 - fdatasync() function that is referenced by the handler table in the file
    386   control block associated with this file descriptor
    387 
    388 **Development Comments:**
    389 
    390 The routine will test to see if the file descriptor index is associated with a
    391 network connection. If it is, an error is returned from this routine.
    392 
    393 The file descriptor index is used to obtain the associated file control block.
    394 
    395 The file descriptor value is range checked.
    396 
    397 The file control block is examined to determine if it has write permissions to
    398 the file.
    399 
    400 A test is made to determine if the handler table that is referenced in the file
    401 control block contains an entry for the fdatasync() handler function.  If it
    402 does not an error is returned to the calling routine.
    403 
    404 If the fdatasync() handler function exists, it is called with the file control
    405 block as its parameter.
     346File:
     347    ``fdatasync.c``
     348
     349Processing:
     350    This routine is a template in the in memory filesystem that will route us
     351    to the appropriate handler function to carry out the fdatasync()
     352    processing. In the in memory filesystem this function is not necessary. Its
     353    function in a disk based file system that employs a memory cache is to
     354    flush all memory based data buffers to disk. It is layered on the following
     355    functions and macros:
     356
     357    - rtems_file_descriptor_type()
     358
     359    - rtems_libio_iop()
     360
     361    - rtems_libio_check_fd()
     362
     363    - rtems_libio_check_permissions()
     364
     365    - fdatasync() function that is referenced by the handler table in the file
     366      control block associated with this file descriptor
     367
     368Development Comments:
     369    The routine will test to see if the file descriptor index is associated
     370    with a network connection. If it is, an error is returned from this
     371    routine.
     372
     373    The file descriptor index is used to obtain the associated file control
     374    block.
     375
     376    The file descriptor value is range checked.
     377
     378    The file control block is examined to determine if it has write permissions
     379    to the file.
     380
     381    A test is made to determine if the handler table that is referenced in the
     382    file control block contains an entry for the fdatasync() handler function.
     383    If it does not an error is returned to the calling routine.
     384
     385    If the fdatasync() handler function exists, it is called with the file
     386    control block as its parameter.
    406387
    407388fpathconf
    408389=========
    409390
    410 **File:**
    411 
    412 fpathconf.c
    413 
    414 **Processing:**
    415 
    416 This routine is layered on the following functions and macros:
    417 
    418 - rtems_file_descriptor_type()
    419 
    420 - rtems_libio_iop()
    421 
    422 - rtems_libio_check_fd()
    423 
    424 - rtems_libio_check_permissions()
    425 
    426 When a filesystem is mounted, a set of constants is specified for the
    427 filesystem.  These constants are stored with the mount table entry for the
    428 filesystem. These constants appear in the POSIX standard and are listed below.
    429 
    430 - PCLINKMAX
    431 
    432 - PCMAXCANON
    433 
    434 - PCMAXINPUT
    435 
    436 - PCNAMEMAX
    437 
    438 - PCPATHMAX
    439 
    440 - PCPIPEBUF
    441 
    442 - PCCHOWNRESTRICTED
    443 
    444 - PCNOTRUNC
    445 
    446 - PCVDISABLE
    447 
    448 - PCASYNCIO
    449 
    450 - PCPRIOIO
    451 
    452 - PCSYNCIO
    453 
    454 This routine will find the mount table information associated the file control
    455 block for the specified file descriptor parameter. The mount table entry
    456 structure contains a set of filesystem specific constants that can be accessed
    457 by individual identifiers.
    458 
    459 **Development Comments:**
    460 
    461 The routine will test to see if the file descriptor index is associated with a
    462 network connection. If it is, an error is returned from this routine.
    463 
    464 The file descriptor index is used to obtain the associated file control block.
    465 
    466 The file descriptor value is range checked.
    467 
    468 The file control block is examined to determine if it has read permissions to
    469 the file.
    470 
    471 Pathinfo in the file control block is used to locate the mount table entry for
    472 the filesystem associated with the file descriptor.
    473 
    474 The mount table entry contains the pathconf_limits_and_options element.  This
    475 element is a table of constants that is associated with the filesystem.
    476 
    477 The name argument is used to reference the desired constant from the
    478 pathconf_limits_and_options table.
     391File:
     392    ``fpathconf.c``
     393
     394Processing:
     395    This routine is layered on the following functions and macros:
     396
     397    - rtems_file_descriptor_type()
     398
     399    - rtems_libio_iop()
     400
     401    - rtems_libio_check_fd()
     402
     403    - rtems_libio_check_permissions()
     404
     405    When a filesystem is mounted, a set of constants is specified for the
     406    filesystem.  These constants are stored with the mount table entry for the
     407    filesystem. These constants appear in the POSIX standard and are listed
     408    below.
     409
     410    - PCLINKMAX
     411
     412    - PCMAXCANON
     413
     414    - PCMAXINPUT
     415
     416    - PCNAMEMAX
     417
     418    - PCPATHMAX
     419
     420    - PCPIPEBUF
     421
     422    - PCCHOWNRESTRICTED
     423
     424    - PCNOTRUNC
     425
     426    - PCVDISABLE
     427
     428    - PCASYNCIO
     429
     430    - PCPRIOIO
     431
     432    - PCSYNCIO
     433
     434    This routine will find the mount table information associated the file
     435    control block for the specified file descriptor parameter. The mount table
     436    entry structure contains a set of filesystem specific constants that can be
     437    accessed by individual identifiers.
     438
     439Development Comments:
     440    The routine will test to see if the file descriptor index is associated
     441    with a network connection. If it is, an error is returned from this
     442    routine.
     443
     444    The file descriptor index is used to obtain the associated file control
     445    block.
     446
     447    The file descriptor value is range checked.
     448
     449    The file control block is examined to determine if it has read permissions
     450    to the file.
     451
     452    Pathinfo in the file control block is used to locate the mount table entry
     453    for the filesystem associated with the file descriptor.
     454
     455    The mount table entry contains the pathconf_limits_and_options element.
     456    This element is a table of constants that is associated with the
     457    filesystem.
     458
     459    The name argument is used to reference the desired constant from the
     460    pathconf_limits_and_options table.
    479461
    480462fstat
    481463=====
    482464
    483 **File:**
    484 
    485 fstat.c
    486 
    487 **Processing:**
    488 
    489 This routine will return information concerning a file or network
    490 connection. If the file descriptor is associated with a network connection, the
    491 current implementation of ``fstat()`` will return a mode set to
    492 ``S_IFSOCK``. In a later version, this routine will map the status of a network
    493 connection to an external handler routine.
    494 
    495 If the file descriptor is associated with a node under a filesystem, the
    496 fstat() routine will map to the fstat() function taken from the node handler
    497 table.
    498 
    499 **Development Comments:**
    500 
    501 This routine validates that the struct stat pointer is not NULL so that the
    502 return location is valid.
    503 
    504 The struct stat is then initialized to all zeros.
    505 
    506 rtems_file_descriptor_type() is then used to determine if the file descriptor
    507 is associated with a network connection. If it is, network status processing is
    508 performed. In the current implementation, the file descriptor type processing
    509 needs to be improved. It currently just drops into the normal processing for
    510 file system nodes.
    511 
    512 If the file descriptor is associated with a node under a filesystem, the
    513 following steps are performed:
    514 
    515 # Obtain the file control block that is associated with the file descriptor
    516   index.
    517 
    518 # Range check the file descriptor index.
    519 
    520 # Test to see if there is a non-NULL function pointer in the handler table for
    521   the fstat() function. If there is, invoke the function with the file control
    522   block and the pointer to the stat structure.
     465File:
     466    ``fstat.c``
     467
     468Processing:
     469    This routine will return information concerning a file or network
     470    connection. If the file descriptor is associated with a network connection,
     471    the current implementation of ``fstat()`` will return a mode set to
     472    ``S_IFSOCK``. In a later version, this routine will map the status of a
     473    network connection to an external handler routine.
     474
     475    If the file descriptor is associated with a node under a filesystem, the
     476    fstat() routine will map to the fstat() function taken from the node
     477    handler table.
     478
     479Development Comments:
     480    This routine validates that the struct stat pointer is not NULL so that the
     481    return location is valid.
     482
     483    The struct stat is then initialized to all zeros.
     484
     485    rtems_file_descriptor_type() is then used to determine if the file
     486    descriptor is associated with a network connection. If it is, network
     487    status processing is performed. In the current implementation, the file
     488    descriptor type processing needs to be improved. It currently just drops
     489    into the normal processing for file system nodes.
     490
     491    If the file descriptor is associated with a node under a filesystem, the
     492    following steps are performed:
     493
     494    #. Obtain the file control block that is associated with the file descriptor
     495       index.
     496
     497    #. Range check the file descriptor index.
     498
     499    #. Test to see if there is a non-NULL function pointer in the handler table
     500       for the fstat() function. If there is, invoke the function with the file
     501       control block and the pointer to the stat structure.
    523502
    524503ioctl
    525504=====
    526505
    527 **File:**
    528 
    529 ioctl.c
    530 
    531 **Processing:**
    532 
    533 Not defined in the POSIX 1003.1b standard but commonly supported in most UNIX
    534 and POSIX system. Ioctl() is a catchall for I/O operations. Routine is layered
    535 on external network handlers and filesystem specific handlers.  The development
    536 of new filesystems should not alter the basic processing performed by this
    537 routine.
    538 
    539 **Development Comments:**
    540 
    541 The file descriptor is examined to determine if it is associated with a network
    542 device. If it is processing is mapped to an external network handler. The value
    543 returned by this handler is then returned to the calling program.
    544 
    545 File descriptors that are associated with a filesystem undergo the following
    546 processing:
    547 
    548 # The file descriptor index is used to obtain the associated file control
    549   block.
    550 
    551 # The file descriptor value is range checked.
    552 
    553 # A test is made to determine if the handler table that is referenced
    554   in the file control block contains an entry for the ioctl() handler
    555   function. If it does not, an error is returned to the calling routine.
    556 
    557 # If the ioctl() handler function exists, it is called with the file control
    558   block, the command and buffer as its parameters.
    559 
    560 # The return code from this function is then sent to the calling routine.
     506File:
     507    ``ioctl.c``
     508
     509Processing:
     510    Not defined in the POSIX 1003.1b standard but commonly supported in most
     511    UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine is
     512    layered on external network handlers and filesystem specific handlers.  The
     513    development of new filesystems should not alter the basic processing
     514    performed by this routine.
     515
     516Development Comments:
     517    The file descriptor is examined to determine if it is associated with a
     518    network device. If it is processing is mapped to an external network
     519    handler. The value returned by this handler is then returned to the calling
     520    program.
     521
     522    File descriptors that are associated with a filesystem undergo the
     523    following processing:
     524
     525    #. The file descriptor index is used to obtain the associated file control
     526       block.
     527
     528    #. The file descriptor value is range checked.
     529
     530    #. A test is made to determine if the handler table that is referenced in
     531       the file control block contains an entry for the ioctl() handler
     532       function. If it does not, an error is returned to the calling routine.
     533
     534    #. If the ioctl() handler function exists, it is called with the file
     535       control block, the command and buffer as its parameters.
     536
     537    #. The return code from this function is then sent to the calling routine.
    561538
    562539link
    563540====
    564541
    565 **File:**
    566 
    567 link.c
    568 
    569 **Processing:**
    570 
    571 This routine will establish a hard link to a file, directory or a device.  The
    572 target of the hard link must be in the same filesystem as the new link being
    573 created. A link to an existing link is also permitted but the existing link is
    574 evaluated before the new link is made. This implies that links to links are
    575 reduced to links to files, directories or devices before they are made.
    576 
    577 **Development Comments:**
    578 
    579 Calling parameters:
    580 
    581 .. code-block:: c
    582 
    583     const char   *existing
    584     const char   *new
    585 
    586 link() will determine if the target of the link actually exists using
    587 rtems_filesystem_evaluate_path()
    588 
    589 rtems_filesystem_get_start_loc() is used to determine where to start the path
    590 evaluation of the new name. This macro examines the first characters of the
    591 name to see if the name of the new link starts with a
    592 rtems_filesystem_is_separator. If it does the search starts from the root of
    593 the RTEMS filesystem; otherwise the search will start from the current
    594 directory.
    595 
    596 The OPS table evalformake() function for the parent's filesystem is used to
    597 locate the node that will be the parent of the new link. It will also locate
    598 the start of the new path's name. This name will be used to define a child
    599 under the parent directory.
    600 
    601 If the parent is found, the routine will determine if the hard link that we are
    602 trying to create will cross a filesystem boundary. This is not permitted for
    603 hard-links.
    604 
    605 If the hard-link does not cross a filesystem boundary, a check is performed to
    606 determine if the OPS table contains an entry for the link() function.
    607 
    608 If a link() function is defined, the OPS table link() function will be called
    609 to establish the actual link within the filesystem.
    610 
    611 The return code from the OPS table link() function is returned to the calling
    612 program.
     542File:
     543    ``link.c``
     544
     545Processing:
     546    This routine will establish a hard link to a file, directory or a device.
     547    The target of the hard link must be in the same filesystem as the new link
     548    being created. A link to an existing link is also permitted but the
     549    existing link is evaluated before the new link is made. This implies that
     550    links to links are reduced to links to files, directories or devices before
     551    they are made.
     552
     553Development Comments:
     554    Calling parameters:
     555
     556    .. code-block:: c
     557
     558        const char   *existing
     559        const char   *new
     560
     561    link() will determine if the target of the link actually exists using
     562    rtems_filesystem_evaluate_path()
     563
     564    rtems_filesystem_get_start_loc() is used to determine where to start the
     565    path evaluation of the new name. This macro examines the first characters
     566    of the name to see if the name of the new link starts with a
     567    rtems_filesystem_is_separator. If it does the search starts from the root
     568    of the RTEMS filesystem; otherwise the search will start from the current
     569    directory.
     570
     571    The OPS table evalformake() function for the parent's filesystem is used to
     572    locate the node that will be the parent of the new link. It will also
     573    locate the start of the new path's name. This name will be used to define a
     574    child under the parent directory.
     575
     576    If the parent is found, the routine will determine if the hard link that we
     577    are trying to create will cross a filesystem boundary. This is not
     578    permitted for hard-links.
     579
     580    If the hard-link does not cross a filesystem boundary, a check is performed
     581    to determine if the OPS table contains an entry for the link() function.
     582
     583    If a link() function is defined, the OPS table link() function will be
     584    called to establish the actual link within the filesystem.
     585
     586    The return code from the OPS table link() function is returned to the
     587    calling program.
    613588
    614589lseek
    615590=====
    616591
    617 **File:**
    618 
    619 lseek.c
    620 
    621 **Processing:**
    622 
    623 This routine is layered on both external handlers and filesystem / node type
    624 specific handlers. This routine should allow for the support of new filesystems
    625 without modification.
    626 
    627 **Development Comments:**
    628 
    629 This routine will determine if the file descriptor is associated with a network
    630 device. If it is lseek will map to an external network handler.  The handler
    631 will be called with the file descriptor, offset and whence as its calling
    632 parameters. The return code from the external handler will be returned to the
    633 calling routine.
    634 
    635 If the file descriptor is not associated with a network connection, it is
    636 associated with a node in a filesystem. The following steps will be performed
    637 for filesystem nodes:
    638 
    639 # The file descriptor is used to obtain the file control block for the node.
    640 
    641 # The file descriptor is range checked.
    642 
    643 # The offset element of the file control block is altered as indicated by the
    644   offset and whence calling parameters
    645 
    646 # The handler table in the file control block is examined to determine if it
    647   contains an entry for the lseek() function. If it does not an error is
    648   returned to the calling program.
    649 
    650 # The lseek() function from the designated handler table is called with the
    651   file control block, offset and whence as calling arguments
    652 
    653 # The return code from the lseek() handler function is returned to the calling
    654   program
     592File:
     593    ``lseek.c``
     594
     595Processing:
     596    This routine is layered on both external handlers and filesystem / node
     597    type specific handlers. This routine should allow for the support of new
     598    filesystems without modification.
     599
     600Development Comments:
     601    This routine will determine if the file descriptor is associated with a
     602    network device. If it is lseek will map to an external network handler.
     603    The handler will be called with the file descriptor, offset and whence as
     604    its calling parameters. The return code from the external handler will be
     605    returned to the calling routine.
     606
     607    If the file descriptor is not associated with a network connection, it is
     608    associated with a node in a filesystem. The following steps will be
     609    performed for filesystem nodes:
     610
     611    #. The file descriptor is used to obtain the file control block for the
     612       node.
     613
     614    #. The file descriptor is range checked.
     615
     616    #. The offset element of the file control block is altered as indicated by
     617       the offset and whence calling parameters
     618
     619    #. The handler table in the file control block is examined to determine if
     620       it contains an entry for the lseek() function. If it does not an error
     621       is returned to the calling program.
     622
     623    #. The lseek() function from the designated handler table is called with
     624       the file control block, offset and whence as calling arguments
     625
     626    #. The return code from the lseek() handler function is returned to the
     627       calling program
    655628
    656629mkdir
    657630=====
    658631
    659 **File:**
    660 
    661 mkdir.c
    662 
    663 **Processing:**
    664 
    665 This routine attempts to create a directory node under the filesystem. The
    666 routine is layered the mknod() function.
    667 
    668 **Development Comments:**
    669 
    670 See mknod() for developmental comments.
     632File:
     633    ``mkdir.c``
     634
     635Processing:
     636    This routine attempts to create a directory node under the filesystem. The
     637    routine is layered the mknod() function.
     638
     639Development Comments:
     640    See mknod() for developmental comments.
    671641
    672642mkfifo
    673643======
    674644
    675 **File:**
    676 
    677 mkfifo.c
    678 
    679 **Processing:**
    680 
    681 This routine attempts to create a FIFO node under the filesystem. The routine
    682 is layered the mknod() function.
    683 
    684 **Development Comments:**
    685 
    686 See mknod() for developmental comments
     645File:
     646    ``mkfifo.c``
     647
     648Processing:
     649    This routine attempts to create a FIFO node under the filesystem. The
     650    routine is layered the mknod() function.
     651
     652Development Comments:
     653    See mknod() for developmental comments
    687654
    688655.. COMMENT: @page
     
    691658=====
    692659
    693 **File:**
    694 
    695 mknod.c
    696 
    697 **Processing:**
    698 
    699 This function will allow for the creation of the following types of nodes under
    700 the filesystem:
    701 
    702 - directories
    703 
    704 - regular files
    705 
    706 - character devices
    707 
    708 - block devices
    709 
    710 - fifos
    711 
    712 At the present time, an attempt to create a FIFO will result in an ENOTSUP
    713 error to the calling function. This routine is layered the filesystem specific
    714 routines evalformake and mknod. The introduction of a new filesystem must
    715 include its own evalformake and mknod function to support the generic mknod()
    716 function.  Under this condition the generic mknod() function should accommodate
    717 other filesystem types without alteration.
    718 
    719 **Development Comments:**
    720 
    721 Test for nodal types - I thought that this test should look like the following
    722 code:
    723 
    724 .. code-block:: c
    725 
    726     if ( (mode & S_IFDIR) = = S_IFDIR) ||
    727          (mode & S_IFREG) = = S_IFREG) ||
    728          (mode & S_IFCHR) = = S_IFCHR) ||
    729          (mode & S_IFBLK) = = S_IFBLK) ||
    730          (mode & S_IFIFO) = = S_IFIFO))
    731             Set_errno_and_return_minus_one (EINVAL);
    732 
    733 Where:
    734 
    735 - S_IFREG (0100000) - Creation of a regular file
    736 
    737 - S_IFCHR (0020000) - Creation of a character device
    738 
    739 - S_IFBLK (0060000) - Creation of a block device
    740 
    741 - S_IFIFO (0010000) - Creation of a FIFO
    742 
    743 Determine if the pathname that we are trying to create starts at the root
    744 directory or is relative to the current directory using the
    745 ``rtems_filesystem_get_start_loc()`` function.
    746 
    747 Determine if the pathname leads to a valid directory that can be accessed for
    748 the creation of a node.
    749 
    750 If the pathname is a valid location to create a node, verify that a filesystem
    751 specific mknod() function exists.
    752 
    753 If the mknod() function exists, call the filesystem specific mknod() function.
    754 Pass the name, mode, device type and the location information associated with
    755 the directory under which the node will be created.
     660File:
     661    ``mknod.c``
     662
     663Processing:
     664    This function will allow for the creation of the following types of nodes
     665    under the filesystem:
     666
     667    - directories
     668
     669    - regular files
     670
     671    - character devices
     672
     673    - block devices
     674
     675    - fifos
     676
     677    At the present time, an attempt to create a FIFO will result in an ENOTSUP
     678    error to the calling function. This routine is layered the filesystem
     679    specific routines evalformake and mknod. The introduction of a new
     680    filesystem must include its own evalformake and mknod function to support
     681    the generic mknod() function.  Under this condition the generic mknod()
     682    function should accommodate other filesystem types without alteration.
     683
     684Development Comments:
     685    Test for nodal types - I thought that this test should look like the
     686    following code:
     687
     688    .. code-block:: c
     689
     690        if ( (mode & S_IFDIR) = = S_IFDIR) ||
     691             (mode & S_IFREG) = = S_IFREG) ||
     692             (mode & S_IFCHR) = = S_IFCHR) ||
     693             (mode & S_IFBLK) = = S_IFBLK) ||
     694             (mode & S_IFIFO) = = S_IFIFO))
     695                Set_errno_and_return_minus_one (EINVAL);
     696
     697    Where:
     698
     699    - S_IFREG (0100000) - Creation of a regular file
     700
     701    - S_IFCHR (0020000) - Creation of a character device
     702
     703    - S_IFBLK (0060000) - Creation of a block device
     704
     705    - S_IFIFO (0010000) - Creation of a FIFO
     706
     707    Determine if the pathname that we are trying to create starts at the root
     708    directory or is relative to the current directory using the
     709    ``rtems_filesystem_get_start_loc()`` function.
     710
     711    Determine if the pathname leads to a valid directory that can be accessed
     712    for the creation of a node.
     713
     714    If the pathname is a valid location to create a node, verify that a
     715    filesystem specific mknod() function exists.
     716
     717    If the mknod() function exists, call the filesystem specific mknod()
     718    function.  Pass the name, mode, device type and the location information
     719    associated with the directory under which the node will be created.
    756720
    757721mount
    758722=====
    759723
    760 **File:**
    761 
    762 mount.c
    763 
    764 Arguments (Not a standard POSIX call):
    765 
    766 .. code-block:: c
    767 
    768     rtems_filesystem_mount_table_entry_t   **mt_entry,
    769 
    770 If the mount operation is successful, this pointer to a pointer will be set to
    771 reference the mount table chain entry that has been allocated for this file
    772 system mount.
    773 
    774 .. code-block:: c
    775 
    776     rtems_filesystem_operations_table   *fs_ops,
    777 
    778 This is a pointer to a table of functions that are associated with the file
    779 system that we are about to mount. This is the mechanism to selected file
    780 system type without keeping a dynamic database of all possible file system
    781 types that are valid for the mount operation. Using this method, it is only
    782 necessary to configure the filesystems that we wish to use into the RTEMS
    783 build. Unused filesystems types will not be drawn into the build.
    784 
    785 .. code-block:: c
    786 
    787     char                      *fsoptions,
    788 
    789 This argument points to a string that selects mounting for read only
    790 access or read/write access. Valid states are "RO" and "RW"
    791 
    792 .. code-block:: c
    793 
    794     char                      *device,
    795 
    796 This argument is reserved for the name of a device that will be used to access
    797 the filesystem information. Current filesystem implementations are memory based
    798 and do not require a device to access filesystem information.
    799 
    800 .. code-block:: c
    801 
    802     char                      *mount_point
    803 
    804 This is a pathname to a directory in a currently mounted filesystem that allows
    805 read, write and execute permissions.  If successful, the node found by
    806 evaluating this name, is stored in the mt_entry.
    807 
    808 **Processing:**
    809 
    810 This routine will handle the mounting of a filesystem on a mount point. If the
    811 operation is successful, a pointer to the mount table chain entry associated
    812 with the mounted filesystem will be returned to the calling function. The
    813 specifics about the processing required at the mount point and within the
    814 filesystem being mounted is isolated in the filesystem specific mount() and
    815 fsmount_me() functions. This allows the generic mount() function to remain
    816 unaltered even if new filesystem types are introduced.
    817 
    818 **Development Comments:**
    819 
    820 This routine will use get_file_system_options() to determine if the mount
    821 options are valid ("RO" or "RW").
    822 
    823 It confirms that a filesystem ops-table has been selected.
    824 
    825 Space is allocated for a mount table entry and selective elements of the
    826 temporary mount table entry are initialized.
    827 
    828 If a mount point is specified: The mount point is examined to determine that it
    829 is a directory and also has the appropriate permissions to allow a filesystem
    830 to be mounted.
    831 
    832 The current mount table chain is searched to determine that there is not
    833 another filesystem mounted at the mount point we are trying to mount onto.
    834 
    835 If a mount function is defined in the ops table for the filesystem containing
    836 the mount point, it is called at this time.
    837 
    838 If no mount point is specified: Processing if performed to set up the mount
    839 table chain entry as the base filesystem.
    840 
    841 If the fsmount_me() function is specified for ops-table of the filesystem being
    842 mounted, that function is called to initialize for the new filesystem.
    843 
    844 On successful completion, the temporary mount table entry will be placed on the
    845 mount table chain to record the presence of the mounted filesystem.
     724File:
     725    ``mount.c``
     726
     727    Arguments (Not a standard POSIX call):
     728
     729    .. code-block:: c
     730
     731        rtems_filesystem_mount_table_entry_t   **mt_entry,
     732
     733    If the mount operation is successful, this pointer to a pointer will be set
     734    to reference the mount table chain entry that has been allocated for this
     735    file system mount.
     736
     737    .. code-block:: c
     738
     739        rtems_filesystem_operations_table   *fs_ops,
     740
     741    This is a pointer to a table of functions that are associated with the file
     742    system that we are about to mount. This is the mechanism to selected file
     743    system type without keeping a dynamic database of all possible file system
     744    types that are valid for the mount operation. Using this method, it is only
     745    necessary to configure the filesystems that we wish to use into the RTEMS
     746    build. Unused filesystems types will not be drawn into the build.
     747
     748    .. code-block:: c
     749
     750        char                      *fsoptions,
     751
     752    This argument points to a string that selects mounting for read only access
     753    or read/write access. Valid states are "RO" and "RW"
     754
     755    .. code-block:: c
     756
     757        char                      *device,
     758
     759    This argument is reserved for the name of a device that will be used to
     760    access the filesystem information. Current filesystem implementations are
     761    memory based and do not require a device to access filesystem information.
     762
     763    .. code-block:: c
     764
     765        char                      *mount_point
     766
     767    This is a pathname to a directory in a currently mounted filesystem that
     768    allows read, write and execute permissions.  If successful, the node found
     769    by evaluating this name, is stored in the mt_entry.
     770
     771Processing:
     772    This routine will handle the mounting of a filesystem on a mount point. If
     773    the operation is successful, a pointer to the mount table chain entry
     774    associated with the mounted filesystem will be returned to the calling
     775    function. The specifics about the processing required at the mount point
     776    and within the filesystem being mounted is isolated in the filesystem
     777    specific mount() and fsmount_me() functions. This allows the generic
     778    mount() function to remain unaltered even if new filesystem types are
     779    introduced.
     780
     781Development Comments:
     782    This routine will use get_file_system_options() to determine if the mount
     783    options are valid ("RO" or "RW").
     784
     785    It confirms that a filesystem ops-table has been selected.
     786
     787    Space is allocated for a mount table entry and selective elements of the
     788    temporary mount table entry are initialized.
     789
     790    If a mount point is specified: The mount point is examined to determine
     791    that it is a directory and also has the appropriate permissions to allow a
     792    filesystem to be mounted.
     793
     794    The current mount table chain is searched to determine that there is not
     795    another filesystem mounted at the mount point we are trying to mount onto.
     796
     797    If a mount function is defined in the ops table for the filesystem
     798    containing the mount point, it is called at this time.
     799
     800    If no mount point is specified: Processing if performed to set up the mount
     801    table chain entry as the base filesystem.
     802
     803    If the fsmount_me() function is specified for ops-table of the filesystem
     804    being mounted, that function is called to initialize for the new
     805    filesystem.
     806
     807    On successful completion, the temporary mount table entry will be placed on
     808    the mount table chain to record the presence of the mounted filesystem.
    846809
    847810open
    848811====
    849812
    850 **File:**
    851 
    852 open.c
    853 
    854 **Processing:**
    855 
    856 This routine is layered on both RTEMS calls and filesystem specific
    857 implementations of the open() function. These functional interfaces should not
    858 change for new filesystems and therefore this code should be stable as new file
    859 systems are introduced.
    860 
    861 **Development Comments:**
    862 
    863 This routine will allocate a file control block for the file or device that we
    864 are about to open.
    865 
    866 It will then test to see if the pathname exists. If it does a
    867 rtems_filesystem_location_info_t data structure will be filled out. This
    868 structure contains information that associates node information, filesystem
    869 specific functions and mount table chain information with the pathname.
    870 
    871 If the create option has been it will attempt to create a node for a regular
    872 file along the specified path. If a file already exists along this path, an
    873 error will be generated; otherwise, a node will be allocated for the file under
    874 the filesystem that contains the pathname. When a new node is created, it is
    875 also evaluated so that an appropriate rtems_filesystem_location_info_t data
    876 structure can be filled out for the newly created node.
    877 
    878 If the file exists or the new file was created successfully, the file control
    879 block structure will be initialized with handler table information, node
    880 information and the rtems_filesystem_location_info_t data structure that
    881 describes the node and filesystem data in detail.
    882 
    883 If an open() function exists in the filesystem specific handlers table for the
    884 node that we are trying to open, it will be called at this time.
    885 
    886 If any error is detected in the process, cleanup is performed. It consists of
    887 freeing the file control block structure that was allocated at the beginning of
    888 the generic open() routine.
    889 
    890 On a successful open(), the index into the file descriptor table will be
    891 calculated and returned to the calling routine.
     813File:
     814    ``open.c``
     815
     816Processing:
     817    This routine is layered on both RTEMS calls and filesystem specific
     818    implementations of the open() function. These functional interfaces should
     819    not change for new filesystems and therefore this code should be stable as
     820    new file systems are introduced.
     821
     822Development Comments:
     823    This routine will allocate a file control block for the file or device that
     824    we are about to open.
     825
     826    It will then test to see if the pathname exists. If it does a
     827    rtems_filesystem_location_info_t data structure will be filled out. This
     828    structure contains information that associates node information, filesystem
     829    specific functions and mount table chain information with the pathname.
     830
     831    If the create option has been it will attempt to create a node for a
     832    regular file along the specified path. If a file already exists along this
     833    path, an error will be generated; otherwise, a node will be allocated for
     834    the file under the filesystem that contains the pathname. When a new node
     835    is created, it is also evaluated so that an appropriate
     836    rtems_filesystem_location_info_t data structure can be filled out for the
     837    newly created node.
     838
     839    If the file exists or the new file was created successfully, the file
     840    control block structure will be initialized with handler table information,
     841    node information and the rtems_filesystem_location_info_t data structure
     842    that describes the node and filesystem data in detail.
     843
     844    If an open() function exists in the filesystem specific handlers table for
     845    the node that we are trying to open, it will be called at this time.
     846
     847    If any error is detected in the process, cleanup is performed. It consists
     848    of freeing the file control block structure that was allocated at the
     849    beginning of the generic open() routine.
     850
     851    On a successful open(), the index into the file descriptor table will be
     852    calculated and returned to the calling routine.
    892853
    893854opendir
    894855=======
    895856
    896 **File:**
    897 
    898 opendir.c
    899 
    900 **Processing:**
    901 
    902 This routine will attempt to open a directory for read access. It will setup a
    903 DIR control structure that will be used to access directory information. This
    904 routine is layered on the generic open() routine and filesystem specific
    905 directory processing routines.
    906 
    907 **Development Comments:**
    908 
    909 The BSD group provided this routine.
     857File:
     858    ``opendir.c``
     859
     860Processing:
     861    This routine will attempt to open a directory for read access. It will
     862    setup a DIR control structure that will be used to access directory
     863    information. This routine is layered on the generic open() routine and
     864    filesystem specific directory processing routines.
     865
     866Development Comments:
     867    The BSD group provided this routine.
    910868
    911869pathconf
    912870========
    913871
    914 **File:**
    915 
    916 pathconf.c
    917 
    918 **Processing:**
    919 
    920 This routine will obtain the value of one of the path configuration parameters
    921 and return it to the calling routine. It is layered on the generic open() and
    922 fpathconf() functions. These interfaces should not change with the addition of
    923 new filesystem types.
    924 
    925 **Development Comments:**
    926 
    927 This routine will try to open the file indicated by path.
    928 
    929 If successful, the file descriptor will be used to access the pathconf value
    930 specified by ``name`` using the fpathconf() function.
    931 
    932 The file that was accessed is then closed.
     872File:
     873    ``pathconf.c``
     874
     875Processing:
     876    This routine will obtain the value of one of the path configuration
     877    parameters and return it to the calling routine. It is layered on the
     878    generic open() and fpathconf() functions. These interfaces should not
     879    change with the addition of new filesystem types.
     880
     881Development Comments:
     882    This routine will try to open the file indicated by path.
     883
     884    If successful, the file descriptor will be used to access the pathconf
     885    value specified by ``name`` using the fpathconf() function.
     886
     887    The file that was accessed is then closed.
    933888
    934889read
    935890====
    936891
    937 **File:**
    938 
    939 deviceio.c
    940 
    941 **Processing:**
    942 
    943 This routine is layered on a set of RTEMS calls and filesystem specific read
    944 operations. The functions are layered in such a way as to isolate them from
    945 change as new filesystems are introduced.
    946 
    947 **Development Comments:**
    948 
    949 This routine will examine the type of file descriptor it is sent.
    950 
    951 If the file descriptor is associated with a network device, the read function
    952 will be mapped to a special network handler. The return code from the network
    953 handler will then be sent as the return code from generic read() function.
    954 
    955 For file descriptors that are associated with the filesystem the following
    956 sequence will be performed:
    957 
    958 # Obtain the file control block associated with the file descriptor
    959 
    960 # Range check the file descriptor
    961 
    962 # Determine that the buffer pointer is not invalid
    963 
    964 # Check that the count is not zero
    965 
    966 # Check the file control block to see if we have permissions to read
    967 
    968 # If there is a read function in the handler table, invoke the handler table
    969   read() function
    970 
    971 # Use the return code from the handler table read function(number of bytes
    972   read) to increment the offset element of the file control block
    973 
    974 # Return the number of bytes read to the calling program
     892File:
     893    ``deviceio.c``
     894
     895Processing:
     896    This routine is layered on a set of RTEMS calls and filesystem specific
     897    read operations. The functions are layered in such a way as to isolate them
     898    from change as new filesystems are introduced.
     899
     900Development Comments:
     901    This routine will examine the type of file descriptor it is sent.
     902
     903    If the file descriptor is associated with a network device, the read
     904    function will be mapped to a special network handler. The return code from
     905    the network handler will then be sent as the return code from generic
     906    read() function.
     907
     908    For file descriptors that are associated with the filesystem the following
     909    sequence will be performed:
     910
     911    #. Obtain the file control block associated with the file descriptor
     912
     913    #. Range check the file descriptor
     914
     915    #. Determine that the buffer pointer is not invalid
     916
     917    #. Check that the count is not zero
     918
     919    #. Check the file control block to see if we have permissions to read
     920
     921    #. If there is a read function in the handler table, invoke the handler
     922       table read() function
     923
     924    #. Use the return code from the handler table read function(number of bytes
     925       read) to increment the offset element of the file control block
     926
     927    #. Return the number of bytes read to the calling program
    975928
    976929readdir
    977930=======
    978931
    979 **File:**
    980 
    981 readdir.c
    982 
    983 **Processing:**
    984 
    985 This routine was acquired from the BSD group. It has not been altered from its
    986 original form.
    987 
    988 **Development Comments:**
    989 
    990 The routine calls a customized getdents() function that is provided by the
    991 user.  This routine provides the filesystem specific aspects of reading a
    992 directory.
    993 
    994 It is layered on the read() function in the directory handler table. This
    995 function has been mapped to the Imfs_dir_read() function.
     932File:
     933    ``readdir.c``
     934
     935Processing:
     936    This routine was acquired from the BSD group. It has not been altered from
     937    its original form.
     938
     939Development Comments:
     940    The routine calls a customized getdents() function that is provided by the
     941    user.  This routine provides the filesystem specific aspects of reading a
     942    directory.
     943
     944    It is layered on the read() function in the directory handler table. This
     945    function has been mapped to the Imfs_dir_read() function.
    996946
    997947unmount
    998948=======
    999949
    1000 **File:**
    1001 
    1002 unmount.c
    1003 
    1004 **Processing:**
    1005 
    1006 This routine will attempt to dismount a mounted filesystem and then free all
    1007 resources that were allocated for the management of that filesystem.
    1008 
    1009 **Development Comments:**
    1010 
    1011 - This routine will determine if there are any filesystems currently mounted
    1012   under the filesystem that we are trying to dismount. This would prevent the
    1013   dismount of the filesystem.
    1014 
    1015 - It will test to see if the current directory is in the filesystem that we are
    1016   attempting to dismount. This would prevent the dismount of the filesystem.
    1017 
    1018 - It will scan all the currently open file descriptors to determine is there is
    1019   an open file descriptor to a file in the filesystem that we are attempting to
    1020   unmount().
    1021 
    1022 If the above preconditions are met then the following sequence is performed:
    1023 
    1024 # Call the filesystem specific unmount() function for the filesystem that
    1025   contains the mount point. This routine should indicate that the mount point
    1026   no longer has a filesystem mounted below it.
    1027 
    1028 # Call the filesystem specific fsunmount_me() function for the mounted
    1029   filesystem that we are trying to unmount(). This routine should clean up any
    1030   resources that are no longer needed for the management of the file system
    1031   being un-mounted.
    1032 
    1033 # Extract the mount table entry for the filesystem that was just dismounted
    1034   from the mount table chain.
    1035 
    1036 # Free the memory associated with the extracted mount table entry.
     950File:
     951    ``unmount.c``
     952
     953Processing:
     954    This routine will attempt to dismount a mounted filesystem and then free
     955    all resources that were allocated for the management of that filesystem.
     956
     957Development Comments:
     958    - This routine will determine if there are any filesystems currently
     959      mounted under the filesystem that we are trying to dismount. This would
     960      prevent the dismount of the filesystem.
     961
     962    - It will test to see if the current directory is in the filesystem that we
     963      are attempting to dismount. This would prevent the dismount of the
     964      filesystem.
     965
     966    - It will scan all the currently open file descriptors to determine is
     967      there is an open file descriptor to a file in the filesystem that we are
     968      attempting to unmount().
     969
     970    If the above preconditions are met then the following sequence is
     971    performed:
     972
     973    #. Call the filesystem specific unmount() function for the filesystem that
     974       contains the mount point. This routine should indicate that the mount
     975       point no longer has a filesystem mounted below it.
     976
     977    #. Call the filesystem specific fsunmount_me() function for the mounted
     978       filesystem that we are trying to unmount(). This routine should clean up
     979       any resources that are no longer needed for the management of the file
     980       system being un-mounted.
     981
     982    #. Extract the mount table entry for the filesystem that was just dismounted
     983       from the mount table chain.
     984
     985    #. Free the memory associated with the extracted mount table entry.
    1037986
    1038987eval
    1039988====
    1040989
    1041 **File:**
    1042 
    1043 XXX
    1044 
    1045 **Processing:**
    1046 
    1047 XXX
    1048 
    1049 **Development Comments:**
    1050 
    1051 XXX
     990File:
     991    ``XXX``
     992
     993Processing:
     994    XXX
     995
     996Development Comments:
     997    XXX
    1052998
    1053999getdentsc
    10541000=========
    10551001
    1056 **File:**
    1057 
    1058 XXX
    1059 
    1060 **Processing:**
    1061 
    1062 XXX
    1063 
    1064 **Development Comments:**
    1065 
    1066 XXX
     1002File:
     1003    ``XXX``
     1004
     1005Processing:
     1006    XXX
     1007
     1008Development Comments:
     1009    XXX
  • filesystem/command_and_variable.rst

    rf7dbf17 r5431beb  
    22
    33Command and Variable Index
    4 ##########################
     4**************************
    55
    66There are currently no Command and Variable Index entries.
  • filesystem/conf.py

    rf7dbf17 r5431beb  
    44from conf import *
    55
    6 version = '1.0'
    7 release = '5.0'
     6version = '4.11.0'
     7release = '4.11.0'
     8
     9project = "RTEMS Filesystem Design Guide"
    810
    911latex_documents = [
    10         ('index', 'filesystem.tex', u'RTEMS Filesystem', u'RTEMS Documentation Project', 'manual'),
     12        ('index', 'filesystem.tex', u'RTEMS Filesystem Design Guide', u'RTEMS Filesystem Design Guide', 'manual'),
    1113]
  • filesystem/fileystem_implmentation.rst

    rf7dbf17 r5431beb  
    66
    77Filesystem Implementation Requirements
    8 ######################################
     8**************************************
    99
    1010This chapter details the behavioral requirements that all filesystem
     
    106106application:
    107107
    108 # access()
    109 
    110 # chdir()
    111 
    112 # chmod()
    113 
    114 # chown()
    115 
    116 # close()
    117 
    118 # closedir()
    119 
    120 # fchmod()
    121 
    122 # fcntl()
    123 
    124 # fdatasync()
    125 
    126 # fpathconf()
    127 
    128 # fstat()
    129 
    130 # fsync()
    131 
    132 # ftruncate()
    133 
    134 # link()
    135 
    136 # lseek()
    137 
    138 # mkdir()
    139 
    140 # mknod()
    141 
    142 # mount()
    143 
    144 # open()
    145 
    146 # opendir()
    147 
    148 # pathconf()
    149 
    150 # read()
    151 
    152 # readdir()
    153 
    154 # rewinddir()
    155 
    156 # rmdir()
    157 
    158 # rmnod()
    159 
    160 # scandir()
    161 
    162 # seekdir()
    163 
    164 # stat()
    165 
    166 # telldir()
    167 
    168 # umask()
    169 
    170 # unlink()
    171 
    172 # unmount()
    173 
    174 # utime()
    175 
    176 # write()
     108#. access()
     109
     110#. chdir()
     111
     112#. chmod()
     113
     114#. chown()
     115
     116#. close()
     117
     118#. closedir()
     119
     120#. fchmod()
     121
     122#. fcntl()
     123
     124#. fdatasync()
     125
     126#. fpathconf()
     127
     128#. fstat()
     129
     130#. fsync()
     131
     132#. ftruncate()
     133
     134#. link()
     135
     136#. lseek()
     137
     138#. mkdir()
     139
     140#. mknod()
     141
     142#. mount()
     143
     144#. open()
     145
     146#. opendir()
     147
     148#. pathconf()
     149
     150#. read()
     151
     152#. readdir()
     153
     154#. rewinddir()
     155
     156#. rmdir()
     157
     158#. rmnod()
     159
     160#. scandir()
     161
     162#. seekdir()
     163
     164#. stat()
     165
     166#. telldir()
     167
     168#. umask()
     169
     170#. unlink()
     171
     172#. unmount()
     173
     174#. utime()
     175
     176#. write()
    177177
    178178The filesystem's type as well as the node type within the filesystem determine
     
    197197the relationship between and among the following components.
    198198
    199 # File Descriptor Table
     199File Descriptor Table:
    200200  This is an internal RTEMS structure that tracks all currently defined file
    201201  descriptors in the system. The index that is returned by the file open()
     
    204204  represents the file control block.
    205205
    206 # Allocation of entry in the File Descriptor Table
     206Allocation of entry in the File Descriptor Table:
    207207  Access to the file descriptor table is controlled through a semaphore that is
    208208  implemented using the rtems_libio_allocate() function. This routine will grab
     
    213213  released to allow further operations on the table.
    214214
    215 # Maximum number of entries in the file descriptor table is configurable
     215  Maximum number of entries in the file descriptor table is configurable
    216216  through the src/exec/sapi/headers/confdefs.h file. If the
    217   CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value will
    218   represent the maximum number of file descriptors that are allowed.  If
    219   CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default value of
    220   20 will be used as the maximum number of file descriptors allowed.
    221 
    222 # File control block - rtems_libio_t structure
    223 
     217  ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` constant is defined its value
     218  will represent the maximum number of file descriptors that are allowed.  If
     219  ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` is not specified a default value
     220  of 20 will be used as the maximum number of file descriptors allowed.
     221
     222File control block - rtems_libio_t structure:
    224223  .. code-block:: c
    225224
     
    259258-----------------------------------------------------------------------------
    260259
    261 The rtems_filesystem_location_info_tt structure below provides sufficient
     260The ``rtems_filesystem_location_info_tt`` structure below provides sufficient
    262261information to process nodes under a mounted filesystem.
    263262
     
    317316
    318317evalpath Handler
    319 ~~~~~~~~~~~~~~~~
    320 
    321 **Corresponding Structure Element:**
    322 
    323 evalpath
    324 
    325 **Arguments:**
    326 
    327 .. code-block:: c
    328 
    329     const char                        *pathname,      /* IN     */
    330     int                                flags,         /* IN     */
    331     rtems_filesystem_location_info_t  *pathloc        /* IN/OUT */
    332 
    333 **Description:**
    334 
    335 This routine is responsible for evaluating the pathname passed in based upon
    336 the flags and the valid ``rthems_filesystem_location_info_t``.  Additionally,
    337 it must make any changes to pathloc necessary to identify the pathname node.
    338 This should include calling the evalpath for a mounted filesystem, if the given
    339 filesystem supports the mount command.
    340 
    341 This routine returns a 0 if the evaluation was successful.  Otherwise, it
    342 returns a -1 and sets errno to the correct error.
    343 
    344 This routine is required and should NOT be set to NULL.
     318^^^^^^^^^^^^^^^^
     319
     320Corresponding Structure Element:
     321    ``evalpath``
     322
     323Arguments:
     324    .. code-block:: c
     325
     326        const char                        *pathname,      /* IN     */
     327        int                                flags,         /* IN     */
     328        rtems_filesystem_location_info_t  *pathloc        /* IN/OUT */
     329
     330Description:
     331    This routine is responsible for evaluating the pathname passed in based
     332    upon the flags and the valid ``rthems_filesystem_location_info_t``.
     333    Additionally, it must make any changes to pathloc necessary to identify the
     334    pathname node.  This should include calling the evalpath for a mounted
     335    filesystem, if the given filesystem supports the mount command.
     336
     337    This routine returns a 0 if the evaluation was successful.  Otherwise, it
     338    returns a -1 and sets errno to the correct error.
     339
     340    This routine is required and should NOT be set to NULL.
    345341
    346342evalformake Handler
    347 ~~~~~~~~~~~~~~~~~~~
    348 
    349 **Corresponding Structure Element:**
    350 
    351 evalformake
    352 
    353 **Arguments:**
    354 
    355 .. code-block:: c
    356 
    357     const char                       *path,       /* IN */
    358     rtems_filesystem_location_info_t *pathloc,    /* IN/OUT */
    359     const char                      **name        /* OUT */
    360 
    361 **Description:**
    362 
    363 This method is given a path to evaluate and a valid start location.  It is
    364 responsible for finding the parent node for a requested make command, setting
    365 pathloc information to identify the parent node, and setting the name pointer
    366 to the first character of the name of the new node.  Additionally, if the
    367 filesystem supports the mount command, this method should call the evalformake
    368 routine for the mounted filesystem.
    369 
    370 This routine returns a 0 if the evaluation was successful.  Otherwise, it
    371 returns a -1 and sets errno to the correct error.
    372 
    373 This routine is required and should NOT be set to NULL.  However, if the
    374 filesystem does not support user creation of a new node, it may set errno to
    375 ENOSYS and return -1.
     343^^^^^^^^^^^^^^^^^^^
     344
     345Corresponding Structure Element:
     346    ``evalformake``
     347
     348Arguments:
     349    .. code-block:: c
     350
     351        const char                       *path,       /* IN */
     352        rtems_filesystem_location_info_t *pathloc,    /* IN/OUT */
     353        const char                      **name        /* OUT */
     354
     355Description:
     356    This method is given a path to evaluate and a valid start location.  It is
     357    responsible for finding the parent node for a requested make command,
     358    setting pathloc information to identify the parent node, and setting the
     359    name pointer to the first character of the name of the new node.
     360    Additionally, if the filesystem supports the mount command, this method
     361    should call the evalformake routine for the mounted filesystem.
     362
     363    This routine returns a 0 if the evaluation was successful.  Otherwise, it
     364    returns a -1 and sets errno to the correct error.
     365
     366    This routine is required and should NOT be set to NULL.  However, if the
     367    filesystem does not support user creation of a new node, it may set errno
     368    to ENOSYS and return -1.
    376369
    377370link Handler
    378 ~~~~~~~~~~~~
    379 
    380 **Corresponding Structure Element:**
    381 
    382 link
    383 
    384 **Arguments:**
    385 
    386 .. code-block:: c
    387 
    388     rtems_filesystem_location_info_t    *to_loc,      /* IN */
    389     rtems_filesystem_location_info_t    *parent_loc,  /* IN */
    390     const char                          *token        /* IN */
    391 
    392 **Description:**
    393 
    394 This routine is used to create a hard-link.
    395 
    396 It will first examine the st_nlink count of the node that we are trying to.  If
    397 the link count exceeds LINK_MAX an error will be returned.
    398 
    399 The name of the link will be normalized to remove extraneous separators from
    400 the end of the name.
    401 
    402 This routine is not required and may be set to NULL.
     371^^^^^^^^^^^^
     372
     373Corresponding Structure Element:
     374    ``link``
     375
     376Arguments:
     377    .. code-block:: c
     378
     379        rtems_filesystem_location_info_t    *to_loc,      /* IN */
     380        rtems_filesystem_location_info_t    *parent_loc,  /* IN */
     381        const char                          *token        /* IN */
     382
     383Description:
     384    This routine is used to create a hard-link.
     385
     386    It will first examine the st_nlink count of the node that we are trying to.
     387    If the link count exceeds LINK_MAX an error will be returned.
     388
     389    The name of the link will be normalized to remove extraneous separators
     390    from the end of the name.
     391
     392    This routine is not required and may be set to NULL.
    403393
    404394unlink Handler
    405 ~~~~~~~~~~~~~~
    406 
    407 **Corresponding Structure Element:**
    408 
    409 XXX
    410 
    411 **Arguments:**
    412 
    413 XXX
    414 
    415 **Description:**
    416 
    417 XXX
     395^^^^^^^^^^^^^^
     396
     397Corresponding Structure Element:
     398    ``unlink``
     399
     400Arguments:
     401    XXX
     402
     403Description:
     404    XXX
    418405
    419406node_type Handler
    420 ~~~~~~~~~~~~~~~~~
    421 
    422 **Corresponding Structure Element:**
    423 
    424 node_type()
    425 
    426 **Arguments:**
    427 
    428 .. code-block:: c
    429 
    430     rtems_filesystem_location_info_t    *pathloc        /* IN */
    431 
    432 **Description:**
    433 
    434 XXX
     407^^^^^^^^^^^^^^^^^
     408
     409Corresponding Structure Element:
     410    ``node_type()``
     411
     412Arguments:
     413    .. code-block:: c
     414
     415        rtems_filesystem_location_info_t    *pathloc        /* IN */
     416
     417Description:
     418    XXX
    435419
    436420mknod Handler
    437 ~~~~~~~~~~~~~
    438 
    439 **Corresponding Structure Element:**
    440 
    441 mknod()
    442 
    443 **Arguments:**
    444 
    445 .. code-block:: c
    446 
    447     const char                          *token,        /* IN */
    448     mode_t                               mode,         /* IN */
    449     dev_t                                dev,          /* IN */
    450     rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
    451 
    452 **Description:**
    453 
    454 XXX
     421^^^^^^^^^^^^^
     422
     423Corresponding Structure Element:
     424    ``mknod()``
     425
     426Arguments:
     427    .. code-block:: c
     428
     429        const char                          *token,        /* IN */
     430        mode_t                               mode,         /* IN */
     431        dev_t                                dev,          /* IN */
     432        rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
     433
     434Description:
     435    XXX
    455436
    456437rmnod Handler
    457 ~~~~~~~~~~~~~
    458 
    459 **Corresponding Structure Element:**
    460 
    461 XXX
    462 
    463 **Arguments:**
    464 
    465 XXX
    466 
    467 **Description:**
    468 
    469 XXX
     438^^^^^^^^^^^^^
     439
     440Corresponding Structure Element:
     441    ``rmnod()``
     442
     443Arguments:
     444    XXX
     445
     446Description:
     447    XXX
    470448
    471449chown Handler
    472 ~~~~~~~~~~~~~
    473 
    474 **Corresponding Structure Element:**
    475 
    476 chown()
    477 
    478 **Arguments:**
    479 
    480 .. code-block:: c
    481 
    482     rtems_filesystem_location_info_t    *pathloc        /* IN */
    483     uid_t                                owner          /* IN */
    484     gid_t                                group          /* IN */
    485 
    486 **Description:**
    487 
    488 XXX
    489 
    490 .. COMMENT: @page
     450^^^^^^^^^^^^^
     451
     452Corresponding Structure Element:
     453    ``chown()``
     454
     455Arguments:
     456    .. code-block:: c
     457
     458        rtems_filesystem_location_info_t    *pathloc        /* IN */
     459        uid_t                                owner          /* IN */
     460        gid_t                                group          /* IN */
     461
     462Description:
     463    XXX
    491464
    492465freenod Handler
    493 ~~~~~~~~~~~~~~~
    494 
    495 **Corresponding Structure Element:**
    496 
    497 freenod()
    498 
    499 **Arguments:**
    500 
    501 .. code-block:: c
    502 
    503     rtems_filesystem_location_info_t      *pathloc       /* IN */
    504 
    505 **Description:**
    506 
    507 This routine is used by the generic code to allow memory to be allocated during
    508 the evaluate routines, and set free when the generic code is finished accessing
    509 a node.  If the evaluate routines allocate memory to identify a node this
    510 routine should be utilized to free that memory.
    511 
    512 This routine is not required and may be set to NULL.
     466^^^^^^^^^^^^^^^
     467
     468Corresponding Structure Element:
     469    ``freenod()``
     470
     471Arguments:
     472    .. code-block:: c
     473
     474        rtems_filesystem_location_info_t      *pathloc       /* IN */
     475
     476Description:
     477    This routine is used by the generic code to allow memory to be allocated
     478    during the evaluate routines, and set free when the generic code is
     479    finished accessing a node.  If the evaluate routines allocate memory to
     480    identify a node this routine should be utilized to free that memory.
     481
     482    This routine is not required and may be set to NULL.
    513483
    514484mount Handler
    515 ~~~~~~~~~~~~~
    516 
    517 **Corresponding Structure Element:**
    518 
    519 mount()
    520 
    521 **Arguments:**
    522 
    523 .. code-block:: c
    524 
    525     rtems_filesystem_mount_table_entry_t   *mt_entry
    526 
    527 **Description:**
    528 
    529 XXX
     485^^^^^^^^^^^^^
     486
     487Corresponding Structure Element:
     488    ``mount()``
     489
     490Arguments:
     491    .. code-block:: c
     492
     493        rtems_filesystem_mount_table_entry_t   *mt_entry
     494
     495Description:
     496    XXX
    530497
    531498fsmount_me Handler
    532 ~~~~~~~~~~~~~~~~~~
    533 
    534 **Corresponding Structure Element:**
    535 
    536 XXX
    537 
    538 **Arguments:**
    539 
    540 .. code-block:: c
    541 
    542     rtems_filesystem_mount_table_entry_t   *mt_entry
    543 
    544 **Description:**
    545 
    546 This function is provided with a filesystem to take care of the internal
    547 filesystem management details associated with mounting that filesystem under
    548 the RTEMS environment.
    549 
    550 It is not responsible for the mounting details associated the filesystem
    551 containing the mount point.
    552 
    553 The rtems_filesystem_mount_table_entry_t structure contains the key elements
    554 below:
    555 
    556 .. code-block:: c
    557 
    558     rtems_filesystem_location_info_t         *mt_point_node,
    559 
    560 This structure contains information about the mount point. This
    561 allows us to find the ops-table and the handling functions
    562 associated with the filesystem containing the mount point.
    563 
    564 .. code-block:: c
    565 
    566     rtems_filesystem_location_info_t         *fs_root_node,
    567 
    568 This structure contains information about the root node in the file
    569 system to be mounted. It allows us to find the ops-table and the
    570 handling functions associated with the filesystem to be mounted.
    571 
    572 .. code-block:: c
     499^^^^^^^^^^^^^^^^^^
     500
     501Corresponding Structure Element:
     502    ``imfs_fsmount_me``
     503
     504Arguments:
     505    .. code-block:: c
     506
     507        rtems_filesystem_mount_table_entry_t   *mt_entry
     508
     509Description:
     510    This function is provided with a filesystem to take care of the internal
     511    filesystem management details associated with mounting that filesystem
     512    under the RTEMS environment.
     513
     514    It is not responsible for the mounting details associated the filesystem
     515    containing the mount point.
     516
     517    The rtems_filesystem_mount_table_entry_t structure contains the key
     518    elements below:
     519
     520    .. code-block:: c
     521
     522        rtems_filesystem_location_info_t         *mt_point_node,
     523
     524    This structure contains information about the mount point. This allows us
     525    to find the ops-table and the handling functions associated with the
     526    filesystem containing the mount point.
     527
     528    .. code-block:: c
     529
     530        rtems_filesystem_location_info_t         *fs_root_node,
     531
     532    This structure contains information about the root node in the file system
     533    to be mounted. It allows us to find the ops-table and the handling
     534    functions associated with the filesystem to be mounted.
     535
     536    .. code-block:: c
    573537
    574538    rtems_filesystem_options_t                 options,
    575539
    576 Read only or read/write access
    577 
    578 .. code-block:: c
    579 
    580     void                                         *fs_info,
    581 
    582 This points to an allocated block of memory the will be used to hold any
    583 filesystem specific information of a global nature. This allocated region if
    584 important because it allows us to mount the same filesystem type more than once
    585 under the RTEMS system.  Each instance of the mounted filesystem has its own
    586 set of global management information that is separate from the global
    587 management information associated with the other instances of the mounted
    588 filesystem type.
    589 
    590 .. code-block:: c
    591 
    592     rtems_filesystem_limits_and_options_t    pathconf_info,
    593 
    594 The table contains the following set of values associated with the mounted
    595 filesystem:
    596 
    597 - link_max
    598 
    599 - max_canon
    600 
    601 - max_input
    602 
    603 - name_max
    604 
    605 - path_max
    606 
    607 - pipe_buf
    608 
    609 - posix_async_io
    610 
    611 - posix_chown_restrictions
    612 
    613 - posix_no_trunc
    614 
    615 - posix_prio_io
    616 
    617 - posix_sync_io
    618 
    619 - posix_vdisable
    620 
    621 These values are accessed with the pathconf() and the fpathconf () functions.
    622 
    623 .. code-block:: c
    624 
    625     const char                                   *dev
    626 
    627 The is intended to contain a string that identifies the device that contains
    628 the filesystem information. The filesystems that are currently implemented are
    629 memory based and don't require a device specification.
    630 
    631 If the mt_point_node.node_access is NULL then we are mounting the base file
    632 system.
    633 
    634 The routine will create a directory node for the root of the IMFS file system.
    635 
    636 The node will have read, write and execute permissions for owner, group and
    637 others.
    638 
    639 The node's name will be a null string.
    640 
    641 A filesystem information structure(fs_info) will be allocated and initialized
    642 for the IMFS filesystem. The fs_info pointer in the mount table entry will be
    643 set to point the filesystem information structure.
    644 
    645 The pathconf_info element of the mount table will be set to the appropriate
    646 table of path configuration constants (LIMITS_AND_OPTIONS).
    647 
    648 The fs_root_node structure will be filled in with the following:
    649 
    650 - pointer to the allocated root node of the filesystem
    651 
    652 - directory handlers for a directory node under the IMFS filesystem
    653 
    654 - OPS table functions for the IMFS
    655 
    656 A 0 will be returned to the calling routine if the process succeeded, otherwise
    657 a 1 will be returned.
     540    Read only or read/write access
     541
     542    .. code-block:: c
     543
     544        void                                         *fs_info,
     545
     546    This points to an allocated block of memory the will be used to hold any
     547    filesystem specific information of a global nature. This allocated region
     548    if important because it allows us to mount the same filesystem type more
     549    than once under the RTEMS system.  Each instance of the mounted filesystem
     550    has its own set of global management information that is separate from the
     551    global management information associated with the other instances of the
     552    mounted filesystem type.
     553
     554    .. code-block:: c
     555
     556        rtems_filesystem_limits_and_options_t    pathconf_info,
     557
     558    The table contains the following set of values associated with the mounted
     559    filesystem:
     560
     561    - link_max
     562
     563    - max_canon
     564
     565    - max_input
     566
     567    - name_max
     568
     569    - path_max
     570
     571    - pipe_buf
     572
     573    - posix_async_io
     574
     575    - posix_chown_restrictions
     576
     577    - posix_no_trunc
     578
     579    - posix_prio_io
     580
     581    - posix_sync_io
     582
     583    - posix_vdisable
     584
     585    These values are accessed with the pathconf() and the fpathconf () functions.
     586
     587    .. code-block:: c
     588
     589        const char                                   *dev
     590
     591    The is intended to contain a string that identifies the device that
     592    contains the filesystem information. The filesystems that are currently
     593    implemented are memory based and don't require a device specification.
     594
     595    If the mt_point_node.node_access is NULL then we are mounting the base file
     596    system.
     597
     598    The routine will create a directory node for the root of the IMFS file
     599    system.
     600
     601    The node will have read, write and execute permissions for owner, group and
     602    others.
     603
     604    The node's name will be a null string.
     605
     606    A filesystem information structure(fs_info) will be allocated and
     607    initialized for the IMFS filesystem. The fs_info pointer in the mount table
     608    entry will be set to point the filesystem information structure.
     609
     610    The pathconf_info element of the mount table will be set to the appropriate
     611    table of path configuration constants (LIMITS_AND_OPTIONS).
     612
     613    The fs_root_node structure will be filled in with the following:
     614
     615    - pointer to the allocated root node of the filesystem
     616
     617    - directory handlers for a directory node under the IMFS filesystem
     618
     619    - OPS table functions for the IMFS
     620
     621    A 0 will be returned to the calling routine if the process succeeded,
     622    otherwise a 1 will be returned.
    658623
    659624unmount Handler
    660 ~~~~~~~~~~~~~~~
    661 
    662 **Corresponding Structure Element:**
    663 
    664 XXX
    665 
    666 **Arguments:**
    667 
    668 XXX
    669 
    670 **Description:**
    671 
    672 XXX
     625^^^^^^^^^^^^^^^
     626
     627Corresponding Structure Element:
     628    XXX
     629
     630Arguments:
     631    XXX
     632
     633Description:
     634    XXX
    673635
    674636fsunmount_me Handler
    675 ~~~~~~~~~~~~~~~~~~~~
    676 
    677 **Corresponding Structure Element:**
    678 
    679 imfs_fsunmount_me()
    680 
    681 **Arguments:**
    682 
    683 .. code-block:: c
    684 
    685     rtems_filesystem_mount_table_entry_t   *mt_entry
    686 
    687 **Description:**
    688 
    689 XXX
     637^^^^^^^^^^^^^^^^^^^^
     638
     639Corresponding Structure Element:
     640    ``imfs_fsunmount_me()``
     641
     642Arguments:
     643    .. code-block:: c
     644
     645        rtems_filesystem_mount_table_entry_t   *mt_entry
     646
     647Description:
     648    XXX
    690649
    691650utime Handler
    692 ~~~~~~~~~~~~~
    693 
    694 **Corresponding Structure Element:**
    695 
    696 XXX
    697 
    698 **Arguments:**
    699 
    700 XXX
    701 
    702 **Description:**
    703 
    704 XXX
     651^^^^^^^^^^^^^
     652
     653Corresponding Structure Element:
     654    XXX
     655
     656Arguments:
     657    XXX
     658
     659Description:
     660    XXX
    705661
    706662eval_link Handler
    707 ~~~~~~~~~~~~~~~~~
    708 
    709 **Corresponding Structure Element:**
    710 
    711 XXX
    712 
    713 **Arguments:**
    714 
    715 XXX
    716 
    717 **Description:**
    718 
    719 XXX
     663^^^^^^^^^^^^^^^^^
     664
     665Corresponding Structure Element:
     666    XXX
     667
     668Arguments:
     669    XXX
     670
     671Description:
     672    XXX
    720673
    721674symlink Handler
    722 ~~~~~~~~~~~~~~~
    723 
    724 **Corresponding Structure Element:**
    725 
    726 XXX
    727 
    728 **Arguments:**
    729 
    730 XXX
    731 
    732 **Description:**
    733 
    734 XXX
     675^^^^^^^^^^^^^^^
     676
     677Corresponding Structure Element:
     678    XXX
     679
     680Arguments:
     681    XXX
     682
     683Description:
     684    XXX
    735685
    736686File Handler Table Functions
     
    763713
    764714open Handler
    765 ~~~~~~~~~~~~
    766 
    767 **Corresponding Structure Element:**
    768 
    769 open()
    770 
    771 **Arguments:**
    772 
    773 .. code-block:: c
    774 
    775     rtems_libio_t   *iop,
    776     const char      *pathname,
    777     unsigned32       flag,
    778     unsigned32       mode
    779 
    780 **Description:**
    781 
    782 XXX
     715^^^^^^^^^^^^
     716
     717Corresponding Structure Element:
     718    ``open()``
     719
     720Arguments:
     721    .. code-block:: c
     722
     723        rtems_libio_t   *iop,
     724        const char      *pathname,
     725        unsigned32       flag,
     726        unsigned32       mode
     727
     728Description:
     729    XXX
    783730
    784731close Handler
    785732~~~~~~~~~~~~~
    786733
    787 **Corresponding Structure Element:**
    788 
    789 close()
    790 
    791 **Arguments:**
    792 
    793 .. code-block:: c
    794 
    795     rtems_libio_t     *iop
    796 
    797 **Description:**
    798 
    799 XXX
    800 
    801 **NOTES:**
    802 
    803 XXX
     734Corresponding Structure Element:
     735    ``close()``
     736
     737Arguments:
     738    .. code-block:: c
     739
     740        rtems_libio_t     *iop
     741
     742Description:
     743    XXX
     744
     745NOTES:
     746    XXX
    804747
    805748read Handler
    806749~~~~~~~~~~~~
    807750
    808 **Corresponding Structure Element:**
    809 
    810 read()
    811 
    812 **Arguments:**
    813 
    814 .. code-block:: c
    815 
    816     rtems_libio_t     *iop,
    817     void              *buffer,
    818     unsigned32         count
    819 
    820 **Description:**
    821 
    822 XXX
    823 
    824 **NOTES:**
    825 
    826 XXX
     751Corresponding Structure Element:
     752    ``read()``
     753
     754Arguments:
     755    .. code-block:: c
     756
     757        rtems_libio_t     *iop,
     758        void              *buffer,
     759        unsigned32         count
     760
     761Description:
     762    XXX
     763
     764NOTES:
     765    XXX
    827766
    828767write Handler
    829768~~~~~~~~~~~~~
    830769
    831 **Corresponding Structure Element:**
    832 
    833 XXX
    834 
    835 **Arguments:**
    836 
    837 XXX
    838 
    839 **Description:**
    840 
    841 XXX
    842 
    843 **NOTES:**
    844 
    845 XXX
     770Corresponding Structure Element:
     771    XXX
     772
     773Arguments:
     774    XXX
     775
     776Description:
     777    XXX
     778
     779NOTES:
     780    XXX
    846781
    847782ioctl Handler
    848783~~~~~~~~~~~~~
    849784
    850 **Corresponding Structure Element:**
    851 
    852 XXX
    853 
    854 **Arguments:**
    855 
    856 .. code-block:: c
    857 
    858     rtems_libio_t     *iop,
    859     unsigned32       command,
    860     void              *buffer
    861 
    862 **Description:**
    863 
    864 XXX
    865 
    866 **NOTES:**
    867 
    868 XXX
     785Corresponding Structure Element:
     786    XXX
     787
     788Arguments:
     789    .. code-block:: c
     790
     791        rtems_libio_t     *iop,
     792        unsigned32       command,
     793        void              *buffer
     794
     795Description:
     796    XXX
     797
     798NOTES:
     799    XXX
    869800
    870801lseek Handler
    871802~~~~~~~~~~~~~
    872803
    873 **Corresponding Structure Element:**
    874 
    875 lseek()
    876 
    877 **Arguments:**
    878 
    879 .. code-block:: c
    880 
    881     rtems_libio_t     *iop,
    882     off_t              offset,
    883     int                whence
    884 
    885 **Description:**
    886 
    887 XXX
    888 
    889 **NOTES:**
    890 
    891 XXX
     804Corresponding Structure Element:
     805    ``lseek()``
     806
     807Arguments:
     808    .. code-block:: c
     809
     810        rtems_libio_t     *iop,
     811        off_t              offset,
     812        int                whence
     813
     814Description:
     815    XXX
     816
     817NOTES:
     818    XXX
    892819
    893820fstat Handler
    894821~~~~~~~~~~~~~
    895822
    896 **Corresponding Structure Element:**
    897 
    898 fstat()
    899 
    900 **Arguments:**
    901 
    902 .. code-block:: c
    903 
    904     rtems_filesystem_location_info_t   *loc,
    905     struct stat                        *buf
    906 
    907 **Description:**
    908 
    909 The following information is extracted from the filesystem specific node and
    910 placed in the ``stat`` structure:
    911 
    912 - st_mode
    913 
    914 - st_nlink
    915 
    916 - st_ino
    917 
    918 - st_uid
    919 
    920 - st_gid
    921 
    922 - st_atime
    923 
    924 - st_mtime
    925 
    926 - st_ctime
    927 
    928 **NOTES:**
    929 
    930 Both the ``stat()`` and ``lstat()`` services are implemented directly using the
    931 ``fstat()`` handler.  The difference in behavior is determined by how the path
    932 is evaluated prior to this handler being called on a particular file entity.
    933 
    934 The ``fstat()`` system call is implemented directly on top of this filesystem
    935 handler.
     823Corresponding Structure Element:
     824    ``fstat()``
     825
     826Arguments:
     827    .. code-block:: c
     828
     829        rtems_filesystem_location_info_t   *loc,
     830        struct stat                        *buf
     831
     832Description:
     833    The following information is extracted from the filesystem specific node
     834    and placed in the ``stat`` structure:
     835
     836    - st_mode
     837
     838    - st_nlink
     839
     840    - st_ino
     841
     842    - st_uid
     843
     844    - st_gid
     845
     846    - st_atime
     847
     848    - st_mtime
     849
     850    - st_ctime
     851
     852NOTES:
     853    Both the ``stat()`` and ``lstat()`` services are implemented directly using
     854    the ``fstat()`` handler.  The difference in behavior is determined by how
     855    the path is evaluated prior to this handler being called on a particular
     856    file entity.
     857
     858    The ``fstat()`` system call is implemented directly on top of this
     859    filesystem handler.
    936860
    937861fchmod Handler
    938862~~~~~~~~~~~~~~
    939863
    940 **Corresponding Structure Element:**
    941 
    942 fchmod()
    943 
    944 **Arguments:**
    945 
    946 .. code-block:: c
    947 
    948     rtems_libio_t     *iop
    949     mode_t             mode
    950 
    951 **Description:**
    952 
    953 XXX
    954 
    955 **NOTES:**
    956 
    957 XXX
     864Corresponding Structure Element:
     865    ``fchmod()``
     866
     867Arguments:
     868    .. code-block:: c
     869
     870        rtems_libio_t     *iop
     871        mode_t             mode
     872
     873Description:
     874    XXX
     875
     876NOTES:
     877    XXX
    958878
    959879ftruncate Handler
    960880~~~~~~~~~~~~~~~~~
    961881
    962 **Corresponding Structure Element:**
    963 
    964 XXX
    965 
    966 **Arguments:**
    967 
    968 XXX
    969 
    970 **Description:**
    971 
    972 XXX
    973 
    974 **NOTES:**
    975 
    976 XXX
     882Corresponding Structure Element:
     883    XXX
     884
     885Arguments:
     886    XXX
     887
     888Description:
     889    XXX
     890
     891NOTES:
     892    XXX
    977893
    978894fpathconf Handler
    979895~~~~~~~~~~~~~~~~~
    980896
    981 **Corresponding Structure Element:**
    982 
    983 XXX
    984 
    985 **Arguments:**
    986 
    987 XXX
    988 
    989 **Description:**
    990 
    991 XXX
    992 
    993 **NOTES:**
    994 
    995 XXX
     897Corresponding Structure Element:
     898    XXX
     899
     900Arguments:
     901    XXX
     902
     903Description:
     904    XXX
     905
     906NOTES:
     907    XXX
    996908
    997909fsync Handler
    998910~~~~~~~~~~~~~
    999911
    1000 **Corresponding Structure Element:**
    1001 
    1002 XXX
    1003 
    1004 **Arguments:**
    1005 
    1006 XXX
    1007 
    1008 **Description:**
    1009 
    1010 XXX
    1011 
    1012 **NOTES:**
    1013 
    1014 XXX
     912Corresponding Structure Element:
     913    XXX
     914
     915Arguments:
     916    XXX
     917
     918Description:
     919    XXX
     920
     921NOTES:
     922    XXX
    1015923
    1016924fdatasync Handler
    1017925~~~~~~~~~~~~~~~~~
    1018926
    1019 **Corresponding Structure Element:**
    1020 
    1021 XXX
    1022 
    1023 **Arguments:**
    1024 
    1025 XXX
    1026 
    1027 **Description:**
    1028 
    1029 XXX
    1030 
    1031 **NOTES:**
    1032 
    1033 XXX
     927Corresponding Structure Element:
     928    XXX
     929
     930Arguments:
     931    XXX
     932
     933Description:
     934    XXX
     935
     936NOTES:
     937    XXX
    1034938
    1035939fcntl Handler
    1036940~~~~~~~~~~~~~
    1037941
    1038 **Corresponding Structure Element:**
    1039 
    1040 XXX
    1041 
    1042 **Arguments:**
    1043 
    1044 XXX
    1045 
    1046 **Description:**
    1047 
    1048 XXX
    1049 
    1050 **NOTES:**
    1051 
    1052 XXX
     942Corresponding Structure Element:
     943    XXX
     944
     945Arguments:
     946    XXX
     947
     948Description:
     949    XXX
     950
     951NOTES:
     952    XXX
  • filesystem/in-memory.rst

    rf7dbf17 r5431beb  
    66
    77In-Memory Filesystem
    8 ####################
     8********************
    99
    1010This chapter describes the In-Memory FileSystem (IMFS).  The IMFS is a full
     
    130130Miscellaneous IMFS Information
    131131==============================
     132
     133TBD
    132134
    133135Memory associated with the IMFS
     
    198200
    199201IMFS_evalpath()
    200 ~~~~~~~~~~~~~~~
    201 
    202 **Corresponding Structure Element:**
    203 
    204 XXX
    205 
    206 **Arguments:**
    207 
    208 XXX
    209 
    210 **File:**
    211 
    212 XXX
    213 
    214 **Description:**
    215 
    216 XXX
     202^^^^^^^^^^^^^^^
     203
     204Corresponding Structure Element:
     205    XXX
     206
     207Arguments:
     208    XXX
     209
     210File:
     211    XXX
     212
     213Description:
     214    XXX
    217215
    218216IMFS_evalformake()
    219 ~~~~~~~~~~~~~~~~~~
    220 
    221 **Corresponding Structure Element:**
    222 
    223 XXX
    224 
    225 **Arguments:**
    226 
    227 XXX
    228 
    229 **File:**
    230 
    231 XXX
    232 
    233 **Description:**
    234 
    235 XXX
     217^^^^^^^^^^^^^^^^^^
     218
     219Corresponding Structure Element:
     220    XXX
     221
     222Arguments:
     223    XXX
     224
     225File:
     226    XXX
     227
     228Description:
     229    XXX
    236230
    237231IMFS_link()
    238 ~~~~~~~~~~~
    239 
    240 **Corresponding Structure Element:**
    241 
    242 link
    243 
    244 **Arguments:**
    245 
    246 .. code-block:: c
    247 
    248     rtems_filesystem_location_info_t    *to_loc,      /* IN */
    249     rtems_filesystem_location_info_t    *parent_loc,  /* IN */
    250     const char                          *token        /* IN */
    251 
    252 **File:**
    253 
    254 imfs_link.c
    255 
    256 **Description:**
    257 
    258 This routine is used in the IMFS filesystem to create a hard-link.
    259 
    260 It will first examine the st_nlink count of the node that we are trying to.  If
    261 the link count exceeds LINK_MAX an error will be returned.
    262 
    263 The name of the link will be normalized to remove extraneous separators from
    264 the end of the name.
    265 
    266 IMFS_create_node will be used to create a filesystem node that will have the
    267 following characteristics:
    268 
    269 - parent that was determined in the link() function in file link.c
    270 
    271 - Type will be set to IMFS_HARD_LINK
    272 
    273 - name will be set to the normalized name
    274 
    275 - mode of the hard-link will be set to the mode of the target node
    276 
    277 If there was trouble allocating memory for the new node an error will be
    278 returned.
    279 
    280 The st_nlink count of the target node will be incremented to reflect the new
    281 link.
    282 
    283 The time fields of the link will be set to reflect the creation time of the
    284 hard-link.
     232^^^^^^^^^^^
     233
     234Corresponding Structure Element:
     235    ``link``
     236
     237Arguments:
     238    .. code-block:: c
     239
     240        rtems_filesystem_location_info_t    *to_loc,      /* IN */
     241        rtems_filesystem_location_info_t    *parent_loc,  /* IN */
     242        const char                          *token        /* IN */
     243
     244File:
     245    ``imfs_link.c``
     246
     247Description:
     248
     249    This routine is used in the IMFS filesystem to create a hard-link.
     250
     251    It will first examine the st_nlink count of the node that we are trying to.
     252    If the link count exceeds LINK_MAX an error will be returned.
     253
     254    The name of the link will be normalized to remove extraneous separators
     255    from the end of the name.
     256
     257    IMFS_create_node will be used to create a filesystem node that will have
     258    the following characteristics:
     259
     260    - parent that was determined in the link() function in file link.c
     261
     262    - Type will be set to IMFS_HARD_LINK
     263
     264    - name will be set to the normalized name
     265
     266    - mode of the hard-link will be set to the mode of the target node
     267
     268    If there was trouble allocating memory for the new node an error will be
     269    returned.
     270
     271    The st_nlink count of the target node will be incremented to reflect the
     272    new link.
     273
     274    The time fields of the link will be set to reflect the creation time of the
     275    hard-link.
    285276
    286277IMFS_unlink()
    287 ~~~~~~~~~~~~~
    288 
    289 **Corresponding Structure Element:**
    290 
    291 XXX
    292 
    293 **Arguments:**
    294 
    295 XXX
    296 
    297 **File:**
    298 
    299 XXX
    300 
    301 **Description:**
    302 
    303 XXX
     278^^^^^^^^^^^^^
     279
     280Corresponding Structure Element:
     281    XXX
     282
     283Arguments:
     284    XXX
     285
     286File:
     287    XXX
     288
     289Description:
     290    XXX
    304291
    305292IMFS_node_type()
    306 ~~~~~~~~~~~~~~~~
    307 
    308 **Corresponding Structure Element:**
    309 
    310 IMFS_node_type()
    311 
    312 **Arguments:**
    313 
    314 .. code-block:: c
    315 
    316     rtems_filesystem_location_info_t    *pathloc        /* IN */
    317 
    318 **File:**
    319 
    320 imfs_ntype.c
    321 
    322 **Description:**
    323 
    324 This routine will locate the IMFS_jnode_t structure that holds ownership
    325 information for the selected node in the filesystem.
    326 
    327 This structure is pointed to by pathloc->node_access.
    328 
    329 The IMFS_jnode_t type element indicates one of the node types listed below:
    330 
    331 - RTEMS_FILESYSTEM_DIRECTORY
    332 
    333 - RTEMS_FILESYSTEM_DEVICE
    334 
    335 - RTEMS_FILESYSTEM_HARD_LINK
    336 
    337 - RTEMS_FILESYSTEM_MEMORY_FILE
     293^^^^^^^^^^^^^^^^
     294
     295Corresponding Structure Element:
     296    ``IMFS_node_type()``
     297
     298Arguments:
     299    .. code-block:: c
     300
     301        rtems_filesystem_location_info_t    *pathloc        /* IN */
     302
     303File:
     304    ``imfs_ntype.c``
     305
     306Description:
     307    This routine will locate the IMFS_jnode_t structure that holds ownership
     308    information for the selected node in the filesystem.
     309
     310    This structure is pointed to by pathloc->node_access.
     311
     312    The IMFS_jnode_t type element indicates one of the node types listed below:
     313
     314    - RTEMS_FILESYSTEM_DIRECTORY
     315
     316    - RTEMS_FILESYSTEM_DEVICE
     317
     318    - RTEMS_FILESYSTEM_HARD_LINK
     319
     320    - RTEMS_FILESYSTEM_MEMORY_FILE
    338321
    339322.. COMMENT: @page
    340323
    341324IMFS_mknod()
    342 ~~~~~~~~~~~~
    343 
    344 **Corresponding Structure Element:**
    345 
    346 IMFS_mknod()
    347 
    348 **Arguments:**
    349 
    350 .. code-block:: c
    351 
    352     const char                          *token,        /* IN */
    353     mode_t                               mode,         /* IN */
    354     dev_t                                dev,          /* IN */
    355     rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
    356 
    357 **File:**
    358 
    359 imfs_mknod.c
    360 
    361 **Description:**
    362 
    363 This routine will examine the mode argument to determine is we are trying to
    364 create a directory, regular file and a device node. The creation of other node
    365 types is not permitted and will cause an assert.
    366 
    367 Memory space will be allocated for a ``jnode`` and the node will be set up
    368 according to the nodal type that was specified. The IMFS_create_node() function
    369 performs the allocation and setup of the node.
    370 
    371 The only problem that is currently reported is the lack of memory when we
    372 attempt to allocate space for the ``jnode`` (ENOMEN).
     325^^^^^^^^^^^^
     326
     327Corresponding Structure Element:
     328    ``IMFS_mknod()``
     329
     330Arguments:
     331    .. code-block:: c
     332
     333        const char                          *token,        /* IN */
     334        mode_t                               mode,         /* IN */
     335        dev_t                                dev,          /* IN */
     336        rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
     337
     338File:
     339    ``imfs_mknod.c``
     340
     341Description:
     342    This routine will examine the mode argument to determine is we are trying
     343    to create a directory, regular file and a device node. The creation of
     344    other node types is not permitted and will cause an assert.
     345
     346    Memory space will be allocated for a ``jnode`` and the node will be set up
     347    according to the nodal type that was specified. The IMFS_create_node()
     348    function performs the allocation and setup of the node.
     349
     350    The only problem that is currently reported is the lack of memory when we
     351    attempt to allocate space for the ``jnode`` (ENOMEN).
    373352
    374353IMFS_rmnod()
    375 ~~~~~~~~~~~~
    376 
    377 **Corresponding Structure Element:**
    378 
    379 XXX
    380 
    381 **Arguments:**
    382 
    383 XXX
    384 
    385 **File:**
    386 
    387 XXX
    388 
    389 **Description:**
    390 
    391 XXX
     354^^^^^^^^^^^^
     355
     356Corresponding Structure Element:
     357    XXX
     358
     359Arguments:
     360    XXX
     361
     362File:
     363    XXX
     364
     365Description:
     366    XXX
    392367
    393368IMFS_chown()
    394 ~~~~~~~~~~~~
    395 
    396 **Corresponding Structure Element:**
    397 
    398 IMFS_chown()
    399 
    400 **Arguments:**
    401 
    402 .. code-block:: c
    403 
    404     rtems_filesystem_location_info_t    *pathloc        /* IN */
    405     uid_t                                owner          /* IN */
    406     gid_t                                group          /* IN */
    407 
    408 **File:**
    409 
    410 imfs_chown.c
    411 
    412 **Description:**
    413 
    414 This routine will locate the IMFS_jnode_t structure that holds ownership
    415 information for the selected node in the filesystem.
    416 
    417 This structure is pointed to by pathloc->node_access.
    418 
    419 The st_uid and st_gid fields of the node are then modified. Since this is a
    420 memory based filesystem, no further action is required to alter the ownership
    421 of the IMFS_jnode_t structure.
     369^^^^^^^^^^^^
     370
     371Corresponding Structure Element:
     372    ``IMFS_chown()``
     373
     374Arguments:
     375    .. code-block:: c
     376
     377        rtems_filesystem_location_info_t    *pathloc        /* IN */
     378        uid_t                                owner          /* IN */
     379        gid_t                                group          /* IN */
     380
     381File:
     382    ``imfs_chown.c``
     383
     384Description:
     385    This routine will locate the IMFS_jnode_t structure that holds ownership
     386    information for the selected node in the filesystem.
     387
     388    This structure is pointed to by pathloc->node_access.
     389
     390    The st_uid and st_gid fields of the node are then modified. Since this is a
     391    memory based filesystem, no further action is required to alter the
     392    ownership of the IMFS_jnode_t structure.
    422393
    423394IMFS_freenod()
    424 ~~~~~~~~~~~~~~
    425 
    426 **Corresponding Structure Element:**
    427 
    428 IMFS_freenod()
    429 
    430 **Arguments:**
    431 
    432 .. code-block:: c
    433 
    434     rtems_filesystem_location_info_t      *pathloc       /* IN */
    435 
    436 **File:**
    437 
    438 imfs_free.c
    439 
    440 **Description:**
    441 
    442 This method is a private function to the IMFS.  It is called by IMFS routines
    443 to free nodes that have been allocated.  Examples of where this routine may be
    444 called from are unlink and rmnod.
    445 
    446 Note: This routine should not be confused with the filesystem callback freenod.
    447 The IMFS allocates memory until the node no longer exists.
     395^^^^^^^^^^^^^^
     396
     397Corresponding Structure Element:
     398    ``IMFS_freenod()``
     399
     400Arguments:
     401    .. code-block:: c
     402
     403        rtems_filesystem_location_info_t      *pathloc       /* IN */
     404
     405File:
     406    ``imfs_free.c``
     407
     408Description:
     409    This method is a private function to the IMFS.  It is called by IMFS
     410    routines to free nodes that have been allocated.  Examples of where this
     411    routine may be called from are unlink and rmnod.
     412
     413    Note: This routine should not be confused with the filesystem callback
     414    freenod.  The IMFS allocates memory until the node no longer exists.
    448415
    449416IMFS_freenodinfo()
    450 ~~~~~~~~~~~~~~~~~~
    451 
    452 **Corresponding Structure Element:**
    453 
    454 IMFS_freenodinfo()
    455 
    456 **Arguments:**
    457 
    458 .. code-block:: c
    459 
    460     rtems_filesystem_location_info_t      *pathloc       /* IN */
    461 
    462 **File:**
    463 
    464 imfs_free.c
    465 
    466 **Description:**
    467 
    468 The In-Memory File System does not need to allocate memory during the evaluate
    469 routines. Therefore, this routine simply routines PASS.
     417^^^^^^^^^^^^^^^^^^
     418
     419Corresponding Structure Element:
     420    ``IMFS_freenodinfo()``
     421
     422Arguments:
     423    .. code-block:: c
     424
     425        rtems_filesystem_location_info_t      *pathloc       /* IN */
     426
     427File:
     428    ``imfs_free.c``
     429
     430Description:
     431    The In-Memory File System does not need to allocate memory during the
     432    evaluate routines. Therefore, this routine simply routines PASS.
    470433
    471434IMFS_mount()
    472 ~~~~~~~~~~~~
    473 
    474 **Corresponding Structure Element:**
    475 
    476 IMFS_mount()
    477 
    478 **Arguments:**
    479 
    480 .. code-block:: c
    481 
    482     rtems_filesystem_mount_table_entry_t   *mt_entry
    483 
    484 **File:**
    485 
    486 imfs_mount.c
    487 
    488 **Description:**
    489 
    490 This routine provides the filesystem specific processing required to mount a
    491 filesystem for the system that contains the mount point. It will determine if
    492 the point that we are trying to mount onto is a node of IMFS_DIRECTORY type.
    493 
    494 If it is the node's info element is altered so that the info.directory.mt_fs
    495 element points to the mount table chain entry that is associated with the
    496 mounted filesystem at this point. The info.directory.mt_fs element can be
    497 examined to determine if a filesystem is mounted at a directory. If it is NULL,
    498 the directory does not serve as a mount point. A non-NULL entry indicates that
    499 the directory does serve as a mount point and the value of info.directory.mt_fs
    500 can be used to locate the mount table chain entry that describes the filesystem
    501 mounted at this point.
     435^^^^^^^^^^^^
     436
     437Corresponding Structure Element:
     438    ``IMFS_mount()``
     439
     440Arguments:
     441    .. code-block:: c
     442
     443        rtems_filesystem_mount_table_entry_t   *mt_entry
     444
     445File:
     446    ``imfs_mount.c``
     447
     448Description:
     449    This routine provides the filesystem specific processing required to mount
     450    a filesystem for the system that contains the mount point. It will
     451    determine if the point that we are trying to mount onto is a node of
     452    IMFS_DIRECTORY type.
     453
     454    If it is the node's info element is altered so that the
     455    info.directory.mt_fs element points to the mount table chain entry that is
     456    associated with the mounted filesystem at this point. The
     457    info.directory.mt_fs element can be examined to determine if a filesystem
     458    is mounted at a directory. If it is NULL, the directory does not serve as a
     459    mount point. A non-NULL entry indicates that the directory does serve as a
     460    mount point and the value of info.directory.mt_fs can be used to locate the
     461    mount table chain entry that describes the filesystem mounted at this
     462    point.
    502463
    503464IMFS_fsmount_me()
    504 ~~~~~~~~~~~~~~~~~
    505 
    506 **Corresponding Structure Element:**
    507 
    508 IMFS_initialize()
    509 
    510 **Arguments:**
    511 
    512 .. code-block:: c
    513 
    514     rtems_filesystem_mount_table_entry_t   *mt_entry
    515 
    516 **File:**
    517 
    518 imfs_init.c
    519 
    520 **Description:**
    521 
    522 This function is provided with a filesystem to take care of the internal
    523 filesystem management details associated with mounting that filesystem under
    524 the RTEMS environment.
    525 
    526 It is not responsible for the mounting details associated the filesystem
    527 containing the mount point.
    528 
    529 The rtems_filesystem_mount_table_entry_t structure contains the key elements
    530 below:
    531 
    532 .. code-block:: c
    533 
    534     rtems_filesystem_location_info_t         *mt_point_node,
    535 
    536 This structure contains information about the mount point. This
    537 allows us to find the ops-table and the handling functions
    538 associated with the filesystem containing the mount point.
    539 
    540 .. code-block:: c
    541 
    542     rtems_filesystem_location_info_t         *fs_root_node,
    543 
    544 This structure contains information about the root node in the file
    545 system to be mounted. It allows us to find the ops-table and the
    546 handling functions associated with the filesystem to be mounted.
    547 
    548 .. code-block:: c
    549 
    550     rtems_filesystem_options_t                 options,
    551 
    552 Read only or read/write access
    553 
    554 .. code-block:: c
    555 
    556     void                                         *fs_info,
    557 
    558 This points to an allocated block of memory the will be used to hold any
    559 filesystem specific information of a global nature. This allocated region if
    560 important because it allows us to mount the same filesystem type more than once
    561 under the RTEMS system.  Each instance of the mounted filesystem has its own
    562 set of global management information that is separate from the global
    563 management information associated with the other instances of the mounted
    564 filesystem type.
    565 
    566 .. code-block:: c
    567 
    568     rtems_filesystem_limits_and_options_t    pathconf_info,
    569 
    570 The table contains the following set of values associated with the mounted
    571 filesystem:
    572 
    573 - link_max
    574 
    575 - max_canon
    576 
    577 - max_input
    578 
    579 - name_max
    580 
    581 - path_max
    582 
    583 - pipe_buf
    584 
    585 - posix_async_io
    586 
    587 - posix_chown_restrictions
    588 
    589 - posix_no_trunc
    590 
    591 - posix_prio_io
    592 
    593 - posix_sync_io
    594 
    595 - posix_vdisable
    596 
    597 These values are accessed with the pathconf() and the fpathconf () functions.
    598 
    599 .. code-block:: c
    600 
    601     const char                                   *dev
    602 
    603 The is intended to contain a string that identifies the device that contains
    604 the filesystem information. The filesystems that are currently implemented are
    605 memory based and don't require a device specification.
    606 
    607 If the mt_point_node.node_access is NULL then we are mounting the base file
    608 system.
    609 
    610 The routine will create a directory node for the root of the IMFS file system.
    611 
    612 The node will have read, write and execute permissions for owner, group and
    613 others.
    614 
    615 The node's name will be a null string.
    616 
    617 A filesystem information structure(fs_info) will be allocated and initialized
    618 for the IMFS filesystem. The fs_info pointer in the mount table entry will be
    619 set to point the filesystem information structure.
    620 
    621 The pathconf_info element of the mount table will be set to the appropriate
    622 table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
    623 
    624 The fs_root_node structure will be filled in with the following:
    625 
    626 - pointer to the allocated root node of the filesystem
    627 
    628 - directory handlers for a directory node under the IMFS filesystem
    629 
    630 - OPS table functions for the IMFS
    631 
    632 A 0 will be returned to the calling routine if the process succeeded, otherwise
    633 a 1 will be returned.
     465^^^^^^^^^^^^^^^^^
     466
     467Corresponding Structure Element:
     468    ``IMFS_initialize()``
     469
     470Arguments:
     471    .. code-block:: c
     472
     473        rtems_filesystem_mount_table_entry_t   *mt_entry
     474
     475File:
     476    ``imfs_init.c``
     477
     478Description:
     479    This function is provided with a filesystem to take care of the internal
     480    filesystem management details associated with mounting that filesystem
     481    under the RTEMS environment.
     482
     483    It is not responsible for the mounting details associated the filesystem
     484    containing the mount point.
     485
     486    The rtems_filesystem_mount_table_entry_t structure contains the key
     487    elements below:
     488
     489    .. code-block:: c
     490
     491        rtems_filesystem_location_info_t         *mt_point_node,
     492
     493    This structure contains information about the mount point. This allows us
     494    to find the ops-table and the handling functions associated with the
     495    filesystem containing the mount point.
     496
     497    .. code-block:: c
     498
     499        rtems_filesystem_location_info_t         *fs_root_node,
     500
     501    This structure contains information about the root node in the file system
     502    to be mounted. It allows us to find the ops-table and the handling
     503    functions associated with the filesystem to be mounted.
     504
     505    .. code-block:: c
     506
     507        rtems_filesystem_options_t                 options,
     508
     509    Read only or read/write access
     510
     511    .. code-block:: c
     512
     513        void                                         *fs_info,
     514
     515    This points to an allocated block of memory the will be used to hold any
     516    filesystem specific information of a global nature. This allocated region
     517    if important because it allows us to mount the same filesystem type more
     518    than once under the RTEMS system.  Each instance of the mounted filesystem
     519    has its own set of global management information that is separate from the
     520    global management information associated with the other instances of the
     521    mounted filesystem type.
     522
     523    .. code-block:: c
     524
     525        rtems_filesystem_limits_and_options_t    pathconf_info,
     526
     527    The table contains the following set of values associated with the mounted
     528    filesystem:
     529
     530    - link_max
     531
     532    - max_canon
     533
     534    - max_input
     535
     536    - name_max
     537
     538    - path_max
     539
     540    - pipe_buf
     541
     542    - posix_async_io
     543
     544    - posix_chown_restrictions
     545
     546    - posix_no_trunc
     547
     548    - posix_prio_io
     549
     550    - posix_sync_io
     551
     552    - posix_vdisable
     553
     554    These values are accessed with the pathconf() and the fpathconf ()
     555    functions.
     556
     557    .. code-block:: c
     558
     559        const char                                   *dev
     560
     561    The is intended to contain a string that identifies the device that
     562    contains the filesystem information. The filesystems that are currently
     563    implemented are memory based and don't require a device specification.
     564
     565    If the mt_point_node.node_access is NULL then we are mounting the base file
     566    system.
     567
     568    The routine will create a directory node for the root of the IMFS file
     569    system.
     570
     571    The node will have read, write and execute permissions for owner, group and
     572    others.
     573
     574    The node's name will be a null string.
     575
     576    A filesystem information structure(fs_info) will be allocated and
     577    initialized for the IMFS filesystem. The fs_info pointer in the mount table
     578    entry will be set to point the filesystem information structure.
     579
     580    The pathconf_info element of the mount table will be set to the appropriate
     581    table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
     582
     583    The fs_root_node structure will be filled in with the following:
     584
     585    - pointer to the allocated root node of the filesystem
     586
     587    - directory handlers for a directory node under the IMFS filesystem
     588
     589    - OPS table functions for the IMFS
     590
     591    A 0 will be returned to the calling routine if the process succeeded,
     592    otherwise a 1 will be returned.
    634593
    635594IMFS_unmount()
    636 ~~~~~~~~~~~~~~
    637 
    638 **Corresponding Structure Element:**
    639 
    640 IMFS_unmount()
    641 
    642 **Arguments:**
    643 
    644 .. code-block:: c
    645 
    646     rtems_filesystem_mount_table_entry_t   *mt_entry
    647 
    648 **File:**
    649 
    650 imfs_unmount.c
    651 
    652 **Description:**
    653 
    654 This routine allows the IMFS to unmount a filesystem that has been mounted onto
    655 a IMFS directory.
    656 
    657 The mount entry mount point node access is verified to be a mounted directory.
    658 It's mt_fs is set to NULL.  This identifies to future calles into the IMFS that
    659 this directory node is no longer a mount point.  Additionally, it will allow
    660 any directories that were hidden by the mounted system to again become visible.
     595^^^^^^^^^^^^^^
     596
     597Corresponding Structure Element:
     598    ``IMFS_unmount()``
     599
     600Arguments:
     601    .. code-block:: c
     602
     603        rtems_filesystem_mount_table_entry_t   *mt_entry
     604
     605File:
     606    ``imfs_unmount.c``
     607
     608Description:
     609    This routine allows the IMFS to unmount a filesystem that has been mounted
     610    onto a IMFS directory.
     611
     612    The mount entry mount point node access is verified to be a mounted
     613    directory.  It's mt_fs is set to NULL.  This identifies to future calles
     614    into the IMFS that this directory node is no longer a mount point.
     615    Additionally, it will allow any directories that were hidden by the mounted
     616    system to again become visible.
    661617
    662618IMFS_fsunmount()
    663 ~~~~~~~~~~~~~~~~
    664 
    665 **Corresponding Structure Element:**
    666 
    667 imfs_fsunmount()
    668 
    669 **Arguments:**
    670 
    671 .. code-block:: c
    672 
    673     rtems_filesystem_mount_table_entry_t   *mt_entry
    674 
    675 **File:**
    676 
    677 imfs_init.c
    678 
    679 **Description:**
    680 
    681 This method unmounts this instance of the IMFS file system.  It is the
    682 counterpart to the IMFS_initialize routine.  It is called by the generic code
    683 under the fsunmount_me callback.
    684 
    685 All method loops finding the first encountered node with no children and
    686 removing the node from the tree, thus returning allocated resources.  This is
    687 done until all allocated nodes are returned.
     619^^^^^^^^^^^^^^^^
     620
     621Corresponding Structure Element:
     622    ``imfs_fsunmount()``
     623
     624Arguments:
     625    .. code-block:: c
     626
     627        rtems_filesystem_mount_table_entry_t   *mt_entry
     628
     629File:
     630    ``imfs_init.c``
     631
     632Description:
     633    This method unmounts this instance of the IMFS file system.  It is the
     634    counterpart to the IMFS_initialize routine.  It is called by the generic
     635    code under the fsunmount_me callback.
     636
     637    All method loops finding the first encountered node with no children and
     638    removing the node from the tree, thus returning allocated resources.  This
     639    is done until all allocated nodes are returned.
    688640
    689641IMFS_utime()
    690 ~~~~~~~~~~~~
    691 
    692 **Corresponding Structure Element:**
    693 
    694 XXX
    695 
    696 **Arguments:**
    697 
    698 XXX
    699 
    700 **File:**
    701 
    702 XXX
    703 
    704 **Description:**
    705 
    706 XXX
     642^^^^^^^^^^^^
     643
     644Corresponding Structure Element:
     645    XXX
     646
     647Arguments:
     648    XXX
     649
     650File:
     651    XXX
     652
     653Description:
     654    XXX
    707655
    708656IMFS_eval_link()
    709 ~~~~~~~~~~~~~~~~
    710 
    711 **Corresponding Structure Element:**
    712 
    713 XXX
    714 
    715 **Arguments:**
    716 
    717 XXX
    718 
    719 **File:**
    720 
    721 XXX
    722 
    723 **Description:**
    724 
    725 XXX
     657^^^^^^^^^^^^^^^^
     658
     659Corresponding Structure Element:
     660    XXX
     661
     662Arguments:
     663    XXX
     664
     665File:
     666    XXX
     667
     668Description:
     669    XXX
    726670
    727671Regular File Handler Table Functions
     
    754698
    755699memfile_open() for Regular Files
    756 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    757 
    758 **Corresponding Structure Element:**
    759 
    760 memfile_open()
    761 
    762 **Arguments:**
    763 
    764 .. code-block:: c
    765 
    766     rtems_libio_t   *iop,
    767     const char      *pathname,
    768     unsigned32       flag,
    769     unsigned32       mode
    770 
    771 **File:**
    772 
    773 memfile.c
    774 
    775 **Description:**
    776 
    777 Currently this function is a shell. No meaningful processing is performed and a
    778 success code is always returned.
     700^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     701
     702Corresponding Structure Element:
     703    ``memfile_open()``
     704
     705Arguments:
     706    .. code-block:: c
     707
     708        rtems_libio_t   *iop,
     709        const char      *pathname,
     710        unsigned32       flag,
     711        unsigned32       mode
     712
     713File:
     714    ``memfile.c``
     715
     716Description:
     717    Currently this function is a shell. No meaningful processing is performed
     718    and a success code is always returned.
    779719
    780720memfile_close() for Regular Files
    781 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    782 
    783 **Corresponding Structure Element:**
    784 
    785 memfile_close()
    786 
    787 **Arguments:**
    788 
    789 .. code-block:: c
    790 
    791     rtems_libio_t     *iop
    792 
    793 **File:**
    794 
    795 memfile.c
    796 
    797 **Description:**
    798 
    799 This routine is a dummy for regular files under the base filesystem. It
    800 performs a capture of the IMFS_jnode_t pointer from the file control block and
    801 then immediately returns a success status.
     721^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     722
     723Corresponding Structure Element:
     724    ``memfile_close()``
     725
     726Arguments:
     727    .. code-block:: c
     728
     729        rtems_libio_t     *iop
     730
     731File:
     732    ``memfile.c``
     733
     734Description:
     735    This routine is a dummy for regular files under the base filesystem. It
     736    performs a capture of the IMFS_jnode_t pointer from the file control block
     737    and then immediately returns a success status.
    802738
    803739memfile_read() for Regular Files
    804 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    805 
    806 **Corresponding Structure Element:**
    807 
    808 memfile_read()
    809 
    810 **Arguments:**
    811 
    812 .. code-block:: c
    813 
    814     rtems_libio_t     *iop,
    815     void              *buffer,
    816     unsigned32         count
    817 
    818 **File:**
    819 
    820 memfile.c
    821 
    822 **Description:**
    823 
    824 This routine will determine the ``jnode`` that is associated with this file.
    825 
    826 It will then call IMFS_memfile_read() with the ``jnode``, file position index,
    827 buffer and transfer count as arguments.
    828 
    829 IMFS_memfile_read() will do the following:
    830 
    831 - Verify that the ``jnode`` is associated with a memory file
    832 
    833 - Verify that the destination of the read is valid
    834 
    835 - Adjust the length of the read if it is too long
    836 
    837 - Acquire data from the memory blocks associated with the file
    838 
    839 - Update the access time for the data in the file
     740^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     741
     742Corresponding Structure Element:
     743    ``memfile_read()``
     744
     745Arguments:
     746    .. code-block:: c
     747
     748        rtems_libio_t     *iop,
     749        void              *buffer,
     750        unsigned32         count
     751
     752File:
     753    ``memfile.c``
     754
     755Description:
     756    This routine will determine the ``jnode`` that is associated with this
     757    file.
     758
     759    It will then call IMFS_memfile_read() with the ``jnode``, file position
     760    index, buffer and transfer count as arguments.
     761
     762    IMFS_memfile_read() will do the following:
     763
     764    - Verify that the ``jnode`` is associated with a memory file
     765
     766    - Verify that the destination of the read is valid
     767
     768    - Adjust the length of the read if it is too long
     769
     770    - Acquire data from the memory blocks associated with the file
     771
     772    - Update the access time for the data in the file
    840773
    841774memfile_write() for Regular Files
    842 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    843 
    844 **Corresponding Structure Element:**
    845 
    846 XXX
    847 
    848 **Arguments:**
    849 
    850 XXX
    851 
    852 **File:**
    853 
    854 XXX
    855 
    856 **Description:**
    857 
    858 XXX
     775^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     776
     777Corresponding Structure Element:
     778    XXX
     779
     780Arguments:
     781    XXX
     782
     783File:
     784    XXX
     785
     786Description:
     787    XXX
    859788
    860789memfile_ioctl() for Regular Files
    861 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    862 
    863 **Corresponding Structure Element:**
    864 
    865 XXX
    866 
    867 **Arguments:**
    868 
    869 .. code-block:: c
    870 
    871     rtems_libio_t   *iop,
    872     unsigned32       command,
    873     void            *buffer
    874 
    875 **File:**
    876 
    877 memfile.c
    878 
    879 **Description:**
    880 
    881 The current code is a placeholder for future development. The routine returns
    882 a successful completion status.
     790^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     791
     792Corresponding Structure Element:
     793    XXX
     794
     795Arguments:
     796    .. code-block:: c
     797
     798        rtems_libio_t   *iop,
     799        unsigned32       command,
     800        void            *buffer
     801
     802File:
     803    ``memfile.c``
     804
     805Description:
     806    The current code is a placeholder for future development. The routine
     807    returns a successful completion status.
    883808
    884809memfile_lseek() for Regular Files
    885 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    886 
    887 **Corresponding Structure Element:**
    888 
    889 Memfile_lseek()
    890 
    891 **Arguments:**
    892 
    893 .. code-block:: c
    894 
    895     rtems_libio_t     *iop,
    896     off_t              offset,
    897     int                whence
    898 
    899 **File:**
    900 
    901 memfile.c
    902 
    903 **Description:**
    904 
    905 This routine make sure that the memory based file is sufficiently large to
    906 allow for the new file position index.
    907 
    908 The IMFS_memfile_extend() function is used to evaluate the current size of the
    909 memory file and allocate additional memory blocks if required by the new file
    910 position index. A success code is always returned from this routine.
     810^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     811
     812Corresponding Structure Element:
     813    ``Memfile_lseek()``
     814
     815Arguments:
     816    .. code-block:: c
     817
     818        rtems_libio_t     *iop,
     819        off_t              offset,
     820        int                whence
     821
     822File:
     823    ``memfile.c``
     824
     825Description:
     826    This routine make sure that the memory based file is sufficiently large to
     827    allow for the new file position index.
     828
     829    The IMFS_memfile_extend() function is used to evaluate the current size of
     830    the memory file and allocate additional memory blocks if required by the
     831    new file position index. A success code is always returned from this
     832    routine.
    911833
    912834IMFS_stat() for Regular Files
    913 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    914 
    915 **Corresponding Structure Element:**
    916 
    917 IMFS_stat()
    918 
    919 **Arguments:**
    920 
    921 .. code-block:: c
    922 
    923     rtems_filesystem_location_info_t   *loc,
    924     struct stat                        *buf
    925 
    926 **File:**
    927 
    928 imfs_stat.c
    929 
    930 **Description:**
    931 
    932 This routine actually performs status processing for both devices and regular
    933 files.
    934 
    935 The IMFS_jnode_t structure is referenced to determine the type of node under
    936 the filesystem.
    937 
    938 If the node is associated with a device, node information is extracted and
    939 transformed to set the st_dev element of the stat structure.
    940 
    941 If the node is a regular file, the size of the regular file is extracted from
    942 the node.
    943 
    944 This routine rejects other node types.
    945 
    946 The following information is extracted from the node and placed in the stat
    947 structure:
    948 
    949 - st_mode
    950 
    951 - st_nlink
    952 
    953 - st_ino
    954 
    955 - st_uid
    956 
    957 - st_gid
    958 
    959 - st_atime
    960 
    961 - st_mtime
    962 
    963 - st_ctime
     835^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     836
     837Corresponding Structure Element:
     838    ``IMFS_stat()``
     839
     840Arguments:
     841    .. code-block:: c
     842
     843        rtems_filesystem_location_info_t   *loc,
     844        struct stat                        *buf
     845
     846File:
     847    ``imfs_stat.c``
     848
     849Description:
     850    This routine actually performs status processing for both devices and
     851    regular files.
     852
     853    The IMFS_jnode_t structure is referenced to determine the type of node
     854    under the filesystem.
     855
     856    If the node is associated with a device, node information is extracted and
     857    transformed to set the st_dev element of the stat structure.
     858
     859    If the node is a regular file, the size of the regular file is extracted
     860    from the node.
     861
     862    This routine rejects other node types.
     863
     864    The following information is extracted from the node and placed in the stat
     865    structure:
     866
     867    - st_mode
     868
     869    - st_nlink
     870
     871    - st_ino
     872
     873    - st_uid
     874
     875    - st_gid
     876
     877    - st_atime
     878
     879    - st_mtime
     880
     881    - st_ctime
    964882
    965883IMFS_fchmod() for Regular Files
    966 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    967 
    968 **Corresponding Structure Element:**
    969 
    970 IMFS_fchmod()
    971 
    972 **Arguments:**
    973 
    974 .. code-block:: c
    975 
    976     rtems_libio_t     *iop
    977     mode_t             mode
    978 
    979 **File:**
    980 
    981 imfs_fchmod.c
    982 
    983 **Description:**
    984 
    985 This routine will obtain the pointer to the IMFS_jnode_t structure from the
    986 information currently in the file control block.
    987 
    988 Based on configuration the routine will acquire the user ID from a call to
    989 getuid() or from the IMFS_jnode_t structure.
    990 
    991 It then checks to see if we have the ownership rights to alter the mode of the
    992 file.  If the caller does not, an error code is returned.
    993 
    994 An additional test is performed to verify that the caller is not trying to
    995 alter the nature of the node. If the caller is attempting to alter more than
    996 the permissions associated with user group and other, an error is returned.
    997 
    998 If all the preconditions are met, the user, group and other fields are set
    999 based on the mode calling parameter.
     884^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     885
     886Corresponding Structure Element:
     887    ``IMFS_fchmod()``
     888
     889Arguments:
     890    .. code-block:: c
     891
     892        rtems_libio_t     *iop
     893        mode_t             mode
     894
     895File:
     896    ``imfs_fchmod.c``
     897
     898Description:
     899    This routine will obtain the pointer to the IMFS_jnode_t structure from the
     900    information currently in the file control block.
     901
     902    Based on configuration the routine will acquire the user ID from a call to
     903    getuid() or from the IMFS_jnode_t structure.
     904
     905    It then checks to see if we have the ownership rights to alter the mode of
     906    the file.  If the caller does not, an error code is returned.
     907
     908    An additional test is performed to verify that the caller is not trying to
     909    alter the nature of the node. If the caller is attempting to alter more
     910    than the permissions associated with user group and other, an error is
     911    returned.
     912
     913    If all the preconditions are met, the user, group and other fields are set
     914    based on the mode calling parameter.
    1000915
    1001916memfile_ftruncate() for Regular Files
    1002 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1003 
    1004 **Corresponding Structure Element:**
    1005 
    1006 XXX
    1007 
    1008 **Arguments:**
    1009 
    1010 XXX
    1011 
    1012 **File:**
    1013 
    1014 XXX
    1015 
    1016 **Description:**
    1017 
    1018 XXX
     917^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     918
     919Corresponding Structure Element:
     920    XXX
     921
     922Arguments:
     923    XXX
     924
     925File:
     926    XXX
     927
     928Description:
     929    XXX
    1019930
    1020931No pathconf() for Regular Files
    1021 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1022 
    1023 **Corresponding Structure Element:**
    1024 
    1025 NULL
    1026 
    1027 **Arguments:**
    1028 
    1029 Not Implemented
    1030 
    1031 **File:**
    1032 
    1033 Not Implemented
    1034 
    1035 **Description:**
    1036 
    1037 Not Implemented
     932^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     933
     934Corresponding Structure Element:
     935    ``NULL``
     936
     937Arguments:
     938    Not Implemented
     939
     940File:
     941    Not Implemented
     942
     943Description:
     944    Not Implemented
    1038945
    1039946No fsync() for Regular Files
    1040 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1041 
    1042 **Corresponding Structure Element:**
    1043 
    1044 XXX
    1045 
    1046 **Arguments:**
    1047 
    1048 XXX
    1049 
    1050 **File:**
    1051 
    1052 XXX
    1053 
    1054 **Description:**
    1055 
    1056 XXX
     947^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     948
     949Corresponding Structure Element:
     950    XXX
     951
     952Arguments:
     953    XXX
     954
     955File:
     956    XXX
     957
     958Description:
     959    XXX
    1057960
    1058961IMFS_fdatasync() for Regular Files
    1059 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1060 
    1061 **Corresponding Structure Element:**
    1062 
    1063 XXX
    1064 
    1065 **Arguments:**
    1066 
    1067 XXX
    1068 
    1069 **File:**
    1070 
    1071 XXX
    1072 
    1073 **Description:**
    1074 
    1075 XXX
     962^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     963
     964Corresponding Structure Element:
     965    XXX
     966
     967Arguments:
     968    XXX
     969
     970File:
     971    XXX
     972
     973Description:
     974    XXX
    1076975
    1077976Directory Handler Table Functions
     
    11041003
    11051004IMFS_dir_open() for Directories
    1106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1107 
    1108 **Corresponding Structure Element:**
    1109 
    1110 imfs_dir_open()
    1111 
    1112 **Arguments:**
    1113 
    1114 .. code-block:: c
    1115 
    1116     rtems_libio_t  *iop,
    1117     const char     *pathname,
    1118     unsigned32      flag,
    1119     unsigned32      mode
    1120 
    1121 **File:**
    1122 
    1123 imfs_directory.c
    1124 
    1125 **Description:**
    1126 
    1127 This routine will look into the file control block to find the ``jnode`` that
    1128 is associated with the directory.
    1129 
    1130 The routine will verify that the node is a directory. If its not a directory an
    1131 error code will be returned.
    1132 
    1133 If it is a directory, the offset in the file control block will be set to 0.
    1134 This allows us to start reading at the beginning of the directory.
     1005^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1006
     1007Corresponding Structure Element:
     1008    ``imfs_dir_open()``
     1009
     1010Arguments:
     1011    .. code-block:: c
     1012
     1013        rtems_libio_t  *iop,
     1014        const char     *pathname,
     1015        unsigned32      flag,
     1016        unsigned32      mode
     1017
     1018File:
     1019    ``imfs_directory.c``
     1020
     1021Description:
     1022    This routine will look into the file control block to find the ``jnode``
     1023    that is associated with the directory.
     1024
     1025    The routine will verify that the node is a directory. If its not a
     1026    directory an error code will be returned.
     1027
     1028    If it is a directory, the offset in the file control block will be set
     1029    to 0.  This allows us to start reading at the beginning of the directory.
    11351030
    11361031IMFS_dir_close() for Directories
    1137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1138 
    1139 **Corresponding Structure Element:**
    1140 
    1141 imfs_dir_close()
    1142 
    1143 **Arguments:**
    1144 
    1145 .. code-block:: c
    1146 
    1147     rtems_libio_t     *iop
    1148 
    1149 **File:**
    1150 
    1151 imfs_directory.c
    1152 
    1153 **Description:**
    1154 
    1155 This routine is a dummy for directories under the base filesystem. It
    1156 immediately returns a success status.
     1032^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1033
     1034Corresponding Structure Element:
     1035    ``imfs_dir_close()``
     1036
     1037Arguments:
     1038    .. code-block:: c
     1039
     1040        rtems_libio_t     *iop
     1041
     1042File:
     1043    ``imfs_directory.c``
     1044
     1045Description:
     1046    This routine is a dummy for directories under the base filesystem. It
     1047    immediately returns a success status.
    11571048
    11581049IMFS_dir_read() for Directories
    1159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1160 
    1161 **Corresponding Structure Element:**
    1162 
    1163 imfs_dir_read
    1164 
    1165 **Arguments:**
    1166 
    1167 .. code-block:: c
    1168 
    1169     rtems_libio_t  *iop,
    1170     void           *buffer,
    1171     unsigned32      count
    1172 
    1173 **File:**
    1174 
    1175 imfs_directory.c
    1176 
    1177 **Description:**
    1178 
    1179 This routine will read a fixed number of directory entries from the current
    1180 directory offset. The number of directory bytes read will be returned from this
    1181 routine.
     1050^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1051
     1052Corresponding Structure Element:
     1053    ``imfs_dir_read``
     1054
     1055Arguments:
     1056    .. code-block:: c
     1057
     1058        rtems_libio_t  *iop,
     1059        void           *buffer,
     1060        unsigned32      count
     1061
     1062File:
     1063    ``imfs_directory.c``
     1064
     1065Description:
     1066    This routine will read a fixed number of directory entries from the current
     1067    directory offset. The number of directory bytes read will be returned from
     1068    this routine.
    11821069
    11831070No write() for Directories
    1184 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1185 
    1186 **Corresponding Structure Element:**
    1187 
    1188 XXX
    1189 
    1190 **Arguments:**
    1191 
    1192 XXX
    1193 
    1194 **File:**
    1195 
    1196 XXX
    1197 
    1198 **Description:**
    1199 
    1200 XXX
     1071^^^^^^^^^^^^^^^^^^^^^^^^^^
     1072
     1073Corresponding Structure Element:
     1074    XXX
     1075
     1076Arguments:
     1077    XXX
     1078
     1079File:
     1080    XXX
     1081
     1082Description:
     1083    XXX
    12011084
    12021085No ioctl() for Directories
    1203 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1204 
    1205 **Corresponding Structure Element:**
    1206 
    1207 ioctl
    1208 
    1209 **Arguments:**
    1210 
    1211 **File:**
    1212 
    1213 Not supported
    1214 
    1215 **Description:**
    1216 
    1217 XXX
     1086^^^^^^^^^^^^^^^^^^^^^^^^^^
     1087
     1088Corresponding Structure Element:
     1089    ``ioctl``
     1090
     1091Arguments:
     1092    Not supported
     1093
     1094File:
     1095    Not supported
     1096
     1097Description:
     1098    XXX
    12181099
    12191100IMFS_dir_lseek() for Directories
    1220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1221 
    1222 **Corresponding Structure Element:**
    1223 
    1224 imfs_dir_lseek()
    1225 
    1226 **Arguments:**
    1227 
    1228 .. code-block:: c
    1229 
    1230     rtems_libio_t      *iop,
    1231     off_t               offset,
    1232     int                 whence
    1233 
    1234 **File:**
    1235 
    1236 imfs_directory.c
    1237 
    1238 **Description:**
    1239 
    1240 This routine alters the offset in the file control block.
    1241 
    1242 No test is performed on the number of children under the current open
    1243 directory.  The imfs_dir_read() function protects against reads beyond the
    1244 current size to the directory by returning a 0 bytes transfered to the calling
    1245 programs whenever the file position index exceeds the last entry in the open
    1246 directory.
     1101^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1102
     1103Corresponding Structure Element:
     1104    ``imfs_dir_lseek()``
     1105
     1106Arguments:
     1107    .. code-block:: c
     1108
     1109        rtems_libio_t      *iop,
     1110        off_t               offset,
     1111        int                 whence
     1112
     1113File:
     1114    ``imfs_directory.c``
     1115
     1116Description:
     1117    This routine alters the offset in the file control block.
     1118
     1119    No test is performed on the number of children under the current open
     1120    directory.  The imfs_dir_read() function protects against reads beyond the
     1121    current size to the directory by returning a 0 bytes transfered to the
     1122    calling programs whenever the file position index exceeds the last entry in
     1123    the open directory.
    12471124
    12481125IMFS_dir_fstat() for Directories
    1249 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1250 
    1251 **Corresponding Structure Element:**
    1252 
    1253 imfs_dir_fstat()
    1254 
    1255 **Arguments:**
    1256 
    1257 .. code-block:: c
    1258 
    1259     rtems_filesystem_location_info_t   *loc,
    1260     struct stat                        *buf
    1261 
    1262 **File:**
    1263 
    1264 imfs_directory.c
    1265 
    1266 **Description:**
    1267 
    1268 The node access information in the rtems_filesystem_location_info_t structure
    1269 is used to locate the appropriate IMFS_jnode_t structure. The following
    1270 information is taken from the IMFS_jnode_t structure and placed in the stat
    1271 structure:
    1272 
    1273 - st_ino
    1274 
    1275 - st_mode
    1276 
    1277 - st_nlink
    1278 
    1279 - st_uid
    1280 
    1281 - st_gid
    1282 
    1283 - st_atime
    1284 
    1285 - st_mtime
    1286 
    1287 - st_ctime
    1288 
    1289 The st_size field is obtained by running through the chain of directory entries
    1290 and summing the sizes of the dirent structures associated with each of the
    1291 children of the directory.
     1126^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1127
     1128Corresponding Structure Element:
     1129    ``imfs_dir_fstat()``
     1130
     1131Arguments:
     1132    .. code-block:: c
     1133
     1134        rtems_filesystem_location_info_t   *loc,
     1135        struct stat                        *buf
     1136
     1137File:
     1138    ``imfs_directory.c``
     1139
     1140Description:
     1141    The node access information in the rtems_filesystem_location_info_t
     1142    structure is used to locate the appropriate IMFS_jnode_t structure. The
     1143    following information is taken from the IMFS_jnode_t structure and placed
     1144    in the stat structure:
     1145
     1146    - st_ino
     1147
     1148    - st_mode
     1149
     1150    - st_nlink
     1151
     1152    - st_uid
     1153
     1154    - st_gid
     1155
     1156    - st_atime
     1157
     1158    - st_mtime
     1159
     1160    - st_ctime
     1161
     1162    The st_size field is obtained by running through the chain of directory
     1163    entries and summing the sizes of the dirent structures associated with each
     1164    of the children of the directory.
    12921165
    12931166IMFS_fchmod() for Directories
    1294 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1295 
    1296 **Corresponding Structure Element:**
    1297 
    1298 IMFS_fchmod()
    1299 
    1300 **Arguments:**
    1301 
    1302 .. code-block:: c
    1303 
    1304     rtems_libio_t     *iop
    1305     mode_t             mode
    1306 
    1307 **File:**
    1308 
    1309 imfs_fchmod.c
    1310 
    1311 **Description:**
    1312 
    1313 This routine will obtain the pointer to the IMFS_jnode_t structure from the
    1314 information currently in the file control block.
    1315 
    1316 Based on configuration the routine will acquire the user ID from a call to
    1317 getuid() or from the IMFS_jnode_t structure.
    1318 
    1319 It then checks to see if we have the ownership rights to alter the mode of the
    1320 file.  If the caller does not, an error code is returned.
    1321 
    1322 An additional test is performed to verify that the caller is not trying to
    1323 alter the nature of the node. If the caller is attempting to alter more than
    1324 the permissions associated with user group and other, an error is returned.
    1325 
    1326 If all the preconditions are met, the user, group and other fields are set
    1327 based on the mode calling parameter.
     1167^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1168
     1169Corresponding Structure Element:
     1170    ``IMFS_fchmod()``
     1171
     1172Arguments:
     1173    .. code-block:: c
     1174
     1175        rtems_libio_t     *iop
     1176        mode_t             mode
     1177
     1178File:
     1179    ``imfs_fchmod.c``
     1180
     1181Description:
     1182    This routine will obtain the pointer to the IMFS_jnode_t structure from the
     1183    information currently in the file control block.
     1184
     1185    Based on configuration the routine will acquire the user ID from a call to
     1186    getuid() or from the IMFS_jnode_t structure.
     1187
     1188    It then checks to see if we have the ownership rights to alter the mode of
     1189    the file.  If the caller does not, an error code is returned.
     1190
     1191    An additional test is performed to verify that the caller is not trying to
     1192    alter the nature of the node. If the caller is attempting to alter more
     1193    than the permissions associated with user group and other, an error is
     1194    returned.
     1195
     1196    If all the preconditions are met, the user, group and other fields are set
     1197    based on the mode calling parameter.
    13281198
    13291199No ftruncate() for Directories
    1330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1331 
    1332 **Corresponding Structure Element:**
    1333 
    1334 XXX
    1335 
    1336 **Arguments:**
    1337 
    1338 XXX
    1339 
    1340 **File:**
    1341 
    1342 XXX
    1343 
    1344 **Description:**
    1345 
    1346 XXX
     1200^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1201
     1202Corresponding Structure Element:
     1203    XXX
     1204
     1205Arguments:
     1206    XXX
     1207
     1208File:
     1209    XXX
     1210
     1211Description:
     1212    XXX
    13471213
    13481214No fpathconf() for Directories
    1349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1350 
    1351 **Corresponding Structure Element:**
    1352 
    1353 fpathconf
    1354 
    1355 **Arguments:**
    1356 
    1357 Not Implemented
    1358 
    1359 **File:**
    1360 
    1361 Not Implemented
    1362 
    1363 **Description:**
    1364 
    1365 Not Implemented
     1215^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1216
     1217Corresponding Structure Element:
     1218    ``fpathconf``
     1219
     1220Arguments:
     1221    Not Implemented
     1222
     1223File:
     1224    Not Implemented
     1225
     1226Description:
     1227    Not Implemented
    13661228
    13671229No fsync() for Directories
    1368 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1369 
    1370 **Corresponding Structure Element:**
    1371 
    1372 XXX
    1373 
    1374 **Arguments:**
    1375 
    1376 XXX
    1377 
    1378 **File:**
    1379 
    1380 XXX
    1381 
    1382 **Description:**
    1383 
    1384 XXX
     1230^^^^^^^^^^^^^^^^^^^^^^^^^^
     1231
     1232Corresponding Structure Element:
     1233    XXX
     1234
     1235Arguments:
     1236    XXX
     1237
     1238File:
     1239    XXX
     1240
     1241Description:
     1242    XXX
    13851243
    13861244IMFS_fdatasync() for Directories
    1387 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1388 
    1389 **Corresponding Structure Element:**
    1390 
    1391 XXX
    1392 
    1393 **Arguments:**
    1394 
    1395 XXX
    1396 
    1397 **File:**
    1398 
    1399 XXX
    1400 
    1401 **Description:**
    1402 
    1403 XXX
     1245^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     1246
     1247Corresponding Structure Element:
     1248    XXX
     1249
     1250Arguments:
     1251    XXX
     1252
     1253File:
     1254    XXX
     1255
     1256Description:
     1257    XXX
    14041258
    14051259Device Handler Table Functions
     
    14311285
    14321286device_open() for Devices
    1433 ~~~~~~~~~~~~~~~~~~~~~~~~~
    1434 
    1435 **Corresponding Structure Element:**
    1436 
    1437 device_open()
    1438 
    1439 **Arguments:**
    1440 
    1441 .. code-block:: c
    1442 
    1443     rtems_libio_t     *iop,
    1444     const char        *pathname,
    1445     unsigned32         flag,
    1446     unsigned32         mode
    1447 
    1448 **File:**
    1449 
    1450 deviceio.c
    1451 
    1452 **Description:**
    1453 
    1454 This routine will use the file control block to locate the node structure for
    1455 the device.
    1456 
    1457 It will extract the major and minor device numbers from the ``jnode``.
    1458 
    1459 The major and minor device numbers will be used to make a rtems_io_open()
    1460 function call to open the device driver. An argument list is sent to the driver
    1461 that contains the file control block, flags and mode information.
     1287^^^^^^^^^^^^^^^^^^^^^^^^^
     1288
     1289Corresponding Structure Element:
     1290    ``device_open()``
     1291
     1292Arguments:
     1293    .. code-block:: c
     1294
     1295        rtems_libio_t     *iop,
     1296        const char        *pathname,
     1297        unsigned32         flag,
     1298        unsigned32         mode
     1299
     1300File:
     1301    ``deviceio.c``
     1302
     1303Description:
     1304    This routine will use the file control block to locate the node structure
     1305    for the device.
     1306
     1307    It will extract the major and minor device numbers from the ``jnode``.
     1308
     1309    The major and minor device numbers will be used to make a rtems_io_open()
     1310    function call to open the device driver. An argument list is sent to the
     1311    driver that contains the file control block, flags and mode information.
    14621312
    14631313device_close() for Devices
    1464 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1465 
    1466 **Corresponding Structure Element:**
    1467 
    1468 device_close()
    1469 
    1470 **Arguments:**
    1471 
    1472 .. code-block:: c
    1473 
    1474     rtems_libio_t     *iop
    1475 
    1476 **File:**
    1477 
    1478 deviceio.c
    1479 
    1480 **Description:**
    1481 
    1482 This routine extracts the major and minor device driver numbers from the
    1483 IMFS_jnode_t that is referenced in the file control block.
    1484 
    1485 It also forms an argument list that contains the file control block.
    1486 
    1487 A rtems_io_close() function call is made to close the device specified by the
    1488 major and minor device numbers.
     1314^^^^^^^^^^^^^^^^^^^^^^^^^^
     1315
     1316Corresponding Structure Element:
     1317    ``device_close()``
     1318
     1319Arguments:
     1320    .. code-block:: c
     1321
     1322        rtems_libio_t     *iop
     1323
     1324File:
     1325    ``deviceio.c``
     1326
     1327Description:
     1328    This routine extracts the major and minor device driver numbers from the
     1329    IMFS_jnode_t that is referenced in the file control block.
     1330
     1331    It also forms an argument list that contains the file control block.
     1332
     1333    A rtems_io_close() function call is made to close the device specified by
     1334    the major and minor device numbers.
    14891335
    14901336device_read() for Devices
    1491 ~~~~~~~~~~~~~~~~~~~~~~~~~
    1492 
    1493 **Corresponding Structure Element:**
    1494 
    1495 device_read()
    1496 
    1497 **Arguments:**
    1498 
    1499 .. code-block:: c
    1500 
    1501     rtems_libio_t     *iop,
    1502     void              *buffer,
    1503     unsigned32         count
    1504 
    1505 **File:**
    1506 
    1507 deviceio.c
    1508 
    1509 **Description:**
    1510 
    1511 This routine will extract the major and minor numbers for the device from the -
    1512 jnode- associated with the file descriptor.
    1513 
    1514 A rtems_io_read() call will be made to the device driver associated with the
    1515 file descriptor. The major and minor device number will be sent as arguments as
    1516 well as an argument list consisting of:
    1517 
    1518 - file control block
    1519 
    1520 - file position index
    1521 
    1522 - buffer pointer where the data read is to be placed
    1523 
    1524 - count indicating the number of bytes that the program wishes to read
    1525   from the device
    1526 
    1527 - flags from the file control block
    1528 
    1529 On return from the rtems_io_read() the number of bytes that were actually read
    1530 will be returned to the calling program.
     1337^^^^^^^^^^^^^^^^^^^^^^^^^
     1338
     1339Corresponding Structure Element:
     1340    ``device_read()``
     1341
     1342Arguments:
     1343    .. code-block:: c
     1344
     1345        rtems_libio_t     *iop,
     1346        void              *buffer,
     1347        unsigned32         count
     1348
     1349File:
     1350    ``deviceio.c``
     1351
     1352Description:
     1353    This routine will extract the major and minor numbers for the device from
     1354    the - jnode- associated with the file descriptor.
     1355
     1356    A rtems_io_read() call will be made to the device driver associated with
     1357    the file descriptor. The major and minor device number will be sent as
     1358    arguments as well as an argument list consisting of:
     1359
     1360    - file control block
     1361
     1362    - file position index
     1363
     1364    - buffer pointer where the data read is to be placed
     1365
     1366    - count indicating the number of bytes that the program wishes to read from
     1367      the device
     1368
     1369    - flags from the file control block
     1370
     1371    On return from the rtems_io_read() the number of bytes that were actually
     1372    read will be returned to the calling program.
    15311373
    15321374device_write() for Devices
    1533 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1534 
    1535 **Corresponding Structure Element:**
    1536 
    1537 XXX
    1538 
    1539 **Arguments:**
    1540 
    1541 XXX
    1542 
    1543 **File:**
    1544 
    1545 XXX
    1546 
    1547 **Description:**
    1548 
    1549 XXX
     1375^^^^^^^^^^^^^^^^^^^^^^^^^^
     1376
     1377Corresponding Structure Element:
     1378    XXX
     1379
     1380Arguments:
     1381    XXX
     1382
     1383File:
     1384    XXX
     1385
     1386Description:
     1387    XXX
    15501388
    15511389device_ioctl() for Devices
    1552 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1553 
    1554 **Corresponding Structure Element:**
    1555 
    1556 ioctl
    1557 
    1558 **Arguments:**
    1559 
    1560 .. code-block:: c
    1561 
    1562     rtems_libio_t     *iop,
    1563     unsigned32         command,
    1564     void              *buffer
    1565 
    1566 **File:**
    1567 
    1568 deviceio.c
    1569 
    1570 **Description:**
    1571 
    1572 This handler will obtain status information about a device.
    1573 
    1574 The form of status is device dependent.
    1575 
    1576 The rtems_io_control() function uses the major and minor number of the device
    1577 to obtain the status information.
    1578 
    1579 rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
    1580 contains the file control block, device specific command and a buffer pointer
    1581 to return the device status information.
    1582 
    1583 The device specific command should indicate the nature of the information that
    1584 is desired from the device.
    1585 
    1586 After the rtems_io_control() is processed, the buffer should contain the
    1587 requested device information.
    1588 
    1589 If the device information is not obtained properly a -1 will be returned to the
    1590 calling program, otherwise the ioctl_return value is returned.
     1390^^^^^^^^^^^^^^^^^^^^^^^^^^
     1391
     1392Corresponding Structure Element:
     1393    ``ioctl``
     1394
     1395Arguments:
     1396    .. code-block:: c
     1397
     1398        rtems_libio_t     *iop,
     1399        unsigned32         command,
     1400        void              *buffer
     1401
     1402File:
     1403    ``deviceio.c``
     1404
     1405Description:
     1406    This handler will obtain status information about a device.
     1407
     1408    The form of status is device dependent.
     1409
     1410    The rtems_io_control() function uses the major and minor number of the
     1411    device to obtain the status information.
     1412
     1413    rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
     1414    contains the file control block, device specific command and a buffer
     1415    pointer to return the device status information.
     1416
     1417    The device specific command should indicate the nature of the information
     1418    that is desired from the device.
     1419
     1420    After the rtems_io_control() is processed, the buffer should contain the
     1421    requested device information.
     1422
     1423    If the device information is not obtained properly a -1 will be returned to
     1424    the calling program, otherwise the ioctl_return value is returned.
    15911425
    15921426device_lseek() for Devices
    1593 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1594 
    1595 **Corresponding Structure Element:**
    1596 
    1597 device_lseek()
    1598 
    1599 **Arguments:**
    1600 
    1601 .. code-block:: c
    1602 
    1603     rtems_libio_t     *iop,
    1604     off_t              offset,
    1605     int                whence
    1606 
    1607 **File:**
    1608 
    1609 deviceio.c
    1610 
    1611 **Description:**
    1612 
    1613 At the present time this is a placeholder function. It always returns a
    1614 successful status.
     1427^^^^^^^^^^^^^^^^^^^^^^^^^^
     1428
     1429Corresponding Structure Element:
     1430    ``device_lseek()``
     1431
     1432Arguments:
     1433    .. code-block:: c
     1434
     1435        rtems_libio_t     *iop,
     1436        off_t              offset,
     1437        int                whence
     1438
     1439File:
     1440    ``deviceio.c``
     1441
     1442Description:
     1443    At the present time this is a placeholder function. It always returns a
     1444    successful status.
    16151445
    16161446IMFS_stat() for Devices
    1617 ~~~~~~~~~~~~~~~~~~~~~~~
    1618 
    1619 **Corresponding Structure Element:**
    1620 
    1621 IMFS_stat()
    1622 
    1623 **Arguments:**
    1624 
    1625 .. code-block:: c
    1626 
    1627     rtems_filesystem_location_info_t   *loc,
    1628     struct stat                        *buf
    1629 
    1630 **File:**
    1631 
    1632 imfs_stat.c
    1633 
    1634 **Description:**
    1635 
    1636 This routine actually performs status processing for both devices and regular files.
    1637 
    1638 The IMFS_jnode_t structure is referenced to determine the type of node under
    1639 the filesystem.
    1640 
    1641 If the node is associated with a device, node information is extracted and
    1642 transformed to set the st_dev element of the stat structure.
    1643 
    1644 If the node is a regular file, the size of the regular file is extracted from
    1645 the node.
    1646 
    1647 This routine rejects other node types.
    1648 
    1649 The following information is extracted from the node and placed in the stat
    1650 structure:
    1651 
    1652 - st_mode
    1653 
    1654 - st_nlink
    1655 
    1656 - st_ino
    1657 
    1658 - st_uid
    1659 
    1660 - st_gid
    1661 
    1662 - st_atime
    1663 
    1664 - st_mtime
    1665 
    1666 - st_ctime
     1447^^^^^^^^^^^^^^^^^^^^^^^
     1448
     1449Corresponding Structure Element:
     1450    ``IMFS_stat()``
     1451
     1452Arguments:
     1453    .. code-block:: c
     1454
     1455        rtems_filesystem_location_info_t   *loc,
     1456        struct stat                        *buf
     1457
     1458File:
     1459    ``imfs_stat.c``
     1460
     1461Description:
     1462    This routine actually performs status processing for both devices and
     1463    regular files.
     1464
     1465    The IMFS_jnode_t structure is referenced to determine the type of node
     1466    under the filesystem.
     1467
     1468    If the node is associated with a device, node information is extracted and
     1469    transformed to set the st_dev element of the stat structure.
     1470
     1471    If the node is a regular file, the size of the regular file is extracted
     1472    from the node.
     1473
     1474    This routine rejects other node types.
     1475
     1476    The following information is extracted from the node and placed in the stat
     1477    structure:
     1478
     1479    - st_mode
     1480
     1481    - st_nlink
     1482
     1483    - st_ino
     1484
     1485    - st_uid
     1486
     1487    - st_gid
     1488
     1489    - st_atime
     1490
     1491    - st_mtime
     1492
     1493    - st_ctime
    16671494
    16681495IMFS_fchmod() for Devices
    1669 ~~~~~~~~~~~~~~~~~~~~~~~~~
    1670 
    1671 **Corresponding Structure Element:**
    1672 
    1673 IMFS_fchmod()
    1674 
    1675 **Arguments:**
    1676 
    1677 .. code-block:: c
    1678 
    1679     rtems_libio_t     *iop
    1680     mode_t             mode
    1681 
    1682 **File:**
    1683 
    1684 imfs_fchmod.c
    1685 
    1686 **Description:**
    1687 
    1688 This routine will obtain the pointer to the IMFS_jnode_t structure from the
    1689 information currently in the file control block.
    1690 
    1691 Based on configuration the routine will acquire the user ID from a call to
    1692 getuid()  or from the IMFS_jnode_t structure.
    1693 
    1694 It then checks to see if we have the ownership rights to alter the mode of the
    1695 file.  If the caller does not, an error code is returned.
    1696 
    1697 An additional test is performed to verify that the caller is not trying to
    1698 alter the nature of the node. If the caller is attempting to alter more than
    1699 the permissions associated with user group and other, an error is returned.
    1700 
    1701 If all the preconditions are met, the user, group and other fields are set
    1702 based on the mode calling parameter.
     1496^^^^^^^^^^^^^^^^^^^^^^^^^
     1497
     1498Corresponding Structure Element:
     1499    ``IMFS_fchmod()``
     1500
     1501Arguments:
     1502    .. code-block:: c
     1503
     1504        rtems_libio_t     *iop
     1505        mode_t             mode
     1506
     1507File:
     1508    ``imfs_fchmod.c``
     1509
     1510Description:
     1511    This routine will obtain the pointer to the IMFS_jnode_t structure from the
     1512    information currently in the file control block.
     1513
     1514    Based on configuration the routine will acquire the user ID from a call to
     1515    getuid() or from the IMFS_jnode_t structure.
     1516
     1517    It then checks to see if we have the ownership rights to alter the mode of
     1518    the file.  If the caller does not, an error code is returned.
     1519
     1520    An additional test is performed to verify that the caller is not trying to
     1521    alter the nature of the node. If the caller is attempting to alter more
     1522    than the permissions associated with user group and other, an error is
     1523    returned.
     1524
     1525    If all the preconditions are met, the user, group and other fields are set
     1526    based on the mode calling parameter.
    17031527
    17041528No ftruncate() for Devices
    1705 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1706 
    1707 **Corresponding Structure Element:**
    1708 
    1709 XXX
    1710 
    1711 **Arguments:**
    1712 
    1713 XXX
    1714 
    1715 **File:**
    1716 
    1717 XXX
    1718 
    1719 **Description:**
    1720 
    1721 XXX
     1529^^^^^^^^^^^^^^^^^^^^^^^^^^
     1530
     1531Corresponding Structure Element:
     1532    XXX
     1533
     1534Arguments:
     1535    XXX
     1536
     1537File:
     1538    XXX
     1539
     1540Description:
     1541    XXX
    17221542
    17231543No fpathconf() for Devices
    1724 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1725 
    1726 **Corresponding Structure Element:**
    1727 
    1728 fpathconf
    1729 
    1730 **Arguments:**
     1544^^^^^^^^^^^^^^^^^^^^^^^^^^
     1545
     1546Corresponding Structure Element:
     1547    ``fpathconf``
     1548
     1549Arguments:
     1550    Not Implemented
     1551
     1552File:
     1553    Not Implemented
     1554
     1555Description:
     1556    Not Implemented
     1557
     1558No fsync() for Devices
     1559^^^^^^^^^^^^^^^^^^^^^^
     1560
     1561Corresponding Structure Element:
     1562    XXX
     1563
     1564Arguments:
     1565    XXX
     1566
     1567File:
     1568    XXX
     1569
     1570Description:
     1571    XXX
     1572
     1573No fdatasync() for Devices
     1574^^^^^^^^^^^^^^^^^^^^^^^^^^
    17311575
    17321576Not Implemented
    17331577
    1734 **File:**
    1735 
    1736 Not Implemented
    1737 
    1738 **Description:**
    1739 
    1740 Not Implemented
    1741 
    1742 No fsync() for Devices
    1743 ~~~~~~~~~~~~~~~~~~~~~~
    1744 
    1745 **Corresponding Structure Element:**
    1746 
    1747 XXX
    1748 
    1749 **Arguments:**
    1750 
    1751 XXX
    1752 
    1753 **File:**
    1754 
    1755 XXX
    1756 
    1757 **Description:**
    1758 
    1759 XXX
    1760 
    1761 No fdatasync() for Devices
    1762 ~~~~~~~~~~~~~~~~~~~~~~~~~~
    1763 
    1764 Not Implemented
    1765 
    1766 **Corresponding Structure Element:**
    1767 
    1768 XXX
    1769 
    1770 **Arguments:**
    1771 
    1772 XXX
    1773 
    1774 **File:**
    1775 
    1776 XXX
    1777 
    1778 **Description:**
    1779 
    1780 XXX
     1578Corresponding Structure Element:
     1579    XXX
     1580
     1581Arguments:
     1582    XXX
     1583
     1584File:
     1585    XXX
     1586
     1587Description:
     1588    XXX
  • filesystem/index.rst

    rf7dbf17 r5431beb  
    44RTEMS Filesystem Design Guide
    55=============================
     6
     7RTEMS Filesystem Design Guide
     8-----------------------------
    69
    710 | COPYRIGHT (c) 1988 - 2015.
     
    3336
    3437.. toctree::
    35         :maxdepth: 3
     38        :maxdepth: 5
    3639        :numbered:
    3740
  • filesystem/minature_in-memory.rst

    rf7dbf17 r5431beb  
    66
    77Miniature In-Memory Filesystem
    8 ##############################
     8******************************
    99
    1010This chapter describes the Miniature In-Memory FileSystem (miniIMFS).  The
  • filesystem/mounting_and_unmounting.rst

    rf7dbf17 r5431beb  
    66
    77Mounting and Unmounting Filesystems
    8 ###################################
     8***********************************
    99
    1010Mount Points
  • filesystem/pathname_eval.rst

    rf7dbf17 r5431beb  
    66
    77Pathname Evaluation
    8 ###################
     8*******************
    99
    1010This chapter describes the pathname evaluation process for the RTEMS Filesystem
  • filesystem/preface.rst

    rf7dbf17 r5431beb  
    55.. COMMENT: All rights reserved.
    66
    7 =======
    87Preface
    9 =======
     8*******
    109
    1110This document describes the implementation of the RTEMS filesystem
     
    2019- Individual file and directory support for the following:
    2120
    22   # Permissions for read, write and execute
    23   # User ID
    24   # Group ID
    25   # Access time
    26   # Modification time
    27   # Creation time
     21  #. Permissions for read, write and execute
     22  #. User ID
     23  #. Group ID
     24  #. Access time
     25  #. Modification time
     26  #. Creation time
    2827
    2928- Hard links to files and directories
  • filesystem/system_init.rst

    rf7dbf17 r5431beb  
    66
    77System Initialization
    8 #####################
     8*********************
    99
    1010After the RTEMS initialization is performed, the application's initialization
  • filesystem/trivial_ftp.rst

    rf7dbf17 r5431beb  
    22
    33Trivial FTP Client Filesystem
    4 #############################
     4*****************************
    55
    66This chapter describes the Trivial FTP (TFTP) Client Filesystem.
Note: See TracChangeset for help on using the changeset viewer.