Changeset 08dc4bd in rtems


Ignore:
Timestamp:
Oct 28, 1999, 7:42:05 PM (20 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
49ea76d
Parents:
dcb93155
Message:

Reformatted.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/filesystem/syscalls.t

    rdcb93155 r08dc4bd  
    4343@end enumerate
    4444
    45 The sections that follow provide developmental information concerning each of these functions.
     45The sections that follow provide developmental information concerning each
     46of these functions.
    4647
    4748 
     
    5556@subheading Processing:
    5657
    57 This routine is layered on the stat() function. It acquires the current status
    58 information for the specified file and then determines if the caller has the ability
    59 to access the file for read, write or execute according to the mode argument to this
    60 function.
    61 
    62 @subheading Development Comments:
    63 
    64 This routine is layered on top of the stat() function. As long as the st_mode
    65 element in the returned structure follow the standard UNIX conventions, this
    66 function should support other filesystems without alteration.
     58This routine is layered on the stat() function. It acquires the current
     59status information for the specified file and then determines if the
     60caller has the ability to access the file for read, write or execute
     61according to the mode argument to this function.
     62
     63@subheading Development Comments:
     64
     65This routine is layered on top of the stat() function. As long as the
     66st_mode element in the returned structure follow the standard UNIX
     67conventions, this function should support other filesystems without
     68alteration.
    6769
    6870@c @page
     
    7678@subheading Processing:
    7779
    78 This routine will determine if the pathname that we are attempting to make that
    79 current directory exists and is in fact a directory. If these conditions are met the
    80 global indication of the current directory (rtems_filesystem_current) is set to the
    81 rtems_filesystem_location_info_t structure that is returned by the
    82 rtems_filesystem_evaluate_path() routine.
    83 
    84 @subheading Development Comments:
    85 
    86 This routine is layered on the rtems_filesystem_evaluate_path() routine and the
    87 filesystem specific OP table function node_type().
    88 
    89 The routine node_type() must be a routine provided for each filesystem since it
    90 must access the filesystems node information to determine which of the
    91 following types the node is:
     80This routine will determine if the pathname that we are attempting to make
     81that current directory exists and is in fact a directory. If these
     82conditions are met the global indication of the current directory
     83(rtems_filesystem_current) is set to the rtems_filesystem_location_info_t
     84structure that is returned by the rtems_filesystem_evaluate_path()
     85routine.
     86
     87@subheading Development Comments:
     88
     89This routine is layered on the rtems_filesystem_evaluate_path() routine
     90and the filesystem specific OP table function node_type().
     91
     92The routine node_type() must be a routine provided for each filesystem
     93since it must access the filesystems node information to determine which
     94of the following types the node is:
    9295
    9396@itemize @bullet
     
    98101@end itemize
    99102
    100 This acknowledges that the form of the node management information can vary
    101 from one filesystem implementation to another.
    102 
    103 RTEMS has a special global structure that maintains the current directory
    104 location. This global variable is of type rtems_filesystem_location_info_t and is
    105 called rtems_filesystem_current. This structure is not always valid. In order to
    106 determine if the structure is valid, you must first test the node_access element of
    107 this structure. If the pointer is NULL, then the structure does not contain a valid
    108 indication of what the current directory is.
     103This acknowledges that the form of the node management information can
     104vary from one filesystem implementation to another.
     105
     106RTEMS has a special global structure that maintains the current directory
     107location. This global variable is of type rtems_filesystem_location_info_t
     108and is called rtems_filesystem_current. This structure is not always
     109valid. In order to determine if the structure is valid, you must first
     110test the node_access element of this structure. If the pointer is NULL,
     111then the structure does not contain a valid indication of what the current
     112directory is.
    109113
    110114@c @page
     
    117121@subheading Processing:
    118122
    119 This routine is layered on the open(), fchmod() and close() functions. As long as
    120 the standard interpretation of the mode_t value is maintained, this routine should
    121 not need modification to support other filesystems.
    122 
    123 @subheading Development Comments:
    124 
    125 The routine first determines if the selected file can be open with read/write access.
    126 This is required to allow modification of the mode associated with the selected
    127 path.
    128 
    129 The fchmod() function is used to actually change the mode of the path using the
    130 integer file descriptor returned by the open() function.
     123This routine is layered on the open(), fchmod() and close() functions. As
     124long as the standard interpretation of the mode_t value is maintained,
     125this routine should not need modification to support other filesystems.
     126
     127@subheading Development Comments:
     128
     129The routine first determines if the selected file can be open with
     130read/write access.  This is required to allow modification of the mode
     131associated with the selected path.
     132
     133The fchmod() function is used to actually change the mode of the path
     134using the integer file descriptor returned by the open() function.
    131135
    132136After mode modification, the open file descriptor is closed.
     
    141145@subheading Processing:
    142146
    143 This routine is layered on the rtems_filesystem_evaluate_path() and the file
    144 system specific chown() routine that is specified in the OPS table for the file
    145 system.
    146 
    147 @subheading Development Comments:
    148 
    149 rtems_filesystem_evaluate_path() is used to determine if the path specified
    150 actually exists. If it does a rtems_filesystem_location_info_t structure will be
    151 obtained that allows the shell function to locate the OPS table that is to be used
    152 for this filesystem.
    153 
    154 It is possible that the chown() function that should be in the OPS table is not
    155 defined. A test for a non-NULL OPS table chown() entry is performed before the
    156 function is called.
    157 
    158 If the chown() function is defined in the indicated OPS table, the function is
    159 called with the rtems_filesystem_location_info_t structure returned from the path
    160 evaluation routine, the desired owner, and group information.
     147This routine is layered on the rtems_filesystem_evaluate_path() and the
     148file system specific chown() routine that is specified in the OPS table
     149for the file system.
     150
     151@subheading Development Comments:
     152
     153rtems_filesystem_evaluate_path() is used to determine if the path
     154specified actually exists. If it does a rtems_filesystem_location_info_t
     155structure will be obtained that allows the shell function to locate the
     156OPS table that is to be used for this filesystem.
     157
     158It is possible that the chown() function that should be in the OPS table
     159is not defined. A test for a non-NULL OPS table chown() entry is performed
     160before the function is called.
     161
     162If the chown() function is defined in the indicated OPS table, the
     163function is called with the rtems_filesystem_location_info_t structure
     164returned from the path evaluation routine, the desired owner, and group
     165information.
    161166
    162167@c @page
     
    169174@subheading Processing:
    170175
    171 This routine will allow for the closing of both network connections and file
    172 system devices. If the file descriptor is associated with a network device, the
    173 appropriate network function handler will be selected from a table of previously
    174 registered network functions (rtems_libio_handlers) and that function will be
    175 invoked.
    176 
    177 If the file descriptor refers to an entry in the filesystem, the appropriate handler
    178 will be selected using information that has been placed in the file control block for
    179 the device (rtems_libio_t structure).
    180 
    181 @subheading Development Comments:
    182 
    183 rtems_file_descriptor_type examines some of the upper bits of the file descriptor
    184 index. If it finds that the upper bits are set in the file descriptor index, the device
    185 referenced is a network device.
    186 
    187 Network device handlers are obtained from a special registration table
    188 (rtems_libio_handlers) that is set up during network initialization. The network
    189 handler invoked and the status of the network handler will be returned to the
    190 calling process.
    191 
    192 If none of the upper bits are set in the file descriptor index, the file descriptor
    193 refers to an element of the RTEMS filesystem.
    194 
    195 The following sequence will be performed for any filesystem file descriptor:
     176This routine will allow for the closing of both network connections and
     177file system devices. If the file descriptor is associated with a network
     178device, the appropriate network function handler will be selected from a
     179table of previously registered network functions (rtems_libio_handlers)
     180and that function will be invoked.
     181
     182If the file descriptor refers to an entry in the filesystem, the
     183appropriate handler will be selected using information that has been
     184placed in the file control block for the device (rtems_libio_t structure).
     185
     186@subheading Development Comments:
     187
     188rtems_file_descriptor_type examines some of the upper bits of the file
     189descriptor index. If it finds that the upper bits are set in the file
     190descriptor index, the device referenced is a network device.
     191
     192Network device handlers are obtained from a special registration table
     193(rtems_libio_handlers) that is set up during network initialization. The
     194network handler invoked and the status of the network handler will be
     195returned to the calling process.
     196
     197If none of the upper bits are set in the file descriptor index, the file
     198descriptor refers to an element of the RTEMS filesystem.
     199
     200The following sequence will be performed for any filesystem file
     201descriptor:
    196202
    197203@enumerate
    198204
    199 @item Use the rtems_libio_iop() function to obtain the rtems_libio_t structure for the
    200 file descriptor
     205@item Use the rtems_libio_iop() function to obtain the rtems_libio_t
     206structure for the file descriptor
    201207
    202208@item Range check the file descriptor using rtems_libio_check_fd()
    203209
    204 @item Determine if there is actually a function in the selected handler table that
    205 processes the close() operation for the filesystem and node type selected.
    206 This is generally done to avoid execution attempts on functions that have not
    207 been implemented.
    208 
    209 @item If the function has been defined it is invoked with the file control block
    210 pointer as its argument.
    211 
    212 @item The file control block that was associated with the open file descriptor is
    213 marked as free using rtems_libio_free().
    214 
    215 @item The return code from the close handler is then passed back to the calling
    216 program.
     210@item Determine if there is actually a function in the selected handler
     211table that processes the close() operation for the filesystem and node
     212type selected.  This is generally done to avoid execution attempts on
     213functions that have not been implemented.
     214
     215@item If the function has been defined it is invoked with the file control
     216block pointer as its argument.
     217
     218@item The file control block that was associated with the open file
     219descriptor is marked as free using rtems_libio_free().
     220
     221@item The return code from the close handler is then passed back to the
     222calling program.
    217223
    218224@end enumerate
     
    227233@subheading Processing:
    228234
    229 The code was obtained from the BSD group. This routine must clean up the
    230 memory resources that are required to track an open directory. The code is layered
    231 on the close() function and standard memory free() functions. It should not
    232 require alterations to support other filesystems.
    233 
    234 @subheading Development Comments:
    235 
    236 The routine alters the file descriptor and the index into the DIR structure to make
    237 it an invalid file descriptor. Apparently the memory that is about to be freed may
    238 still be referenced before it is reallocated.
    239 
    240 The dd_buf structure's memory is reallocated before the control structure that
    241 contains the pointer to the dd_buf region.
     235The code was obtained from the BSD group. This routine must clean up the
     236memory resources that are required to track an open directory. The code is
     237layered on the close() function and standard memory free() functions. It
     238should not require alterations to support other filesystems.
     239
     240@subheading Development Comments:
     241
     242The routine alters the file descriptor and the index into the DIR
     243structure to make it an invalid file descriptor. Apparently the memory
     244that is about to be freed may still be referenced before it is
     245reallocated.
     246
     247The dd_buf structure's memory is reallocated before the control structure
     248that contains the pointer to the dd_buf region.
    242249
    243250DIR control memory is reallocated.
     
    288295@subheading Processing:
    289296
    290 This routine will alter the permissions of a node in a filesystem. It is layered on
    291 the following functions and macros:
     297This routine will alter the permissions of a node in a filesystem. It is
     298layered on the following functions and macros:
    292299
    293300@itemize @bullet
     
    300307@item rtems_libio_check_permissions()
    301308
    302 @item fchmod() function that is referenced by the handler table in the file control block associated with this file descriptor
     309@item fchmod() function that is referenced by the handler table in the
     310file control block associated with this file descriptor
    303311
    304312@end itemize
     
    306314@subheading Development Comments:
    307315
    308 The routine will test to see if the file descriptor index is associated with a network
    309 connection. If it is, an error is returned from this routine.
    310 
    311 The file descriptor index is used to obtain the associated file control block.
     316The routine will test to see if the file descriptor index is associated
     317with a network connection. If it is, an error is returned from this
     318routine.
     319
     320The file descriptor index is used to obtain the associated file control
     321block.
    312322
    313323The file descriptor value is range checked.
    314324
    315 The file control block is examined to determine if it has write permissions to
    316 allow us to alter the mode of the file.
    317 
    318 A test is made to determine if the handler table that is referenced in the file
    319 control block contains an entry for the fchmod() handler function. If it does not,
    320 an error is returned to the calling routine.
    321 
    322 If the fchmod() handler function exists, it is called with the file control block and
    323 the desired mode as parameters.
     325The file control block is examined to determine if it has write
     326permissions to allow us to alter the mode of the file.
     327
     328A test is made to determine if the handler table that is referenced in the
     329file control block contains an entry for the fchmod() handler function. If
     330it does not, an error is returned to the calling routine.
     331
     332If the fchmod() handler function exists, it is called with the file
     333control block and the desired mode as parameters.
    324334
    325335@c @page
     
    332342@subheading Processing:
    333343
    334 This routine currently only interacts with the file control block. If the structure of
    335 the file control block and the associated meanings do not change, the partial
    336 implementation of fcntl() should remain unaltered for other filesystem
    337 implementations.
    338 
    339 @subheading Development Comments:
    340 
    341 The only commands that have been implemented are the F_GETFD and
    342 F_SETFD. The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC
    343 bit in the @code{flags} element of the file control block associated with the file
     344This routine currently only interacts with the file control block. If the
     345structure of the file control block and the associated meanings do not
     346change, the partial implementation of fcntl() should remain unaltered for
     347other filesystem implementations.
     348
     349@subheading Development Comments:
     350
     351The only commands that have been implemented are the F_GETFD and F_SETFD.
     352The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the
     353@code{flags} element of the file control block associated with the file
    344354descriptor index.
    345355
    346 The current implementation of the function performs the sequence of operations
    347 below:
     356The current implementation of the function performs the sequence of
     357operations below:
    348358
    349359@enumerate
    350360
    351 @item Test to see if we are trying to operate on a file descriptor associated with a
    352 network connection
    353 
    354 @item Obtain the file control block that is associated with the file descriptor index
     361@item Test to see if we are trying to operate on a file descriptor
     362associated with a network connection
     363
     364@item Obtain the file control block that is associated with the file
     365descriptor index
    355366
    356367@item Perform a range check on the file descriptor index.
     
    385396@item rtems_libio_check_permissions()
    386397
    387 @item fdatasync() function that is referenced by the handler table in the file control block associated with this file descriptor
     398@item fdatasync() function that is referenced by the handler table in the
     399file control block associated with this file descriptor
    388400
    389401@end itemize
     
    391403@subheading Development Comments:
    392404
    393 The routine will test to see if the file descriptor index is associated with a network
    394 connection. If it is, an error is returned from this routine.
    395 
    396 The file descriptor index is used to obtain the associated file control block.
     405The routine will test to see if the file descriptor index is associated
     406with a network connection. If it is, an error is returned from this
     407routine.
     408
     409The file descriptor index is used to obtain the associated file control
     410block.
    397411
    398412The file descriptor value is range checked.
    399413
    400 The file control block is examined to determine if it has write permissions to the
    401 file.
    402 
    403 A test is made to determine if the handler table that is referenced in the file
    404 control block contains an entry for the fdatasync() handler function. If it does not
    405 an error is returned to the calling routine.
    406 
    407 If the fdatasync() handler function exists, it is called with the file control block as
    408 its parameter.
     414The file control block is examined to determine if it has write
     415permissions to the file.
     416
     417A test is made to determine if the handler table that is referenced in the
     418file control block contains an entry for the fdatasync() handler function.
     419If it does not an error is returned to the calling routine.
     420
     421If the fdatasync() handler function exists, it is called with the file
     422control block as its parameter.
    409423
    410424@c @page
     
    431445@end itemize
    432446
    433 When a filesystem is mounted, a set of constants is specified for the filesystem.
    434 These constants are stored with the mount table entry for the filesystem. These
    435 constants appear in the POSIX standard and are listed below.
     447When a filesystem is mounted, a set of constants is specified for the
     448filesystem.  These constants are stored with the mount table entry for the
     449filesystem. These constants appear in the POSIX standard and are listed
     450below.
    436451
    437452@itemize @bullet
     
    464479@end itemize
    465480
    466 This routine will find the mount table information associated the file control block
    467 for the specified file descriptor parameter. The mount table entry structure
    468 contains a set of filesystem specific constants that can be accessed by individual
    469 identifiers.
    470 
    471 @subheading Development Comments:
    472 
    473 The routine will test to see if the file descriptor index is associated with a network
    474 connection. If it is, an error is returned from this routine.
    475 
    476 The file descriptor index is used to obtain the associated file control block.
     481This routine will find the mount table information associated the file
     482control block for the specified file descriptor parameter. The mount table
     483entry structure contains a set of filesystem specific constants that can
     484be accessed by individual identifiers.
     485
     486@subheading Development Comments:
     487
     488The routine will test to see if the file descriptor index is associated
     489with a network connection. If it is, an error is returned from this
     490routine.
     491
     492The file descriptor index is used to obtain the associated file control
     493block.
    477494
    478495The file descriptor value is range checked.
    479496
    480 The file control block is examined to determine if it has read permissions to the
    481 file.
    482 
    483 Pathinfo in the file control block is used to locate the mount table entry for the
    484 filesystem associated with the file descriptor.
    485 
    486 The mount table entry contains the pathconf_limits_and_options element. This
    487 element is a table of constants that is associated with the filesystem.
    488 
    489 The name argument is used to reference the desired constant from the
     497The file control block is examined to determine if it has read permissions
     498to the file.
     499
     500Pathinfo in the file control block is used to locate the mount table entry
     501for the filesystem associated with the file descriptor.
     502
     503The mount table entry contains the pathconf_limits_and_options element.
     504This element is a table of constants that is associated with the
     505filesystem.
     506
     507The name argument is used to reference the desired constant from the
    490508pathconf_limits_and_options table.
    491509
     
    500518@subheading Processing:
    501519
    502 This routine will return information concerning a file or network connection. If
    503 the file descriptor is associated with a network connection, the current
    504 implementation of fstat() will return a mode set to S_IFSOCK. In a later version,
    505 this routine will map the status of a network connection to an external handler
    506 routine.
    507 
    508 If the file descriptor is associated with a node under a filesystem, the fstat()
    509 routine will map to the fstat() function taken from the node handler table.
    510 
    511 @subheading Development Comments:
    512 
    513 This routine validates that the struct stat pointer is not NULL so that the return
    514 location is valid.
     520This routine will return information concerning a file or network
     521connection. If the file descriptor is associated with a network
     522connection, the current implementation of @code{fstat()} will return a
     523mode set to @code{S_IFSOCK}. In a later version, this routine will map the
     524status of a network connection to an external handler routine.
     525
     526If the file descriptor is associated with a node under a filesystem, the
     527fstat()  routine will map to the fstat() function taken from the node
     528handler table.
     529
     530@subheading Development Comments:
     531
     532This routine validates that the struct stat pointer is not NULL so that
     533the return location is valid.
    515534
    516535The struct stat is then initialized to all zeros.
    517536
    518 Rtems_file_descriptor_type() is then used to determine if the file descriptor is
    519 associated with a network connection. If it is, network status processing is
    520 performed. In the current implementation, the file descriptor type processing
    521 needs to be improved. It currently just drops into the normal processing for file
    522 system nodes.
    523 
    524 If the file descriptor is associated with a node under a filesystem, the following
    525 steps are performed:
     537rtems_file_descriptor_type() is then used to determine if the file
     538descriptor is associated with a network connection. If it is, network
     539status processing is performed. In the current implementation, the file
     540descriptor type processing needs to be improved. It currently just drops
     541into the normal processing for file system nodes.
     542
     543If the file descriptor is associated with a node under a filesystem, the
     544following steps are performed:
    526545
    527546@enumerate
     
    532551@item Range check the file descriptor index.
    533552
    534 @item Test to see if there is a non-NULL function pointer in the handler table
    535 for the fstat() function. If there is, invoke the function with the file
    536 control block and the pointer to the stat structure.
     553@item Test to see if there is a non-NULL function pointer in the handler
     554table for the fstat() function. If there is, invoke the function with the
     555file control block and the pointer to the stat structure.
    537556
    538557@end enumerate
     
    547566@subheading Processing:
    548567
    549 Not defined in the POSIX 1003.1b standard but commonly supported in most
    550 UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine is
    551 layered on external network handlers and filesystem specific handlers. The
    552 development of new filesystems should not alter the basic processing performed
    553 by this routine.
    554 
    555 @subheading Development Comments:
    556 
    557 
    558 The file descriptor is examined to determine if it is associated with a network
    559 device. If it is processing is mapped to an external network handler. The value
    560 returned by this handler is then returned to the calling program.
    561 
    562 File descriptors that are associated with a filesystem undergo the following
    563 processing:
     568Not defined in the POSIX 1003.1b standard but commonly supported in most
     569UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine
     570is layered on external network handlers and filesystem specific handlers.
     571The development of new filesystems should not alter the basic processing
     572performed by this routine.
     573
     574@subheading Development Comments:
     575
     576
     577The file descriptor is examined to determine if it is associated with a
     578network device. If it is processing is mapped to an external network
     579handler. The value returned by this handler is then returned to the
     580calling program.
     581
     582File descriptors that are associated with a filesystem undergo the
     583following processing:
    564584
    565585@enumerate
    566586
    567 @item The file descriptor index is used to obtain the associated file control block.
     587@item The file descriptor index is used to obtain the associated file
     588control block.
    568589
    569590@item The file descriptor value is range checked.
    570591
    571 @item A test is made to determine if the handler table that is referenced in the file
    572 control block contains an entry for the ioctl() handler function. If it does
    573 not, an error is returned to the calling routine.
    574 
    575 @item If the ioctl() handler function exists, it is called with the file control block,
    576 the command and buffer as its parameters.
    577 
    578 @item The return code from this function is then sent to the calling routine.
     592@item A test is made to determine if the handler table that is referenced
     593in the file control block contains an entry for the ioctl() handler
     594function. If it does not, an error is returned to the calling routine.
     595
     596@item If the ioctl() handler function exists, it is called with the file
     597control block, the command and buffer as its parameters.
     598
     599@item The return code from this function is then sent to the calling
     600routine.
    579601
    580602@end enumerate
     
    590612@subheading Processing:
    591613
    592 This routine will establish a hard link to a file, directory or a device. The target of
    593 the hard link must be in the same filesystem as the new link being created. A link
    594 to an existing link is also permitted but the existing link is evaluated before the
    595 new link is made. This implies that links to links are reduced to links to files,
    596 directories or devices before they are made.
     614This routine will establish a hard link to a file, directory or a device.
     615The target of the hard link must be in the same filesystem as the new link
     616being created. A link to an existing link is also permitted but the
     617existing link is evaluated before the new link is made. This implies that
     618links to links are reduced to links to files, directories or devices
     619before they are made.
    597620
    598621@subheading Development Comments:
     
    602625    const char   *new
    603626
    604 Link() will determine if the target of the link actually exists using
     627link() will determine if the target of the link actually exists using
    605628rtems_filesystem_evaluate_path()
    606629
    607 Rtems_filesystem_get_start_loc() is used to determine where to start the path
    608 evaluation of the new name. This macro examines the first characters of the name
    609 to see if the name of the new link starts with a rtems_filesystem_is_separator. If it
    610 does the search starts from the root of the RTEMS filesystem; otherwise the
    611 search will start from the current directory.
    612 
    613 The OPS table evalformake() function for the parent's filesystem is used to
    614 locate the node that will be the parent of the new link. It will also locate the start
    615 of the new path's name. This name will be used to define a child under the parent
     630rtems_filesystem_get_start_loc() is used to determine where to start the
     631path evaluation of the new name. This macro examines the first characters
     632of the name to see if the name of the new link starts with a
     633rtems_filesystem_is_separator. If it does the search starts from the root
     634of the RTEMS filesystem; otherwise the search will start from the current
    616635directory.
    617636
    618 If the parent is found, the routine will determine if the hard link that we are trying
    619 to create will cross a filesystem boundary. This is not permitted for hard-links.
    620 
    621 If the hard-link does not cross a filesystem boundary, a check is performed to
    622 determine if the OPS table contains an entry for the link() function.
    623 
    624 If a link() function is defined, the OPS table link() function will be called to
    625 establish the actual link within the filesystem.
    626 
    627 The return code from the OPS table link() function is returned to the calling
    628 program.
     637The OPS table evalformake() function for the parent's filesystem is used
     638to locate the node that will be the parent of the new link. It will also
     639locate the start of the new path's name. This name will be used to define
     640a child under the parent directory.
     641
     642If the parent is found, the routine will determine if the hard link that
     643we are trying to create will cross a filesystem boundary. This is not
     644permitted for hard-links.
     645
     646If the hard-link does not cross a filesystem boundary, a check is
     647performed to determine if the OPS table contains an entry for the link()
     648function.
     649
     650If a link() function is defined, the OPS table link() function will be
     651called to establish the actual link within the filesystem.
     652
     653The return code from the OPS table link() function is returned to the
     654calling program.
    629655
    630656@c @page
     
    637663@subheading Processing:
    638664
    639 This routine is layered on both external handlers and filesystem / node type
    640 specific handlers. This routine should allow for the support of new filesystems
    641 without modification.
    642 
    643 @subheading Development Comments:
    644 
    645 This routine will determine if the file descriptor is associated with a network
    646 device. If it is lseek will map to an external network handler. The handler will be
    647 called with the file descriptor, offset and whence as its calling parameters. The
    648 return code from the external handler will be returned to the calling routine.
    649 
    650 If the file descriptor is not associated with a network connection, it is associated
    651 with a node in a filesystem. The following steps will be performed for filesystem nodes:
     665This routine is layered on both external handlers and filesystem / node
     666type specific handlers. This routine should allow for the support of new
     667filesystems without modification.
     668
     669@subheading Development Comments:
     670
     671This routine will determine if the file descriptor is associated with a
     672network device. If it is lseek will map to an external network handler.
     673The handler will be called with the file descriptor, offset and whence as
     674its calling parameters. The return code from the external handler will be
     675returned to the calling routine.
     676
     677If the file descriptor is not associated with a network connection, it is
     678associated with a node in a filesystem. The following steps will be
     679performed for filesystem nodes:
    652680
    653681@enumerate
    654682
    655 @item The file descriptor is used to obtain the file control block for the node.
     683@item The file descriptor is used to obtain the file control block for the
     684node.
    656685
    657686@item The file descriptor is range checked.
    658687
    659 @item The offset element of the file control block is altered as indicated by
    660 the offset and whence calling parameters
    661 
    662 @item The handler table in the file control block is examined to determine if
    663 it contains an entry for the lseek() function. If it does not an error is
    664 returned to the calling program.
    665 
    666 @item The lseek() function from the designated handler table is called with
    667 the file control block, offset and whence as calling arguments
    668 
    669 @item The return code from the lseek() handler function is returned to the 
     688@item The offset element of the file control block is altered as indicated
     689by the offset and whence calling parameters
     690
     691@item The handler table in the file control block is examined to determine
     692if it contains an entry for the lseek() function. If it does not an error
     693is returned to the calling program.
     694
     695@item The lseek() function from the designated handler table is called
     696with the file control block, offset and whence as calling arguments
     697
     698@item The return code from the lseek() handler function is returned to the
    670699calling program
    671700
     
    682711@subheading Processing:
    683712
    684 This routine attempts to create a directory node under the filesystem. The routine
    685 is layered the mknod() function.
     713This routine attempts to create a directory node under the filesystem. The
     714routine is layered the mknod() function.
    686715
    687716@subheading Development Comments:
     
    698727@subheading Processing:
    699728
    700 This routine attempts to create a FIFO node under the filesystem. The routine is
    701 layered the mknod() function.
     729This routine attempts to create a FIFO node under the filesystem. The
     730routine is layered the mknod() function.
    702731
    703732@subheading Development Comments:
     
    714743@subheading Processing:
    715744
    716 This function will allow for the creation of the following types of nodes under the
    717 filesystem:
     745This function will allow for the creation of the following types of nodes
     746under the filesystem:
    718747
    719748@itemize @bullet
     
    731760@end itemize
    732761
    733 At the present time, an attempt to create a FIFO will result in an ENOTSUP error
    734 to the calling function. This routine is layered the filesystem specific routines
    735 evalformake and mknod. The introduction of a new filesystem must include its
    736 own evalformake and mknod function to support the generic mknod() function.
    737 Under this condition the generic mknod() function should accommodate other
    738 filesystem types without alteration.
    739 
    740 @subheading Development Comments:
    741 
    742 Test for nodal types - I thought that this test should look like the following code:
     762At the present time, an attempt to create a FIFO will result in an ENOTSUP
     763error to the calling function. This routine is layered the filesystem
     764specific routines evalformake and mknod. The introduction of a new
     765filesystem must include its own evalformake and mknod function to support
     766the generic mknod() function.  Under this condition the generic mknod()
     767function should accommodate other filesystem types without alteration.
     768
     769@subheading Development Comments:
     770
     771Test for nodal types - I thought that this test should look like the
     772following code:
    743773
    744774@example
     
    761791@end itemize
    762792
    763 Determine if the pathname that we are trying to create starts at the root directory
    764 or is relative to the current directory using the rtems_filesystem_get_start_loc()
    765 function.
    766 
    767 Determine if the pathname leads to a valid directory that can be accessed for the
    768 creation of a node.
    769 
    770 If the pathname is a valid location to create a node, verify that a filesystem
    771 specific mknod() function exists.
    772 
    773 If the mknod() function exists, call the filesystem specific mknod() function.
    774 Pass the name, mode, device type and the location information associated with the
    775 directory under which the node will be created.
     793Determine if the pathname that we are trying to create starts at the root
     794directory or is relative to the current directory using the
     795rtems_filesystem_get_start_loc()  function.
     796
     797Determine if the pathname leads to a valid directory that can be accessed
     798for the creation of a node.
     799
     800If the pathname is a valid location to create a node, verify that a
     801filesystem specific mknod() function exists.
     802
     803If the mknod() function exists, call the filesystem specific mknod()
     804function.  Pass the name, mode, device type and the location information
     805associated with the directory under which the node will be created.
    776806
    777807@c @page
     
    785815Arguments (Not a standard POSIX call):
    786816
    787 Rtems_filesystem_mount_table_entry_t   **mt_entry,
    788 
    789 If the mount operation is successful, this pointer to a pointer will be set to
    790 reference the mount table chain entry that has been allocated for this file
    791 system mount.
     817rtems_filesystem_mount_table_entry_t   **mt_entry,
     818
     819If the mount operation is successful, this pointer to a pointer will be
     820set to reference the mount table chain entry that has been allocated for
     821this file system mount.
    792822
    793823rtems_filesystem_operations_table   *fs_ops,
    794824
    795 This is a pointer to a table of functions that are associated with the file
    796 system that we are about to mount. This is the mechanism to selected file
    797 system type without keeping a dynamic database of all possible file
    798 system types that are valid for the mount operation. Using this method, it
    799 is only necessary to configure the filesystems that we wish to use into the
    800 RTEMS build. Unused filesystems types will not be drawn into the build.
     825This is a pointer to a table of functions that are associated with the
     826file system that we are about to mount. This is the mechanism to selected
     827file system type without keeping a dynamic database of all possible file
     828system types that are valid for the mount operation. Using this method, it
     829is only necessary to configure the filesystems that we wish to use into
     830the RTEMS build. Unused filesystems types will not be drawn into the
     831build.
    801832
    802833char                      *fsoptions,
    803834
    804 This argument points to a string that selects mounting for read only access
    805 or read/write access. Valid states are "RO" and "RW"
     835This argument points to a string that selects mounting for read only
     836access or read/write access. Valid states are "RO" and "RW"
    806837
    807838char                      *device,
    808839
    809 This argument is reserved for the name of a device that will be used to
    810 access the filesystem information. Current filesystem implementations
    811 are memory based and do not require a device to access filesystem
    812 information.
     840This argument is reserved for the name of a device that will be used to
     841access the filesystem information. Current filesystem implementations are
     842memory based and do not require a device to access filesystem information.
    813843
    814844char                      *mount_point
    815845
    816 This is a pathname to a directory in a currently mounted filesystem that
    817 allows read, write and execute permissions.  If successful, the node
    818 found by evaluating this name, is stored in the mt_entry.
    819 
    820 @subheading Processing:
    821 
    822 This routine will handle the mounting of a filesystem on a mount point. If the
    823 operation is successful, a pointer to the mount table chain entry associated with
    824 the mounted filesystem will be returned to the calling function. The specifics
    825 about the processing required at the mount point and within the filesystem being
    826 mounted is isolated in the filesystem specific mount() and fsmount_me()
    827 functions. This allows the generic mount() function to remain unaltered even if
    828 new filesystem types are introduced.
    829 
    830 
    831 
    832 @subheading Development Comments:
    833 
    834 This routine will use get_file_system_options() to determine if the mount options
    835 are valid ("RO" or "RW").
     846This is a pathname to a directory in a currently mounted filesystem that
     847allows read, write and execute permissions.  If successful, the node found
     848by evaluating this name, is stored in the mt_entry.
     849
     850@subheading Processing:
     851
     852This routine will handle the mounting of a filesystem on a mount point. If
     853the operation is successful, a pointer to the mount table chain entry
     854associated with the mounted filesystem will be returned to the calling
     855function. The specifics about the processing required at the mount point
     856and within the filesystem being mounted is isolated in the filesystem
     857specific mount() and fsmount_me()  functions. This allows the generic
     858mount() function to remain unaltered even if new filesystem types are
     859introduced.
     860
     861
     862
     863@subheading Development Comments:
     864
     865This routine will use get_file_system_options() to determine if the mount
     866options are valid ("RO" or "RW").
    836867
    837868It confirms that a filesystem ops-table has been selected.
    838869
    839 Space is allocated for a mount table entry and selective elements of the temporary
    840 mount table entry are initialized.
    841 
    842 If a mount point is specified:
    843 The mount point is examined to determine that it is a directory and also
    844 has the appropriate permissions to allow a filesystem to be mounted.
    845 
    846 The current mount table chain is searched to determine that there is not
    847 another filesystem mounted at the mount point we are trying to mount
    848 onto.
    849 
    850 If a mount function is defined in the ops table for the filesystem
    851 containing the mount point, it is called at this time.
    852 
    853 If no mount point is specified:
    854 Processing if performed to set up the mount table chain entry as the base
     870Space is allocated for a mount table entry and selective elements of the
     871temporary mount table entry are initialized.
     872
     873If a mount point is specified: The mount point is examined to determine
     874that it is a directory and also has the appropriate permissions to allow a
     875filesystem to be mounted.
     876
     877The current mount table chain is searched to determine that there is not
     878another filesystem mounted at the mount point we are trying to mount onto.
     879
     880If a mount function is defined in the ops table for the filesystem
     881containing the mount point, it is called at this time.
     882
     883If no mount point is specified: Processing if performed to set up the
     884mount table chain entry as the base filesystem.
     885
     886If the fsmount_me() function is specified for ops-table of the filesystem
     887being mounted, that function is called to initialize for the new
    855888filesystem.
    856889
    857 If the fsmount_me() function is specified for ops-table of the filesystem being
    858 mounted, that function is called to initialize for the new filesystem.
    859 
    860 On successful completion, the temporary mount table entry will be placed on the
    861 mount table chain to record the presence of the mounted filesystem.
     890On successful completion, the temporary mount table entry will be placed
     891on the mount table chain to record the presence of the mounted filesystem.
    862892
    863893@c @page
     
    870900@subheading Processing:
    871901
    872 This routine is layered on both RTEMS calls and filesystem specific
    873 implementations of the open() function. These functional interfaces should not
    874 change for new filesystems and therefore this code should be stable as new file
    875 systems are introduced.
    876 
    877 @subheading Development Comments:
    878 
    879 This routine will allocate a file control block for the file or device that we are
    880 about to open.
    881 
    882 It will then test to see if the pathname exists. If it does a
    883 rtems_filesystem_location_info_t data structure will be filled out. This structure
    884 contains information that associates node information, filesystem specific
    885 functions and mount table chain information with the pathname.
    886 
    887 If the create option has been it will attempt to create a node for a regular file along
    888 the specified path. If a file already exists along this path, an error will be
    889 generated; otherwise, a node will be allocated for the file under the filesystem
    890 that contains the pathname. When a new node is created, it is also evaluated so
    891 that an appropriate rtems_filesystem_location_info_t data structure can be filled
    892 out for the newly created node.
    893 
    894 If the file exists or the new file was created successfully, the file control block
    895 structure will be initialized with handler table information, node information and
    896 the rtems_filesystem_location_info_t data structure that describes the node and
    897 filesystem data in detail.
    898 
    899 If an open() function exists in the filesystem specific handlers table for the node
    900 that we are trying to open, it will be called at this time.
    901 
    902 If any error is detected in the process, cleanup is performed. It consists of freeing
    903 the file control block structure that was allocated at the beginning of the generic
    904 open() routine.
    905 
    906 On a successful open(), the index into the file descriptor table will be calculated
    907 and returned to the calling routine.
     902This routine is layered on both RTEMS calls and filesystem specific
     903implementations of the open() function. These functional interfaces should
     904not change for new filesystems and therefore this code should be stable as
     905new file systems are introduced.
     906
     907@subheading Development Comments:
     908
     909This routine will allocate a file control block for the file or device
     910that we are about to open.
     911
     912It will then test to see if the pathname exists. If it does a
     913rtems_filesystem_location_info_t data structure will be filled out. This
     914structure contains information that associates node information,
     915filesystem specific functions and mount table chain information with the
     916pathname.
     917
     918If the create option has been it will attempt to create a node for a
     919regular file along the specified path. If a file already exists along this
     920path, an error will be generated; otherwise, a node will be allocated for
     921the file under the filesystem that contains the pathname. When a new node
     922is created, it is also evaluated so that an appropriate
     923rtems_filesystem_location_info_t data structure can be filled out for the
     924newly created node.
     925
     926If the file exists or the new file was created successfully, the file
     927control block structure will be initialized with handler table
     928information, node information and the rtems_filesystem_location_info_t
     929data structure that describes the node and filesystem data in detail.
     930
     931If an open() function exists in the filesystem specific handlers table for
     932the node that we are trying to open, it will be called at this time.
     933
     934If any error is detected in the process, cleanup is performed. It consists
     935of freeing the file control block structure that was allocated at the
     936beginning of the generic open() routine.
     937
     938On a successful open(), the index into the file descriptor table will be
     939calculated and returned to the calling routine.
    908940
    909941@c @page
     
    916948@subheading Processing:
    917949
    918 This routine will attempt to open a directory for read access. It will setup a DIR
    919 control structure that will be used to access directory information. This routine is
    920 layered on the generic open() routine and filesystem specific directory
    921 processing routines.
     950This routine will attempt to open a directory for read access. It will
     951setup a DIR control structure that will be used to access directory
     952information. This routine is layered on the generic open() routine and
     953filesystem specific directory processing routines.
    922954
    923955@subheading Development Comments:
     
    934966@subheading Processing:
    935967
    936 This routine will obtain the value of one of the path configuration parameters and
    937 return it to the calling routine. It is layered on the generic open() and fpathconf()
    938 functions. These interfaces should not change with the addition of new filesystem
    939 types.
    940 
    941 @subheading Development Comments:
    942 
    943 This routine will try to open the file indicated by path. 
    944 
    945 If successful, the file descriptor will be used to access the pathconf value specified
    946 by @code{name} using the fpathconf() function.
     968This routine will obtain the value of one of the path configuration
     969parameters and return it to the calling routine. It is layered on the
     970generic open() and fpathconf()  functions. These interfaces should not
     971change with the addition of new filesystem types.
     972
     973@subheading Development Comments:
     974
     975This routine will try to open the file indicated by path.
     976
     977If successful, the file descriptor will be used to access the pathconf
     978value specified by @code{name} using the fpathconf() function.
    947979
    948980The file that was accessed is then closed.
     
    957989@subheading Processing:
    958990
    959 This routine is layered on a set of RTEMS calls and filesystem specific read
    960 operations. The functions are layered in such a way as to isolate them from
    961 change as new filesystems are introduced.
     991This routine is layered on a set of RTEMS calls and filesystem specific
     992read operations. The functions are layered in such a way as to isolate
     993them from change as new filesystems are introduced.
    962994
    963995@subheading Development Comments:
     
    965997This routine will examine the type of file descriptor it is sent.
    966998
    967 If the file descriptor is associated with a network device, the read function will be
    968 mapped to a special network handler. The return code from the network handler
    969 will then be sent as the return code from generic read() function.
    970 
    971 For file descriptors that are associated with the filesystem the following sequence
    972 will be performed:
     999If the file descriptor is associated with a network device, the read
     1000function will be mapped to a special network handler. The return code from
     1001the network handler will then be sent as the return code from generic
     1002read() function.
     1003
     1004For file descriptors that are associated with the filesystem the following
     1005sequence will be performed:
    9731006
    9741007@enumerate
     
    9841017@item Check the file control block to see if we have permissions to read
    9851018
    986 @item If  there is a read function in the handler table, invoke the handler table
    987 read() function
    988 
    989 @item Use the return code from the handler table read function(number of 
     1019@item If there is a read function in the handler table, invoke the handler
     1020table read() function
     1021
     1022@item Use the return code from the handler table read function(number of
    9901023bytes read) to increment the offset element of the file control block
    9911024
     
    10011034readdir.c
    10021035
    1003 @subheading Processing:
    1004 
    1005 This routine was acquired from the BSD group. It has not been altered from its
    1006 original form.
    1007 
    1008 @subheading Development Comments:
    1009 
    1010 The routine calls a customized getdents() function that is provided by the user.
    1011 This routine provides the filesystem specific aspects of reading a directory.
    1012 
    1013 It is layered on the read() function in the directory handler table. This function
    1014 has been mapped to the Imfs_dir_read() function.
     1036@subheading Processing:
     1037
     1038This routine was acquired from the BSD group. It has not been altered from
     1039its original form.
     1040
     1041@subheading Development Comments:
     1042
     1043The routine calls a customized getdents() function that is provided by the
     1044user.  This routine provides the filesystem specific aspects of reading a
     1045directory.
     1046
     1047It is layered on the read() function in the directory handler table. This
     1048function has been mapped to the Imfs_dir_read() function.
    10151049
    10161050@c @page
     
    10231057@subheading Processing:
    10241058
    1025 This routine will attempt to dismount a mounted filesystem and then free all
    1026 resources that were allocated for the management of that filesystem.
     1059This routine will attempt to dismount a mounted filesystem and then free
     1060all resources that were allocated for the management of that filesystem.
    10271061
    10281062@subheading Development Comments:
     
    10301064@itemize @bullet
    10311065
    1032 @item This routine will determine if there are any filesystems currently mounted
    1033 under the filesystem that we are trying to dismount. This would prevent the
    1034 dismount of the filesystem.
    1035 
    1036 @item It will test to see if the current directory is in the filesystem that we are
    1037 attempting to dismount. This would prevent the dismount of the filesystem.
    1038 
    1039 @item It will scan all the currently open file descriptors to determine is there is an
    1040 open file descriptor to a file in the filesystem that we are attempting to
    1041 unmount().
     1066@item This routine will determine if there are any filesystems currently
     1067mounted under the filesystem that we are trying to dismount. This would
     1068prevent the dismount of the filesystem.
     1069
     1070@item It will test to see if the current directory is in the filesystem
     1071that we are attempting to dismount. This would prevent the dismount of the
     1072filesystem.
     1073
     1074@item It will scan all the currently open file descriptors to determine is
     1075there is an open file descriptor to a file in the filesystem that we are
     1076attempting to unmount().
    10421077
    10431078@end itemize
    10441079
    1045 If the above preconditions are met then the following sequence is performed:
     1080If the above preconditions are met then the following sequence is
     1081performed:
    10461082
    10471083@enumerate
    10481084
    1049 @item Call the filesystem specific unmount() function for the filesystem that
    1050 contains the mount point. This routine should indicate that the mount point
    1051 no longer has a filesystem mounted below it.
    1052 
    1053 @item Call the filesystem specific fsunmount_me() function for the mounted 
    1054 filesystem that we are trying to unmount(). This routine should clean up 
    1055 any resources that are no longer needed for the management of the file 
     1085@item Call the filesystem specific unmount() function for the filesystem
     1086that contains the mount point. This routine should indicate that the mount
     1087point no longer has a filesystem mounted below it.
     1088
     1089@item Call the filesystem specific fsunmount_me() function for the mounted
     1090filesystem that we are trying to unmount(). This routine should clean up
     1091any resources that are no longer needed for the management of the file
    10561092system being un-mounted.
    10571093
    1058 @item Extract the mount table entry for the filesystem that was just dismounted
    1059 from the mount table chain.
     1094@item Extract the mount table entry for the filesystem that was just
     1095dismounted from the mount table chain.
    10601096
    10611097@item Free the memory associated with the extracted mount table entry.
Note: See TracChangeset for help on using the changeset viewer.