diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/filesystem/syscalls.t | 754 |
1 files changed, 395 insertions, 359 deletions
diff --git a/doc/filesystem/syscalls.t b/doc/filesystem/syscalls.t index b0c07e2dc7..7651742c4e 100644 --- a/doc/filesystem/syscalls.t +++ b/doc/filesystem/syscalls.t @@ -42,7 +42,8 @@ been included as part of the application's interface. @item unmount() @end enumerate -The sections that follow provide developmental information concerning each of these functions. +The sections that follow provide developmental information concerning each +of these functions. @c @page @@ -54,16 +55,17 @@ access.c @subheading Processing: -This routine is layered on the stat() function. It acquires the current status -information for the specified file and then determines if the caller has the ability -to access the file for read, write or execute according to the mode argument to this -function. +This routine is layered on the stat() function. It acquires the current +status information for the specified file and then determines if the +caller has the ability to access the file for read, write or execute +according to the mode argument to this function. @subheading Development Comments: -This routine is layered on top of the stat() function. As long as the st_mode -element in the returned structure follow the standard UNIX conventions, this -function should support other filesystems without alteration. +This routine is layered on top of the stat() function. As long as the +st_mode element in the returned structure follow the standard UNIX +conventions, this function should support other filesystems without +alteration. @c @page @section chdir @@ -75,20 +77,21 @@ chdir.c @subheading Processing: -This routine will determine if the pathname that we are attempting to make that -current directory exists and is in fact a directory. If these conditions are met the -global indication of the current directory (rtems_filesystem_current) is set to the -rtems_filesystem_location_info_t structure that is returned by the -rtems_filesystem_evaluate_path() routine. +This routine will determine if the pathname that we are attempting to make +that current directory exists and is in fact a directory. If these +conditions are met the global indication of the current directory +(rtems_filesystem_current) is set to the rtems_filesystem_location_info_t +structure that is returned by the rtems_filesystem_evaluate_path() +routine. @subheading Development Comments: -This routine is layered on the rtems_filesystem_evaluate_path() routine and the -filesystem specific OP table function node_type(). +This routine is layered on the rtems_filesystem_evaluate_path() routine +and the filesystem specific OP table function node_type(). -The routine node_type() must be a routine provided for each filesystem since it -must access the filesystems node information to determine which of the -following types the node is: +The routine node_type() must be a routine provided for each filesystem +since it must access the filesystems node information to determine which +of the following types the node is: @itemize @bullet @item RTEMS_FILESYSTEM_DIRECTORY @@ -97,15 +100,16 @@ following types the node is: @item RTEMS_FILESYSTEM_MEMORY_FILE @end itemize -This acknowledges that the form of the node management information can vary -from one filesystem implementation to another. +This acknowledges that the form of the node management information can +vary from one filesystem implementation to another. -RTEMS has a special global structure that maintains the current directory -location. This global variable is of type rtems_filesystem_location_info_t and is -called rtems_filesystem_current. This structure is not always valid. In order to -determine if the structure is valid, you must first test the node_access element of -this structure. If the pointer is NULL, then the structure does not contain a valid -indication of what the current directory is. +RTEMS has a special global structure that maintains the current directory +location. This global variable is of type rtems_filesystem_location_info_t +and is called rtems_filesystem_current. This structure is not always +valid. In order to determine if the structure is valid, you must first +test the node_access element of this structure. If the pointer is NULL, +then the structure does not contain a valid indication of what the current +directory is. @c @page @section chmod @@ -116,18 +120,18 @@ chmod.c @subheading Processing: -This routine is layered on the open(), fchmod() and close() functions. As long as -the standard interpretation of the mode_t value is maintained, this routine should -not need modification to support other filesystems. +This routine is layered on the open(), fchmod() and close() functions. As +long as the standard interpretation of the mode_t value is maintained, +this routine should not need modification to support other filesystems. @subheading Development Comments: -The routine first determines if the selected file can be open with read/write access. -This is required to allow modification of the mode associated with the selected -path. +The routine first determines if the selected file can be open with +read/write access. This is required to allow modification of the mode +associated with the selected path. -The fchmod() function is used to actually change the mode of the path using the -integer file descriptor returned by the open() function. +The fchmod() function is used to actually change the mode of the path +using the integer file descriptor returned by the open() function. After mode modification, the open file descriptor is closed. @@ -140,24 +144,25 @@ chown.c @subheading Processing: -This routine is layered on the rtems_filesystem_evaluate_path() and the file -system specific chown() routine that is specified in the OPS table for the file -system. +This routine is layered on the rtems_filesystem_evaluate_path() and the +file system specific chown() routine that is specified in the OPS table +for the file system. @subheading Development Comments: -rtems_filesystem_evaluate_path() is used to determine if the path specified -actually exists. If it does a rtems_filesystem_location_info_t structure will be -obtained that allows the shell function to locate the OPS table that is to be used -for this filesystem. +rtems_filesystem_evaluate_path() is used to determine if the path +specified actually exists. If it does a rtems_filesystem_location_info_t +structure will be obtained that allows the shell function to locate the +OPS table that is to be used for this filesystem. -It is possible that the chown() function that should be in the OPS table is not -defined. A test for a non-NULL OPS table chown() entry is performed before the -function is called. +It is possible that the chown() function that should be in the OPS table +is not defined. A test for a non-NULL OPS table chown() entry is performed +before the function is called. -If the chown() function is defined in the indicated OPS table, the function is -called with the rtems_filesystem_location_info_t structure returned from the path -evaluation routine, the desired owner, and group information. +If the chown() function is defined in the indicated OPS table, the +function is called with the rtems_filesystem_location_info_t structure +returned from the path evaluation routine, the desired owner, and group +information. @c @page @section close @@ -168,52 +173,53 @@ close.c @subheading Processing: -This routine will allow for the closing of both network connections and file -system devices. If the file descriptor is associated with a network device, the -appropriate network function handler will be selected from a table of previously -registered network functions (rtems_libio_handlers) and that function will be -invoked. +This routine will allow for the closing of both network connections and +file system devices. If the file descriptor is associated with a network +device, the appropriate network function handler will be selected from a +table of previously registered network functions (rtems_libio_handlers) +and that function will be invoked. -If the file descriptor refers to an entry in the filesystem, the appropriate handler -will be selected using information that has been placed in the file control block for -the device (rtems_libio_t structure). +If the file descriptor refers to an entry in the filesystem, the +appropriate handler will be selected using information that has been +placed in the file control block for the device (rtems_libio_t structure). @subheading Development Comments: -rtems_file_descriptor_type examines some of the upper bits of the file descriptor -index. If it finds that the upper bits are set in the file descriptor index, the device -referenced is a network device. +rtems_file_descriptor_type examines some of the upper bits of the file +descriptor index. If it finds that the upper bits are set in the file +descriptor index, the device referenced is a network device. -Network device handlers are obtained from a special registration table -(rtems_libio_handlers) that is set up during network initialization. The network -handler invoked and the status of the network handler will be returned to the -calling process. +Network device handlers are obtained from a special registration table +(rtems_libio_handlers) that is set up during network initialization. The +network handler invoked and the status of the network handler will be +returned to the calling process. -If none of the upper bits are set in the file descriptor index, the file descriptor -refers to an element of the RTEMS filesystem. +If none of the upper bits are set in the file descriptor index, the file +descriptor refers to an element of the RTEMS filesystem. -The following sequence will be performed for any filesystem file descriptor: +The following sequence will be performed for any filesystem file +descriptor: @enumerate -@item Use the rtems_libio_iop() function to obtain the rtems_libio_t structure for the -file descriptor +@item Use the rtems_libio_iop() function to obtain the rtems_libio_t +structure for the file descriptor @item Range check the file descriptor using rtems_libio_check_fd() -@item Determine if there is actually a function in the selected handler table that -processes the close() operation for the filesystem and node type selected. -This is generally done to avoid execution attempts on functions that have not -been implemented. +@item Determine if there is actually a function in the selected handler +table that processes the close() operation for the filesystem and node +type selected. This is generally done to avoid execution attempts on +functions that have not been implemented. -@item If the function has been defined it is invoked with the file control block -pointer as its argument. +@item If the function has been defined it is invoked with the file control +block pointer as its argument. -@item The file control block that was associated with the open file descriptor is -marked as free using rtems_libio_free(). +@item The file control block that was associated with the open file +descriptor is marked as free using rtems_libio_free(). -@item The return code from the close handler is then passed back to the calling -program. +@item The return code from the close handler is then passed back to the +calling program. @end enumerate @@ -226,19 +232,20 @@ closedir.c @subheading Processing: -The code was obtained from the BSD group. This routine must clean up the -memory resources that are required to track an open directory. The code is layered -on the close() function and standard memory free() functions. It should not -require alterations to support other filesystems. +The code was obtained from the BSD group. This routine must clean up the +memory resources that are required to track an open directory. The code is +layered on the close() function and standard memory free() functions. It +should not require alterations to support other filesystems. @subheading Development Comments: -The routine alters the file descriptor and the index into the DIR structure to make -it an invalid file descriptor. Apparently the memory that is about to be freed may -still be referenced before it is reallocated. +The routine alters the file descriptor and the index into the DIR +structure to make it an invalid file descriptor. Apparently the memory +that is about to be freed may still be referenced before it is +reallocated. -The dd_buf structure's memory is reallocated before the control structure that -contains the pointer to the dd_buf region. +The dd_buf structure's memory is reallocated before the control structure +that contains the pointer to the dd_buf region. DIR control memory is reallocated. @@ -287,8 +294,8 @@ fchmod.c @subheading Processing: -This routine will alter the permissions of a node in a filesystem. It is layered on -the following functions and macros: +This routine will alter the permissions of a node in a filesystem. It is +layered on the following functions and macros: @itemize @bullet @item rtems_file_descriptor_type() @@ -299,28 +306,31 @@ the following functions and macros: @item rtems_libio_check_permissions() -@item fchmod() function that is referenced by the handler table in the file control block associated with this file descriptor +@item fchmod() function that is referenced by the handler table in the +file control block associated with this file descriptor @end itemize @subheading Development Comments: -The routine will test to see if the file descriptor index is associated with a network -connection. If it is, an error is returned from this routine. +The routine will test to see if the file descriptor index is associated +with a network connection. If it is, an error is returned from this +routine. -The file descriptor index is used to obtain the associated file control block. +The file descriptor index is used to obtain the associated file control +block. The file descriptor value is range checked. -The file control block is examined to determine if it has write permissions to -allow us to alter the mode of the file. +The file control block is examined to determine if it has write +permissions to allow us to alter the mode of the file. -A test is made to determine if the handler table that is referenced in the file -control block contains an entry for the fchmod() handler function. If it does not, -an error is returned to the calling routine. +A test is made to determine if the handler table that is referenced in the +file control block contains an entry for the fchmod() handler function. If +it does not, an error is returned to the calling routine. -If the fchmod() handler function exists, it is called with the file control block and -the desired mode as parameters. +If the fchmod() handler function exists, it is called with the file +control block and the desired mode as parameters. @c @page @section fcntl() @@ -331,27 +341,28 @@ fcntl.c @subheading Processing: -This routine currently only interacts with the file control block. If the structure of -the file control block and the associated meanings do not change, the partial -implementation of fcntl() should remain unaltered for other filesystem -implementations. +This routine currently only interacts with the file control block. If the +structure of the file control block and the associated meanings do not +change, the partial implementation of fcntl() should remain unaltered for +other filesystem implementations. @subheading Development Comments: -The only commands that have been implemented are the F_GETFD and -F_SETFD. The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC -bit in the @code{flags} element of the file control block associated with the file +The only commands that have been implemented are the F_GETFD and F_SETFD. +The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the +@code{flags} element of the file control block associated with the file descriptor index. -The current implementation of the function performs the sequence of operations -below: +The current implementation of the function performs the sequence of +operations below: @enumerate -@item Test to see if we are trying to operate on a file descriptor associated with a -network connection +@item Test to see if we are trying to operate on a file descriptor +associated with a network connection -@item Obtain the file control block that is associated with the file descriptor index +@item Obtain the file control block that is associated with the file +descriptor index @item Perform a range check on the file descriptor index. @@ -384,28 +395,31 @@ disk. It is layered on the following functions and macros: @item rtems_libio_check_permissions() -@item fdatasync() function that is referenced by the handler table in the file control block associated with this file descriptor +@item fdatasync() function that is referenced by the handler table in the +file control block associated with this file descriptor @end itemize @subheading Development Comments: -The routine will test to see if the file descriptor index is associated with a network -connection. If it is, an error is returned from this routine. +The routine will test to see if the file descriptor index is associated +with a network connection. If it is, an error is returned from this +routine. -The file descriptor index is used to obtain the associated file control block. +The file descriptor index is used to obtain the associated file control +block. The file descriptor value is range checked. -The file control block is examined to determine if it has write permissions to the -file. +The file control block is examined to determine if it has write +permissions to the file. -A test is made to determine if the handler table that is referenced in the file -control block contains an entry for the fdatasync() handler function. If it does not -an error is returned to the calling routine. +A test is made to determine if the handler table that is referenced in the +file control block contains an entry for the fdatasync() handler function. +If it does not an error is returned to the calling routine. -If the fdatasync() handler function exists, it is called with the file control block as -its parameter. +If the fdatasync() handler function exists, it is called with the file +control block as its parameter. @c @page @section fpathconf @@ -430,9 +444,10 @@ This routine is layered on the following functions and macros: @end itemize -When a filesystem is mounted, a set of constants is specified for the filesystem. -These constants are stored with the mount table entry for the filesystem. These -constants appear in the POSIX standard and are listed below. +When a filesystem is mounted, a set of constants is specified for the +filesystem. These constants are stored with the mount table entry for the +filesystem. These constants appear in the POSIX standard and are listed +below. @itemize @bullet @@ -463,30 +478,33 @@ constants appear in the POSIX standard and are listed below. @end itemize -This routine will find the mount table information associated the file control block -for the specified file descriptor parameter. The mount table entry structure -contains a set of filesystem specific constants that can be accessed by individual -identifiers. +This routine will find the mount table information associated the file +control block for the specified file descriptor parameter. The mount table +entry structure contains a set of filesystem specific constants that can +be accessed by individual identifiers. @subheading Development Comments: -The routine will test to see if the file descriptor index is associated with a network -connection. If it is, an error is returned from this routine. +The routine will test to see if the file descriptor index is associated +with a network connection. If it is, an error is returned from this +routine. -The file descriptor index is used to obtain the associated file control block. +The file descriptor index is used to obtain the associated file control +block. The file descriptor value is range checked. -The file control block is examined to determine if it has read permissions to the -file. +The file control block is examined to determine if it has read permissions +to the file. -Pathinfo in the file control block is used to locate the mount table entry for the -filesystem associated with the file descriptor. +Pathinfo in the file control block is used to locate the mount table entry +for the filesystem associated with the file descriptor. -The mount table entry contains the pathconf_limits_and_options element. This -element is a table of constants that is associated with the filesystem. +The mount table entry contains the pathconf_limits_and_options element. +This element is a table of constants that is associated with the +filesystem. -The name argument is used to reference the desired constant from the +The name argument is used to reference the desired constant from the pathconf_limits_and_options table. @@ -499,30 +517,31 @@ fstat.c @subheading Processing: -This routine will return information concerning a file or network connection. If -the file descriptor is associated with a network connection, the current -implementation of fstat() will return a mode set to S_IFSOCK. In a later version, -this routine will map the status of a network connection to an external handler -routine. +This routine will return information concerning a file or network +connection. If the file descriptor is associated with a network +connection, the current implementation of @code{fstat()} will return a +mode set to @code{S_IFSOCK}. In a later version, this routine will map the +status of a network connection to an external handler routine. -If the file descriptor is associated with a node under a filesystem, the fstat() -routine will map to the fstat() function taken from the node handler table. +If the file descriptor is associated with a node under a filesystem, the +fstat() routine will map to the fstat() function taken from the node +handler table. @subheading Development Comments: -This routine validates that the struct stat pointer is not NULL so that the return -location is valid. +This routine validates that the struct stat pointer is not NULL so that +the return location is valid. The struct stat is then initialized to all zeros. -Rtems_file_descriptor_type() is then used to determine if the file descriptor is -associated with a network connection. If it is, network status processing is -performed. In the current implementation, the file descriptor type processing -needs to be improved. It currently just drops into the normal processing for file -system nodes. +rtems_file_descriptor_type() is then used to determine if the file +descriptor is associated with a network connection. If it is, network +status processing is performed. In the current implementation, the file +descriptor type processing needs to be improved. It currently just drops +into the normal processing for file system nodes. -If the file descriptor is associated with a node under a filesystem, the following -steps are performed: +If the file descriptor is associated with a node under a filesystem, the +following steps are performed: @enumerate @@ -531,9 +550,9 @@ index. @item Range check the file descriptor index. -@item Test to see if there is a non-NULL function pointer in the handler table -for the fstat() function. If there is, invoke the function with the file -control block and the pointer to the stat structure. +@item Test to see if there is a non-NULL function pointer in the handler +table for the fstat() function. If there is, invoke the function with the +file control block and the pointer to the stat structure. @end enumerate @@ -546,36 +565,39 @@ ioctl.c @subheading Processing: -Not defined in the POSIX 1003.1b standard but commonly supported in most -UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine is -layered on external network handlers and filesystem specific handlers. The -development of new filesystems should not alter the basic processing performed -by this routine. +Not defined in the POSIX 1003.1b standard but commonly supported in most +UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine +is layered on external network handlers and filesystem specific handlers. +The development of new filesystems should not alter the basic processing +performed by this routine. @subheading Development Comments: -The file descriptor is examined to determine if it is associated with a network -device. If it is processing is mapped to an external network handler. The value -returned by this handler is then returned to the calling program. +The file descriptor is examined to determine if it is associated with a +network device. If it is processing is mapped to an external network +handler. The value returned by this handler is then returned to the +calling program. -File descriptors that are associated with a filesystem undergo the following -processing: +File descriptors that are associated with a filesystem undergo the +following processing: @enumerate -@item The file descriptor index is used to obtain the associated file control block. +@item The file descriptor index is used to obtain the associated file +control block. @item The file descriptor value is range checked. -@item A test is made to determine if the handler table that is referenced in the file -control block contains an entry for the ioctl() handler function. If it does -not, an error is returned to the calling routine. +@item A test is made to determine if the handler table that is referenced +in the file control block contains an entry for the ioctl() handler +function. If it does not, an error is returned to the calling routine. -@item If the ioctl() handler function exists, it is called with the file control block, -the command and buffer as its parameters. +@item If the ioctl() handler function exists, it is called with the file +control block, the command and buffer as its parameters. -@item The return code from this function is then sent to the calling routine. +@item The return code from this function is then sent to the calling +routine. @end enumerate @@ -589,11 +611,12 @@ link.c @subheading Processing: -This routine will establish a hard link to a file, directory or a device. The target of -the hard link must be in the same filesystem as the new link being created. A link -to an existing link is also permitted but the existing link is evaluated before the -new link is made. This implies that links to links are reduced to links to files, -directories or devices before they are made. +This routine will establish a hard link to a file, directory or a device. +The target of the hard link must be in the same filesystem as the new link +being created. A link to an existing link is also permitted but the +existing link is evaluated before the new link is made. This implies that +links to links are reduced to links to files, directories or devices +before they are made. @subheading Development Comments: @@ -601,31 +624,34 @@ Calling parameters: const char *existing const char *new -Link() will determine if the target of the link actually exists using +link() will determine if the target of the link actually exists using rtems_filesystem_evaluate_path() -Rtems_filesystem_get_start_loc() is used to determine where to start the path -evaluation of the new name. This macro examines the first characters of the name -to see if the name of the new link starts with a rtems_filesystem_is_separator. If it -does the search starts from the root of the RTEMS filesystem; otherwise the -search will start from the current directory. - -The OPS table evalformake() function for the parent's filesystem is used to -locate the node that will be the parent of the new link. It will also locate the start -of the new path's name. This name will be used to define a child under the parent +rtems_filesystem_get_start_loc() is used to determine where to start the +path evaluation of the new name. This macro examines the first characters +of the name to see if the name of the new link starts with a +rtems_filesystem_is_separator. If it does the search starts from the root +of the RTEMS filesystem; otherwise the search will start from the current directory. -If the parent is found, the routine will determine if the hard link that we are trying -to create will cross a filesystem boundary. This is not permitted for hard-links. +The OPS table evalformake() function for the parent's filesystem is used +to locate the node that will be the parent of the new link. It will also +locate the start of the new path's name. This name will be used to define +a child under the parent directory. -If the hard-link does not cross a filesystem boundary, a check is performed to -determine if the OPS table contains an entry for the link() function. +If the parent is found, the routine will determine if the hard link that +we are trying to create will cross a filesystem boundary. This is not +permitted for hard-links. -If a link() function is defined, the OPS table link() function will be called to -establish the actual link within the filesystem. +If the hard-link does not cross a filesystem boundary, a check is +performed to determine if the OPS table contains an entry for the link() +function. + +If a link() function is defined, the OPS table link() function will be +called to establish the actual link within the filesystem. -The return code from the OPS table link() function is returned to the calling -program. +The return code from the OPS table link() function is returned to the +calling program. @c @page @section lseek @@ -636,37 +662,40 @@ lseek.c @subheading Processing: -This routine is layered on both external handlers and filesystem / node type -specific handlers. This routine should allow for the support of new filesystems -without modification. +This routine is layered on both external handlers and filesystem / node +type specific handlers. This routine should allow for the support of new +filesystems without modification. @subheading Development Comments: -This routine will determine if the file descriptor is associated with a network -device. If it is lseek will map to an external network handler. The handler will be -called with the file descriptor, offset and whence as its calling parameters. The -return code from the external handler will be returned to the calling routine. +This routine will determine if the file descriptor is associated with a +network device. If it is lseek will map to an external network handler. +The handler will be called with the file descriptor, offset and whence as +its calling parameters. The return code from the external handler will be +returned to the calling routine. -If the file descriptor is not associated with a network connection, it is associated -with a node in a filesystem. The following steps will be performed for filesystem nodes: +If the file descriptor is not associated with a network connection, it is +associated with a node in a filesystem. The following steps will be +performed for filesystem nodes: @enumerate -@item The file descriptor is used to obtain the file control block for the node. +@item The file descriptor is used to obtain the file control block for the +node. @item The file descriptor is range checked. -@item The offset element of the file control block is altered as indicated by -the offset and whence calling parameters +@item The offset element of the file control block is altered as indicated +by the offset and whence calling parameters -@item The handler table in the file control block is examined to determine if -it contains an entry for the lseek() function. If it does not an error is -returned to the calling program. +@item The handler table in the file control block is examined to determine +if it contains an entry for the lseek() function. If it does not an error +is returned to the calling program. -@item The lseek() function from the designated handler table is called with -the file control block, offset and whence as calling arguments +@item The lseek() function from the designated handler table is called +with the file control block, offset and whence as calling arguments -@item The return code from the lseek() handler function is returned to the +@item The return code from the lseek() handler function is returned to the calling program @end enumerate @@ -681,8 +710,8 @@ mkdir.c @subheading Processing: -This routine attempts to create a directory node under the filesystem. The routine -is layered the mknod() function. +This routine attempts to create a directory node under the filesystem. The +routine is layered the mknod() function. @subheading Development Comments: @@ -697,8 +726,8 @@ mkfifo.c @subheading Processing: -This routine attempts to create a FIFO node under the filesystem. The routine is -layered the mknod() function. +This routine attempts to create a FIFO node under the filesystem. The +routine is layered the mknod() function. @subheading Development Comments: @@ -713,8 +742,8 @@ mknod.c @subheading Processing: -This function will allow for the creation of the following types of nodes under the -filesystem: +This function will allow for the creation of the following types of nodes +under the filesystem: @itemize @bullet @@ -730,16 +759,17 @@ filesystem: @end itemize -At the present time, an attempt to create a FIFO will result in an ENOTSUP error -to the calling function. This routine is layered the filesystem specific routines -evalformake and mknod. The introduction of a new filesystem must include its -own evalformake and mknod function to support the generic mknod() function. -Under this condition the generic mknod() function should accommodate other -filesystem types without alteration. +At the present time, an attempt to create a FIFO will result in an ENOTSUP +error to the calling function. This routine is layered the filesystem +specific routines evalformake and mknod. The introduction of a new +filesystem must include its own evalformake and mknod function to support +the generic mknod() function. Under this condition the generic mknod() +function should accommodate other filesystem types without alteration. @subheading Development Comments: -Test for nodal types - I thought that this test should look like the following code: +Test for nodal types - I thought that this test should look like the +following code: @example if ( (mode & S_IFDIR) = = S_IFDIR) || @@ -760,19 +790,19 @@ Where: @item S_IFIFO (0010000) - Creation of a FIFO @end itemize -Determine if the pathname that we are trying to create starts at the root directory -or is relative to the current directory using the rtems_filesystem_get_start_loc() -function. +Determine if the pathname that we are trying to create starts at the root +directory or is relative to the current directory using the +rtems_filesystem_get_start_loc() function. -Determine if the pathname leads to a valid directory that can be accessed for the -creation of a node. +Determine if the pathname leads to a valid directory that can be accessed +for the creation of a node. -If the pathname is a valid location to create a node, verify that a filesystem -specific mknod() function exists. +If the pathname is a valid location to create a node, verify that a +filesystem specific mknod() function exists. -If the mknod() function exists, call the filesystem specific mknod() function. -Pass the name, mode, device type and the location information associated with the -directory under which the node will be created. +If the mknod() function exists, call the filesystem specific mknod() +function. Pass the name, mode, device type and the location information +associated with the directory under which the node will be created. @c @page @section mount @@ -784,81 +814,81 @@ mount.c Arguments (Not a standard POSIX call): -Rtems_filesystem_mount_table_entry_t **mt_entry, +rtems_filesystem_mount_table_entry_t **mt_entry, -If the mount operation is successful, this pointer to a pointer will be set to -reference the mount table chain entry that has been allocated for this file -system mount. +If the mount operation is successful, this pointer to a pointer will be +set to reference the mount table chain entry that has been allocated for +this file system mount. rtems_filesystem_operations_table *fs_ops, -This is a pointer to a table of functions that are associated with the file -system that we are about to mount. This is the mechanism to selected file -system type without keeping a dynamic database of all possible file -system types that are valid for the mount operation. Using this method, it -is only necessary to configure the filesystems that we wish to use into the -RTEMS build. Unused filesystems types will not be drawn into the build. +This is a pointer to a table of functions that are associated with the +file system that we are about to mount. This is the mechanism to selected +file system type without keeping a dynamic database of all possible file +system types that are valid for the mount operation. Using this method, it +is only necessary to configure the filesystems that we wish to use into +the RTEMS build. Unused filesystems types will not be drawn into the +build. char *fsoptions, -This argument points to a string that selects mounting for read only access -or read/write access. Valid states are "RO" and "RW" +This argument points to a string that selects mounting for read only +access or read/write access. Valid states are "RO" and "RW" char *device, -This argument is reserved for the name of a device that will be used to -access the filesystem information. Current filesystem implementations -are memory based and do not require a device to access filesystem -information. +This argument is reserved for the name of a device that will be used to +access the filesystem information. Current filesystem implementations are +memory based and do not require a device to access filesystem information. char *mount_point -This is a pathname to a directory in a currently mounted filesystem that -allows read, write and execute permissions. If successful, the node -found by evaluating this name, is stored in the mt_entry. +This is a pathname to a directory in a currently mounted filesystem that +allows read, write and execute permissions. If successful, the node found +by evaluating this name, is stored in the mt_entry. @subheading Processing: -This routine will handle the mounting of a filesystem on a mount point. If the -operation is successful, a pointer to the mount table chain entry associated with -the mounted filesystem will be returned to the calling function. The specifics -about the processing required at the mount point and within the filesystem being -mounted is isolated in the filesystem specific mount() and fsmount_me() -functions. This allows the generic mount() function to remain unaltered even if -new filesystem types are introduced. +This routine will handle the mounting of a filesystem on a mount point. If +the operation is successful, a pointer to the mount table chain entry +associated with the mounted filesystem will be returned to the calling +function. The specifics about the processing required at the mount point +and within the filesystem being mounted is isolated in the filesystem +specific mount() and fsmount_me() functions. This allows the generic +mount() function to remain unaltered even if new filesystem types are +introduced. @subheading Development Comments: -This routine will use get_file_system_options() to determine if the mount options -are valid ("RO" or "RW"). +This routine will use get_file_system_options() to determine if the mount +options are valid ("RO" or "RW"). It confirms that a filesystem ops-table has been selected. -Space is allocated for a mount table entry and selective elements of the temporary -mount table entry are initialized. +Space is allocated for a mount table entry and selective elements of the +temporary mount table entry are initialized. -If a mount point is specified: -The mount point is examined to determine that it is a directory and also -has the appropriate permissions to allow a filesystem to be mounted. +If a mount point is specified: The mount point is examined to determine +that it is a directory and also has the appropriate permissions to allow a +filesystem to be mounted. -The current mount table chain is searched to determine that there is not -another filesystem mounted at the mount point we are trying to mount -onto. +The current mount table chain is searched to determine that there is not +another filesystem mounted at the mount point we are trying to mount onto. -If a mount function is defined in the ops table for the filesystem -containing the mount point, it is called at this time. +If a mount function is defined in the ops table for the filesystem +containing the mount point, it is called at this time. -If no mount point is specified: -Processing if performed to set up the mount table chain entry as the base -filesystem. +If no mount point is specified: Processing if performed to set up the +mount table chain entry as the base filesystem. -If the fsmount_me() function is specified for ops-table of the filesystem being -mounted, that function is called to initialize for the new filesystem. +If the fsmount_me() function is specified for ops-table of the filesystem +being mounted, that function is called to initialize for the new +filesystem. -On successful completion, the temporary mount table entry will be placed on the -mount table chain to record the presence of the mounted filesystem. +On successful completion, the temporary mount table entry will be placed +on the mount table chain to record the presence of the mounted filesystem. @c @page @section open @@ -869,42 +899,44 @@ open.c @subheading Processing: -This routine is layered on both RTEMS calls and filesystem specific -implementations of the open() function. These functional interfaces should not -change for new filesystems and therefore this code should be stable as new file -systems are introduced. +This routine is layered on both RTEMS calls and filesystem specific +implementations of the open() function. These functional interfaces should +not change for new filesystems and therefore this code should be stable as +new file systems are introduced. @subheading Development Comments: -This routine will allocate a file control block for the file or device that we are -about to open. +This routine will allocate a file control block for the file or device +that we are about to open. -It will then test to see if the pathname exists. If it does a -rtems_filesystem_location_info_t data structure will be filled out. This structure -contains information that associates node information, filesystem specific -functions and mount table chain information with the pathname. +It will then test to see if the pathname exists. If it does a +rtems_filesystem_location_info_t data structure will be filled out. This +structure contains information that associates node information, +filesystem specific functions and mount table chain information with the +pathname. -If the create option has been it will attempt to create a node for a regular file along -the specified path. If a file already exists along this path, an error will be -generated; otherwise, a node will be allocated for the file under the filesystem -that contains the pathname. When a new node is created, it is also evaluated so -that an appropriate rtems_filesystem_location_info_t data structure can be filled -out for the newly created node. +If the create option has been it will attempt to create a node for a +regular file along the specified path. If a file already exists along this +path, an error will be generated; otherwise, a node will be allocated for +the file under the filesystem that contains the pathname. When a new node +is created, it is also evaluated so that an appropriate +rtems_filesystem_location_info_t data structure can be filled out for the +newly created node. -If the file exists or the new file was created successfully, the file control block -structure will be initialized with handler table information, node information and -the rtems_filesystem_location_info_t data structure that describes the node and -filesystem data in detail. +If the file exists or the new file was created successfully, the file +control block structure will be initialized with handler table +information, node information and the rtems_filesystem_location_info_t +data structure that describes the node and filesystem data in detail. -If an open() function exists in the filesystem specific handlers table for the node -that we are trying to open, it will be called at this time. +If an open() function exists in the filesystem specific handlers table for +the node that we are trying to open, it will be called at this time. -If any error is detected in the process, cleanup is performed. It consists of freeing -the file control block structure that was allocated at the beginning of the generic -open() routine. +If any error is detected in the process, cleanup is performed. It consists +of freeing the file control block structure that was allocated at the +beginning of the generic open() routine. -On a successful open(), the index into the file descriptor table will be calculated -and returned to the calling routine. +On a successful open(), the index into the file descriptor table will be +calculated and returned to the calling routine. @c @page @section opendir @@ -915,10 +947,10 @@ opendir.c @subheading Processing: -This routine will attempt to open a directory for read access. It will setup a DIR -control structure that will be used to access directory information. This routine is -layered on the generic open() routine and filesystem specific directory -processing routines. +This routine will attempt to open a directory for read access. It will +setup a DIR control structure that will be used to access directory +information. This routine is layered on the generic open() routine and +filesystem specific directory processing routines. @subheading Development Comments: @@ -933,17 +965,17 @@ pathconf.c @subheading Processing: -This routine will obtain the value of one of the path configuration parameters and -return it to the calling routine. It is layered on the generic open() and fpathconf() -functions. These interfaces should not change with the addition of new filesystem -types. +This routine will obtain the value of one of the path configuration +parameters and return it to the calling routine. It is layered on the +generic open() and fpathconf() functions. These interfaces should not +change with the addition of new filesystem types. @subheading Development Comments: -This routine will try to open the file indicated by path. +This routine will try to open the file indicated by path. -If successful, the file descriptor will be used to access the pathconf value specified -by @code{name} using the fpathconf() function. +If successful, the file descriptor will be used to access the pathconf +value specified by @code{name} using the fpathconf() function. The file that was accessed is then closed. @@ -956,20 +988,21 @@ deviceio.c @subheading Processing: -This routine is layered on a set of RTEMS calls and filesystem specific read -operations. The functions are layered in such a way as to isolate them from -change as new filesystems are introduced. +This routine is layered on a set of RTEMS calls and filesystem specific +read operations. The functions are layered in such a way as to isolate +them from change as new filesystems are introduced. @subheading Development Comments: This routine will examine the type of file descriptor it is sent. -If the file descriptor is associated with a network device, the read function will be -mapped to a special network handler. The return code from the network handler -will then be sent as the return code from generic read() function. +If the file descriptor is associated with a network device, the read +function will be mapped to a special network handler. The return code from +the network handler will then be sent as the return code from generic +read() function. -For file descriptors that are associated with the filesystem the following sequence -will be performed: +For file descriptors that are associated with the filesystem the following +sequence will be performed: @enumerate @@ -983,10 +1016,10 @@ will be performed: @item Check the file control block to see if we have permissions to read -@item If there is a read function in the handler table, invoke the handler table -read() function +@item If there is a read function in the handler table, invoke the handler +table read() function -@item Use the return code from the handler table read function(number of +@item Use the return code from the handler table read function(number of bytes read) to increment the offset element of the file control block @item Return the number of bytes read to the calling program @@ -1000,18 +1033,19 @@ bytes read) to increment the offset element of the file control block readdir.c -@subheading Processing: +@subheading Processing: -This routine was acquired from the BSD group. It has not been altered from its -original form. +This routine was acquired from the BSD group. It has not been altered from +its original form. @subheading Development Comments: -The routine calls a customized getdents() function that is provided by the user. -This routine provides the filesystem specific aspects of reading a directory. +The routine calls a customized getdents() function that is provided by the +user. This routine provides the filesystem specific aspects of reading a +directory. -It is layered on the read() function in the directory handler table. This function -has been mapped to the Imfs_dir_read() function. +It is layered on the read() function in the directory handler table. This +function has been mapped to the Imfs_dir_read() function. @c @page @section unmount @@ -1022,41 +1056,43 @@ unmount.c @subheading Processing: -This routine will attempt to dismount a mounted filesystem and then free all -resources that were allocated for the management of that filesystem. +This routine will attempt to dismount a mounted filesystem and then free +all resources that were allocated for the management of that filesystem. @subheading Development Comments: @itemize @bullet -@item This routine will determine if there are any filesystems currently mounted -under the filesystem that we are trying to dismount. This would prevent the -dismount of the filesystem. +@item This routine will determine if there are any filesystems currently +mounted under the filesystem that we are trying to dismount. This would +prevent the dismount of the filesystem. -@item It will test to see if the current directory is in the filesystem that we are -attempting to dismount. This would prevent the dismount of the filesystem. +@item It will test to see if the current directory is in the filesystem +that we are attempting to dismount. This would prevent the dismount of the +filesystem. -@item It will scan all the currently open file descriptors to determine is there is an -open file descriptor to a file in the filesystem that we are attempting to -unmount(). +@item It will scan all the currently open file descriptors to determine is +there is an open file descriptor to a file in the filesystem that we are +attempting to unmount(). @end itemize -If the above preconditions are met then the following sequence is performed: +If the above preconditions are met then the following sequence is +performed: @enumerate -@item Call the filesystem specific unmount() function for the filesystem that -contains the mount point. This routine should indicate that the mount point -no longer has a filesystem mounted below it. +@item Call the filesystem specific unmount() function for the filesystem +that contains the mount point. This routine should indicate that the mount +point no longer has a filesystem mounted below it. -@item Call the filesystem specific fsunmount_me() function for the mounted -filesystem that we are trying to unmount(). This routine should clean up -any resources that are no longer needed for the management of the file +@item Call the filesystem specific fsunmount_me() function for the mounted +filesystem that we are trying to unmount(). This routine should clean up +any resources that are no longer needed for the management of the file system being un-mounted. -@item Extract the mount table entry for the filesystem that was just dismounted -from the mount table chain. +@item Extract the mount table entry for the filesystem that was just +dismounted from the mount table chain. @item Free the memory associated with the extracted mount table entry. |