summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-09 16:54:02 +1100
committerChris Johns <chrisj@rtems.org>2016-11-09 16:54:02 +1100
commit5431beb47290b642e5b6e2b4e12b07db758c6dcd (patch)
treea4cb50ce952c191b15aa6cb3a00630b7e3f5f2de
parentcpu-supplement: Fix the project label. (diff)
downloadrtems-docs-5431beb47290b642e5b6e2b4e12b07db758c6dcd.tar.bz2
filesystem: Fix header levels.
-rw-r--r--filesystem/call_development.rst1265
-rw-r--r--filesystem/command_and_variable.rst2
-rw-r--r--filesystem/conf.py8
-rw-r--r--filesystem/fileystem_implmentation.rst912
-rw-r--r--filesystem/in-memory.rst1830
-rw-r--r--filesystem/index.rst5
-rw-r--r--filesystem/minature_in-memory.rst2
-rw-r--r--filesystem/mounting_and_unmounting.rst2
-rw-r--r--filesystem/pathname_eval.rst2
-rw-r--r--filesystem/preface.rst15
-rw-r--r--filesystem/system_init.rst2
-rw-r--r--filesystem/trivial_ftp.rst2
12 files changed, 1851 insertions, 2196 deletions
diff --git a/filesystem/call_development.rst b/filesystem/call_development.rst
index 447ff58..5875de4 100644
--- a/filesystem/call_development.rst
+++ b/filesystem/call_development.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
System Call Development Notes
-#############################
+*****************************
This set of routines represents the application's interface to files and
directories under the RTEMS filesystem. All routines are compliant with POSIX
@@ -15,7 +15,7 @@ interface.
#. access()
-# .chdir()
+#. chdir()
#. chmod()
@@ -71,996 +71,939 @@ these functions.
access
======
-**File:**
+File:
+ ``access.c``
-access.c
+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.
-**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.
-
-**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.
+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.
chdir
=====
-**File:**
-
-chdir.c
-
-**Processing:**
+File:
+ ``chdir.c``
-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.
+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.
-**Development Comments:**
+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:
+ - RTEMS_FILESYSTEM_DIRECTORY
-- RTEMS_FILESYSTEM_DIRECTORY
+ - RTEMS_FILESYSTEM_DEVICE
-- RTEMS_FILESYSTEM_DEVICE
+ - RTEMS_FILESYSTEM_HARD_LINK
-- RTEMS_FILESYSTEM_HARD_LINK
+ - RTEMS_FILESYSTEM_MEMORY_FILE
-- RTEMS_FILESYSTEM_MEMORY_FILE
+ 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.
chmod
=====
-**File:**
-
-chmod.c
-
-**Processing:**
+File:
+ ``chmod.c``
-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.
+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.
-**Development Comments:**
+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.
+ After mode modification, the open file descriptor is closed.
chown
=====
-**File:**
-
-chown.c
+File:
+ ``chown.c``
-**Processing:**
+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.
+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.
-**Development Comments:**
+ 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.
-``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.
-
-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.
close
=====
-**File:**
-
-close.c
+File:
+ ``close.c``
-**Processing:**
+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).
+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.
-**Development Comments:**
+ 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.
-``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.
+ If none of the upper bits are set in the file descriptor index, the file
+ descriptor refers to an element of the RTEMS filesystem.
-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.
+ The following sequence will be performed for any filesystem file descriptor:
-If none of the upper bits are set in the file descriptor index, the file
-descriptor refers to an element of the RTEMS filesystem.
+ #. Use the ``rtems_libio_iop()`` function to obtain the ``rtems_libio_t``
+ structure for the file descriptor
-The following sequence will be performed for any filesystem file descriptor:
+ #. Range check the file descriptor using ``rtems_libio_check_fd()``
-#. Use the ``rtems_libio_iop()`` function to obtain the ``rtems_libio_t``
- structure for the file descriptor
+ #. 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.
-#. Range check the file descriptor using ``rtems_libio_check_fd()``
+ #. If the function has been defined it is invoked with the file control
+ block pointer as its argument.
-#. 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.
+ #. The file control block that was associated with the open file descriptor
+ is marked as free using ``rtems_libio_free()``.
-# If the function has been defined it is invoked with the file control
- block pointer as its argument.
+ #. The return code from the close handler is then passed back to the
+ calling program.
-#. The file control block that was associated with the open file descriptor is
- marked as free using ``rtems_libio_free()``.
-
-#. The return code from the close handler is then passed back to the calling
- program.
-
closedir
========
-**File:**
-
-closedir.c
+File:
+ ``closedir.c``
-**Processing:**
+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.
+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.
-**Development Comments:**
+ The dd_buf structure's memory is reallocated before the control structure
+ that contains the pointer to the dd_buf region.
-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.
+ DIR control memory is reallocated.
-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.
-
-The ``close()`` function is used to free the file descriptor index.
+ The ``close()`` function is used to free the file descriptor index.
dup() Unimplemented
========================
-**File:**
-
-dup.c
+File:
+ ``dup.c``
-**Processing:**
+Processing:
-**Development Comments:**
+Development Comments:
dup2() Unimplemented
=========================
-**File:**
+File:
+ ``dup2.c``
-dup2.c
+Processing:
-**Processing:**
-
-**Development Comments:**
+Development Comments:
fchmod
======
-**File:**
-
-fchmod.c
+File:
+ ``fchmod.c``
-**Processing:**
+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:
+ - rtems_file_descriptor_type()
-- rtems_file_descriptor_type()
+ - rtems_libio_iop()
-- rtems_libio_iop()
+ - rtems_libio_check_fd()
-- rtems_libio_check_fd()
+ - rtems_libio_check_permissions()
-- rtems_libio_check_permissions()
+ - fchmod() function that is referenced by the handler table in the file
+ control block associated with this file descriptor
-- fchmod() function that is referenced by the handler table in the file control
- block associated with this file descriptor
+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.
-**Development Comments:**
+ The file descriptor index is used to obtain the associated file control
+ block.
-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 value is range checked.
-The file descriptor index is used to obtain the associated file control block.
+ 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 descriptor value is range checked.
+ 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.
-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.
-
-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.
fcntl()
=======
-**File:**
-
-fcntl.c
-
-**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.
+File:
+ ``fcntl.c``
-**Development Comments:**
+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.
-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``flags`` element
-of the file control block associated with the file descriptor index.
+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``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:
-# Test to see if we are trying to operate on a file descriptor
- associated with a network connection
+ #. Test to see if we are trying to operate on a file descriptor associated
+ with a network connection
-# Obtain the file control block that is associated with the file
- descriptor index
+ #. Obtain the file control block that is associated with the file
+ descriptor index
-# Perform a range check on the file descriptor index.
+ #. Perform a range check on the file descriptor index.
fdatasync
=========
-**File:**
+File:
+ ``fdatasync.c``
-fdatasync.c
+Processing:
+ This routine is a template in the in memory filesystem that will route us
+ to the appropriate handler function to carry out the fdatasync()
+ processing. In the in memory filesystem this function is not necessary. Its
+ function in a disk based file system that employs a memory cache is to
+ flush all memory based data buffers to disk. It is layered on the following
+ functions and macros:
-**Processing:**
+ - rtems_file_descriptor_type()
-This routine is a template in the in memory filesystem that will route us to
-the appropriate handler function to carry out the fdatasync() processing. In
-the in memory filesystem this function is not necessary. Its function in a disk
-based file system that employs a memory cache is to flush all memory based data
-buffers to disk. It is layered on the following functions and macros:
+ - rtems_libio_iop()
-- rtems_file_descriptor_type()
+ - rtems_libio_check_fd()
-- rtems_libio_iop()
+ - rtems_libio_check_permissions()
-- rtems_libio_check_fd()
+ - fdatasync() function that is referenced by the handler table in the file
+ control block associated with this file descriptor
-- rtems_libio_check_permissions()
+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.
-- fdatasync() function that is referenced by the handler table in the file
- control block associated with this file descriptor
+ The file descriptor index is used to obtain the associated file control
+ block.
-**Development Comments:**
+ The file descriptor value is range checked.
-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 control block is examined to determine if it has write permissions
+ to the file.
-The file descriptor index is used to obtain the associated file control block.
+ 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.
-The file descriptor value is range checked.
-
-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.
-
-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.
fpathconf
=========
-**File:**
-
-fpathconf.c
-
-**Processing:**
+File:
+ ``fpathconf.c``
-This routine is layered on the following functions and macros:
+Processing:
+ This routine is layered on the following functions and macros:
-- rtems_file_descriptor_type()
+ - rtems_file_descriptor_type()
-- rtems_libio_iop()
+ - rtems_libio_iop()
-- rtems_libio_check_fd()
+ - rtems_libio_check_fd()
-- rtems_libio_check_permissions()
+ - rtems_libio_check_permissions()
-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.
-- PCLINKMAX
+ - PCLINKMAX
-- PCMAXCANON
+ - PCMAXCANON
-- PCMAXINPUT
+ - PCMAXINPUT
-- PCNAMEMAX
+ - PCNAMEMAX
-- PCPATHMAX
+ - PCPATHMAX
-- PCPIPEBUF
+ - PCPIPEBUF
-- PCCHOWNRESTRICTED
+ - PCCHOWNRESTRICTED
-- PCNOTRUNC
+ - PCNOTRUNC
-- PCVDISABLE
+ - PCVDISABLE
-- PCASYNCIO
+ - PCASYNCIO
-- PCPRIOIO
+ - PCPRIOIO
-- PCSYNCIO
+ - PCSYNCIO
-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.
-**Development Comments:**
+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 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
-pathconf_limits_and_options table.
+ The name argument is used to reference the desired constant from the
+ pathconf_limits_and_options table.
fstat
=====
-**File:**
-
-fstat.c
-
-**Processing:**
+File:
+ ``fstat.c``
-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.
+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.
-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.
-**Development Comments:**
+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.
-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:
+ #. Obtain the file control block that is associated with the file descriptor
+ index.
-# Obtain the file control block that is associated with the file descriptor
- index.
+ #. Range check the file descriptor index.
-# Range check the file descriptor index.
-
-# 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.
+ #. 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.
ioctl
=====
-**File:**
-
-ioctl.c
+File:
+ ``ioctl.c``
-**Processing:**
+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.
+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.
-**Development Comments:**
+ File descriptors that are associated with a filesystem undergo the
+ following processing:
-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 index is used to obtain the associated file control
+ block.
-File descriptors that are associated with a filesystem undergo the following
-processing:
+ #. The file descriptor value is range checked.
-# The file descriptor index is used to obtain the associated file control
- block.
+ #. 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.
-# The file descriptor value is range checked.
+ #. If the ioctl() handler function exists, it is called with the file
+ control block, the command and buffer as its parameters.
-# 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.
-
-# If the ioctl() handler function exists, it is called with the file control
- block, the command and buffer as its parameters.
-
-# The return code from this function is then sent to the calling routine.
+ #. The return code from this function is then sent to the calling routine.
link
====
-**File:**
-
-link.c
-
-**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.
+File:
+ ``link.c``
-**Development Comments:**
+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.
-Calling parameters:
+Development Comments:
+ Calling parameters:
-.. code-block:: c
+ .. code-block:: c
- const char *existing
- const char *new
+ const char *existing
+ const char *new
-link() will determine if the target of the link actually exists using
-rtems_filesystem_evaluate_path()
+ 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.
+ 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 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 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.
+ 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 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 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.
+ 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.
lseek
=====
-**File:**
+File:
+ ``lseek.c``
-lseek.c
+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.
-**Processing:**
+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 is layered on both external handlers and filesystem / node type
-specific handlers. This routine should allow for the support of new filesystems
-without modification.
+ 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:
-**Development Comments:**
+ #. The file descriptor is used to obtain the file control block for the
+ node.
-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.
+ #. The file descriptor is range checked.
-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:
+ #. The offset element of the file control block is altered as indicated by
+ the offset and whence calling parameters
-# The file descriptor is used to obtain the file control block for the node.
+ #. 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.
-# The file descriptor is range checked.
+ #. The lseek() function from the designated handler table is called with
+ the file control block, offset and whence as calling arguments
-# The offset element of the file control block is altered as indicated by the
- offset and whence calling parameters
-
-# 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.
-
-# The lseek() function from the designated handler table is called with the
- file control block, offset and whence as calling arguments
-
-# The return code from the lseek() handler function is returned to the calling
- program
+ #. The return code from the lseek() handler function is returned to the
+ calling program
mkdir
=====
-**File:**
-
-mkdir.c
-
-**Processing:**
+File:
+ ``mkdir.c``
-This routine attempts to create a directory node under the filesystem. The
-routine is layered the mknod() function.
+Processing:
+ This routine attempts to create a directory node under the filesystem. The
+ routine is layered the mknod() function.
-**Development Comments:**
-
-See mknod() for developmental comments.
+Development Comments:
+ See mknod() for developmental comments.
mkfifo
======
-**File:**
-
-mkfifo.c
-
-**Processing:**
+File:
+ ``mkfifo.c``
-This routine attempts to create a FIFO node under the filesystem. The routine
-is layered the mknod() function.
+Processing:
+ This routine attempts to create a FIFO node under the filesystem. The
+ routine is layered the mknod() function.
-**Development Comments:**
-
-See mknod() for developmental comments
+Development Comments:
+ See mknod() for developmental comments
.. COMMENT: @page
mknod
=====
-**File:**
-
-mknod.c
+File:
+ ``mknod.c``
-**Processing:**
+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:
+ - directories
-- directories
+ - regular files
-- regular files
+ - character devices
-- character devices
+ - block devices
-- block devices
+ - fifos
-- fifos
+ 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.
+Development Comments:
+ Test for nodal types - I thought that this test should look like the
+ following code:
-**Development Comments:**
+ .. code-block:: c
-Test for nodal types - I thought that this test should look like the following
-code:
+ if ( (mode & S_IFDIR) = = S_IFDIR) ||
+ (mode & S_IFREG) = = S_IFREG) ||
+ (mode & S_IFCHR) = = S_IFCHR) ||
+ (mode & S_IFBLK) = = S_IFBLK) ||
+ (mode & S_IFIFO) = = S_IFIFO))
+ Set_errno_and_return_minus_one (EINVAL);
-.. code-block:: c
+ Where:
- if ( (mode & S_IFDIR) = = S_IFDIR) ||
- (mode & S_IFREG) = = S_IFREG) ||
- (mode & S_IFCHR) = = S_IFCHR) ||
- (mode & S_IFBLK) = = S_IFBLK) ||
- (mode & S_IFIFO) = = S_IFIFO))
- Set_errno_and_return_minus_one (EINVAL);
+ - S_IFREG (0100000) - Creation of a regular file
-Where:
+ - S_IFCHR (0020000) - Creation of a character device
-- S_IFREG (0100000) - Creation of a regular file
+ - S_IFBLK (0060000) - Creation of a block device
-- S_IFCHR (0020000) - Creation of a character device
+ - S_IFIFO (0010000) - Creation of a FIFO
-- S_IFBLK (0060000) - Creation of a block device
+ 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.
-- S_IFIFO (0010000) - Creation of a FIFO
+ Determine if the pathname leads to a valid directory that can be accessed
+ for the creation of a node.
-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.
+ If the pathname is a valid location to create a node, verify that a
+ filesystem specific mknod() function exists.
-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 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.
mount
=====
-**File:**
-
-mount.c
-
-Arguments (Not a standard POSIX call):
-
-.. code-block:: c
+File:
+ ``mount.c``
- rtems_filesystem_mount_table_entry_t **mt_entry,
+ Arguments (Not a standard POSIX call):
-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.
+ .. code-block:: c
-.. code-block:: c
+ rtems_filesystem_mount_table_entry_t **mt_entry,
- rtems_filesystem_operations_table *fs_ops,
+ 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.
-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.
+ .. code-block:: c
-.. code-block:: c
+ rtems_filesystem_operations_table *fs_ops,
- char *fsoptions,
+ 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 argument points to a string that selects mounting for read only
-access or read/write access. Valid states are "RO" and "RW"
+ .. code-block:: c
-.. code-block:: c
+ char *fsoptions,
- char *device,
+ 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 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.
+ .. code-block:: c
-.. code-block:: c
+ char *device,
- char *mount_point
+ 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 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.
+ .. code-block:: c
-**Processing:**
+ char *mount_point
-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 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.
-**Development Comments:**
+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 use get_file_system_options() to determine if the mount
-options are valid ("RO" or "RW").
+Development Comments:
+ 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.
+ 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.
open
====
-**File:**
+File:
+ ``open.c``
-open.c
+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.
-**Processing:**
+Development Comments:
+ This routine will allocate a file control block for the file or device that
+ we are about to open.
-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.
+ 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.
-**Development Comments:**
+ 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.
-This routine will allocate a file control block for the file or device that we
-are about to open.
+ 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.
-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 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 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 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 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 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.
opendir
=======
-**File:**
-
-opendir.c
-
-**Processing:**
+File:
+ ``opendir.c``
-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.
+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.
-**Development Comments:**
-
-The BSD group provided this routine.
+Development Comments:
+ The BSD group provided this routine.
pathconf
========
-**File:**
-
-pathconf.c
-
-**Processing:**
+File:
+ ``pathconf.c``
-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.
+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.
-**Development Comments:**
+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 ``name`` using the fpathconf() function.
-If successful, the file descriptor will be used to access the pathconf value
-specified by ``name`` using the fpathconf() function.
-
-The file that was accessed is then closed.
+ The file that was accessed is then closed.
read
====
-**File:**
-
-deviceio.c
+File:
+ ``deviceio.c``
-**Processing:**
+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.
+Development Comments:
+ This routine will examine the type of file descriptor it is sent.
-**Development Comments:**
+ 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.
-This routine will examine the type of file descriptor it is sent.
+ For file descriptors that are associated with the filesystem the following
+ sequence will be performed:
-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.
+ #. Obtain the file control block associated with the file descriptor
-For file descriptors that are associated with the filesystem the following
-sequence will be performed:
+ #. Range check the file descriptor
-# Obtain the file control block associated with the file descriptor
+ #. Determine that the buffer pointer is not invalid
-# Range check the file descriptor
+ #. Check that the count is not zero
-# Determine that the buffer pointer is not invalid
+ #. Check the file control block to see if we have permissions to read
-# Check that the count is not zero
+ #. If there is a read function in the handler table, invoke the handler
+ table read() function
-# Check the file control block to see if we have permissions to read
+ #. Use the return code from the handler table read function(number of bytes
+ read) to increment the offset element of the file control block
-# If there is a read function in the handler table, invoke the handler table
- read() function
-
-# Use the return code from the handler table read function(number of bytes
- read) to increment the offset element of the file control block
-
-# Return the number of bytes read to the calling program
+ #. Return the number of bytes read to the calling program
readdir
=======
-**File:**
-
-readdir.c
-
-**Processing:**
-
-This routine was acquired from the BSD group. It has not been altered from its
-original form.
+File:
+ ``readdir.c``
-**Development Comments:**
+Processing:
+ This routine was acquired from the BSD group. It has not been altered from
+ its original form.
-The routine calls a customized getdents() function that is provided by the
-user. This routine provides the filesystem specific aspects of reading a
-directory.
+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.
-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.
unmount
=======
-**File:**
+File:
+ ``unmount.c``
-unmount.c
+Processing:
+ This routine will attempt to dismount a mounted filesystem and then free
+ all resources that were allocated for the management of that filesystem.
-**Processing:**
+Development Comments:
+ - 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.
-This routine will attempt to dismount a mounted filesystem and then free all
-resources that were allocated for the management of that filesystem.
+ - 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.
-**Development Comments:**
+ - 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().
-- 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.
+ If the above preconditions are met then the following sequence is
+ performed:
-- 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.
+ #. 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.
-- 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().
+ #. 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.
-If the above preconditions are met then the following sequence is performed:
+ #. Extract the mount table entry for the filesystem that was just dismounted
+ from the mount table chain.
-# 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.
-
-# 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.
-
-# Extract the mount table entry for the filesystem that was just dismounted
- from the mount table chain.
-
-# Free the memory associated with the extracted mount table entry.
+ #. Free the memory associated with the extracted mount table entry.
eval
====
-**File:**
-
-XXX
-
-**Processing:**
+File:
+ ``XXX``
-XXX
+Processing:
+ XXX
-**Development Comments:**
-
-XXX
+Development Comments:
+ XXX
getdentsc
=========
-**File:**
-
-XXX
-
-**Processing:**
-
-XXX
+File:
+ ``XXX``
-**Development Comments:**
+Processing:
+ XXX
-XXX
+Development Comments:
+ XXX
diff --git a/filesystem/command_and_variable.rst b/filesystem/command_and_variable.rst
index 67fa271..422b61e 100644
--- a/filesystem/command_and_variable.rst
+++ b/filesystem/command_and_variable.rst
@@ -1,6 +1,6 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Command and Variable Index
-##########################
+**************************
There are currently no Command and Variable Index entries.
diff --git a/filesystem/conf.py b/filesystem/conf.py
index 129cc7e..4c15bad 100644
--- a/filesystem/conf.py
+++ b/filesystem/conf.py
@@ -3,9 +3,11 @@ sys.path.append(os.path.abspath('../common/'))
from conf import *
-version = '1.0'
-release = '5.0'
+version = '4.11.0'
+release = '4.11.0'
+
+project = "RTEMS Filesystem Design Guide"
latex_documents = [
- ('index', 'filesystem.tex', u'RTEMS Filesystem', u'RTEMS Documentation Project', 'manual'),
+ ('index', 'filesystem.tex', u'RTEMS Filesystem Design Guide', u'RTEMS Filesystem Design Guide', 'manual'),
]
diff --git a/filesystem/fileystem_implmentation.rst b/filesystem/fileystem_implmentation.rst
index f8b5a6a..d40fe61 100644
--- a/filesystem/fileystem_implmentation.rst
+++ b/filesystem/fileystem_implmentation.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
Filesystem Implementation Requirements
-######################################
+**************************************
This chapter details the behavioral requirements that all filesystem
implementations must adhere to.
@@ -105,75 +105,75 @@ explicit knowledge of the filesystem type or the filesystem mount
configuration. The following are functions that are provided to the
application:
-# access()
+#. access()
-# chdir()
+#. chdir()
-# chmod()
+#. chmod()
-# chown()
+#. chown()
-# close()
+#. close()
-# closedir()
+#. closedir()
-# fchmod()
+#. fchmod()
-# fcntl()
+#. fcntl()
-# fdatasync()
+#. fdatasync()
-# fpathconf()
+#. fpathconf()
-# fstat()
+#. fstat()
-# fsync()
+#. fsync()
-# ftruncate()
+#. ftruncate()
-# link()
+#. link()
-# lseek()
+#. lseek()
-# mkdir()
+#. mkdir()
-# mknod()
+#. mknod()
-# mount()
+#. mount()
-# open()
+#. open()
-# opendir()
+#. opendir()
-# pathconf()
+#. pathconf()
-# read()
+#. read()
-# readdir()
+#. readdir()
-# rewinddir()
+#. rewinddir()
-# rmdir()
+#. rmdir()
-# rmnod()
+#. rmnod()
-# scandir()
+#. scandir()
-# seekdir()
+#. seekdir()
-# stat()
+#. stat()
-# telldir()
+#. telldir()
-# umask()
+#. umask()
-# unlink()
+#. unlink()
-# unmount()
+#. unmount()
-# utime()
+#. utime()
-# write()
+#. write()
The filesystem's type as well as the node type within the filesystem determine
the nature of the processing that must be performed for each of the functions
@@ -196,14 +196,14 @@ control block contains information that is used to locate node, file system,
mount table and functional handler information. The diagram in Figure 8 depicts
the relationship between and among the following components.
-# File Descriptor Table
+File Descriptor Table:
This is an internal RTEMS structure that tracks all currently defined file
descriptors in the system. The index that is returned by the file open()
operation references a slot in this table. The slot contains a pointer to the
file descriptor table entry for this file. The rtems_libio_t structure
represents the file control block.
-# Allocation of entry in the File Descriptor Table
+Allocation of entry in the File Descriptor Table:
Access to the file descriptor table is controlled through a semaphore that is
implemented using the rtems_libio_allocate() function. This routine will grab
a semaphore and then scan the file control blocks to determine which slot is
@@ -212,15 +212,14 @@ the relationship between and among the following components.
alterations have been made to the file control block table, the semaphore is
released to allow further operations on the table.
-# Maximum number of entries in the file descriptor table is configurable
+ Maximum number of entries in the file descriptor table is configurable
through the src/exec/sapi/headers/confdefs.h file. If the
- CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value will
- represent the maximum number of file descriptors that are allowed. If
- CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default value of
- 20 will be used as the maximum number of file descriptors allowed.
-
-# File control block - rtems_libio_t structure
+ ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` constant is defined its value
+ will represent the maximum number of file descriptors that are allowed. If
+ ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` is not specified a default value
+ of 20 will be used as the maximum number of file descriptors allowed.
+File control block - rtems_libio_t structure:
.. code-block:: c
struct rtems_libio_tt {
@@ -258,7 +257,7 @@ the relationship between and among the following components.
File/Directory function access via rtems_filesystem_location_info_t structure
-----------------------------------------------------------------------------
-The rtems_filesystem_location_info_tt structure below provides sufficient
+The ``rtems_filesystem_location_info_tt`` structure below provides sufficient
information to process nodes under a mounted filesystem.
.. code-block:: c
@@ -316,422 +315,373 @@ function management structure.
} rtems_filesystem_operations_table;
evalpath Handler
-~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-evalpath
+^^^^^^^^^^^^^^^^
-**Arguments:**
-
-.. code-block:: c
+Corresponding Structure Element:
+ ``evalpath``
- const char *pathname, /* IN */
- int flags, /* IN */
- rtems_filesystem_location_info_t *pathloc /* IN/OUT */
+Arguments:
+ .. code-block:: c
-**Description:**
+ const char *pathname, /* IN */
+ int flags, /* IN */
+ rtems_filesystem_location_info_t *pathloc /* IN/OUT */
-This routine is responsible for evaluating the pathname passed in based upon
-the flags and the valid ``rthems_filesystem_location_info_t``. Additionally,
-it must make any changes to pathloc necessary to identify the pathname node.
-This should include calling the evalpath for a mounted filesystem, if the given
-filesystem supports the mount command.
+Description:
+ This routine is responsible for evaluating the pathname passed in based
+ upon the flags and the valid ``rthems_filesystem_location_info_t``.
+ Additionally, it must make any changes to pathloc necessary to identify the
+ pathname node. This should include calling the evalpath for a mounted
+ filesystem, if the given filesystem supports the mount command.
-This routine returns a 0 if the evaluation was successful. Otherwise, it
-returns a -1 and sets errno to the correct error.
+ This routine returns a 0 if the evaluation was successful. Otherwise, it
+ returns a -1 and sets errno to the correct error.
-This routine is required and should NOT be set to NULL.
+ This routine is required and should NOT be set to NULL.
evalformake Handler
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
-
-evalformake
-
-**Arguments:**
-
-.. code-block:: c
+Corresponding Structure Element:
+ ``evalformake``
- const char *path, /* IN */
- rtems_filesystem_location_info_t *pathloc, /* IN/OUT */
- const char **name /* OUT */
+Arguments:
+ .. code-block:: c
-**Description:**
+ const char *path, /* IN */
+ rtems_filesystem_location_info_t *pathloc, /* IN/OUT */
+ const char **name /* OUT */
-This method is given a path to evaluate and a valid start location. It is
-responsible for finding the parent node for a requested make command, setting
-pathloc information to identify the parent node, and setting the name pointer
-to the first character of the name of the new node. Additionally, if the
-filesystem supports the mount command, this method should call the evalformake
-routine for the mounted filesystem.
+Description:
+ This method is given a path to evaluate and a valid start location. It is
+ responsible for finding the parent node for a requested make command,
+ setting pathloc information to identify the parent node, and setting the
+ name pointer to the first character of the name of the new node.
+ Additionally, if the filesystem supports the mount command, this method
+ should call the evalformake routine for the mounted filesystem.
-This routine returns a 0 if the evaluation was successful. Otherwise, it
-returns a -1 and sets errno to the correct error.
+ This routine returns a 0 if the evaluation was successful. Otherwise, it
+ returns a -1 and sets errno to the correct error.
-This routine is required and should NOT be set to NULL. However, if the
-filesystem does not support user creation of a new node, it may set errno to
-ENOSYS and return -1.
+ This routine is required and should NOT be set to NULL. However, if the
+ filesystem does not support user creation of a new node, it may set errno
+ to ENOSYS and return -1.
link Handler
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-link
-
-**Arguments:**
+^^^^^^^^^^^^
-.. code-block:: c
+Corresponding Structure Element:
+ ``link``
- rtems_filesystem_location_info_t *to_loc, /* IN */
- rtems_filesystem_location_info_t *parent_loc, /* IN */
- const char *token /* IN */
+Arguments:
+ .. code-block:: c
-**Description:**
+ rtems_filesystem_location_info_t *to_loc, /* IN */
+ rtems_filesystem_location_info_t *parent_loc, /* IN */
+ const char *token /* IN */
-This routine is used to create a hard-link.
+Description:
+ This routine is used to create a hard-link.
-It will first examine the st_nlink count of the node that we are trying to. If
-the link count exceeds LINK_MAX an error will be returned.
+ It will first examine the st_nlink count of the node that we are trying to.
+ If the link count exceeds LINK_MAX an error will be returned.
-The name of the link will be normalized to remove extraneous separators from
-the end of the name.
+ The name of the link will be normalized to remove extraneous separators
+ from the end of the name.
-This routine is not required and may be set to NULL.
+ This routine is not required and may be set to NULL.
unlink Handler
-~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
+^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ ``unlink``
-XXX
+Arguments:
+ XXX
-**Description:**
-
-XXX
+Description:
+ XXX
node_type Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^
-node_type()
+Corresponding Structure Element:
+ ``node_type()``
-**Arguments:**
-
-.. code-block:: c
+Arguments:
+ .. code-block:: c
- rtems_filesystem_location_info_t *pathloc /* IN */
+ rtems_filesystem_location_info_t *pathloc /* IN */
-**Description:**
-
-XXX
+Description:
+ XXX
mknod Handler
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``mknod()``
-mknod()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ const char *token, /* IN */
+ mode_t mode, /* IN */
+ dev_t dev, /* IN */
+ rtems_filesystem_location_info_t *pathloc /* IN/OUT */
- const char *token, /* IN */
- mode_t mode, /* IN */
- dev_t dev, /* IN */
- rtems_filesystem_location_info_t *pathloc /* IN/OUT */
-
-**Description:**
-
-XXX
+Description:
+ XXX
rmnod Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ ``rmnod()``
-**Arguments:**
+Arguments:
+ XXX
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
chown Handler
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``chown()``
-chown()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_location_info_t *pathloc /* IN */
+ uid_t owner /* IN */
+ gid_t group /* IN */
-.. code-block:: c
-
- rtems_filesystem_location_info_t *pathloc /* IN */
- uid_t owner /* IN */
- gid_t group /* IN */
-
-**Description:**
-
-XXX
-
-.. COMMENT: @page
+Description:
+ XXX
freenod Handler
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``freenod()``
-freenod()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_location_info_t *pathloc /* IN */
-.. code-block:: c
+Description:
+ This routine is used by the generic code to allow memory to be allocated
+ during the evaluate routines, and set free when the generic code is
+ finished accessing a node. If the evaluate routines allocate memory to
+ identify a node this routine should be utilized to free that memory.
- rtems_filesystem_location_info_t *pathloc /* IN */
-
-**Description:**
-
-This routine is used by the generic code to allow memory to be allocated during
-the evaluate routines, and set free when the generic code is finished accessing
-a node. If the evaluate routines allocate memory to identify a node this
-routine should be utilized to free that memory.
-
-This routine is not required and may be set to NULL.
+ This routine is not required and may be set to NULL.
mount Handler
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``mount()``
-mount()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_mount_table_entry_t *mt_entry
-.. code-block:: c
-
- rtems_filesystem_mount_table_entry_t *mt_entry
-
-**Description:**
-
-XXX
+Description:
+ XXX
fsmount_me Handler
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``imfs_fsmount_me``
-XXX
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_mount_table_entry_t *mt_entry
-.. code-block:: c
-
- rtems_filesystem_mount_table_entry_t *mt_entry
+Description:
+ This function is provided with a filesystem to take care of the internal
+ filesystem management details associated with mounting that filesystem
+ under the RTEMS environment.
-**Description:**
+ It is not responsible for the mounting details associated the filesystem
+ containing the mount point.
-This function is provided with a filesystem to take care of the internal
-filesystem management details associated with mounting that filesystem under
-the RTEMS environment.
+ The rtems_filesystem_mount_table_entry_t structure contains the key
+ elements below:
-It is not responsible for the mounting details associated the filesystem
-containing the mount point.
+ .. code-block:: c
-The rtems_filesystem_mount_table_entry_t structure contains the key elements
-below:
+ rtems_filesystem_location_info_t *mt_point_node,
-.. code-block:: c
+ This structure contains information about the mount point. This allows us
+ to find the ops-table and the handling functions associated with the
+ filesystem containing the mount point.
- rtems_filesystem_location_info_t *mt_point_node,
+ .. code-block:: c
-This structure contains information about the mount point. This
-allows us to find the ops-table and the handling functions
-associated with the filesystem containing the mount point.
+ rtems_filesystem_location_info_t *fs_root_node,
-.. code-block:: c
+ This structure contains information about the root node in the file system
+ to be mounted. It allows us to find the ops-table and the handling
+ functions associated with the filesystem to be mounted.
- rtems_filesystem_location_info_t *fs_root_node,
-
-This structure contains information about the root node in the file
-system to be mounted. It allows us to find the ops-table and the
-handling functions associated with the filesystem to be mounted.
-
-.. code-block:: c
+ .. code-block:: c
rtems_filesystem_options_t options,
-Read only or read/write access
+ Read only or read/write access
-.. code-block:: c
+ .. code-block:: c
- void *fs_info,
+ void *fs_info,
-This points to an allocated block of memory the will be used to hold any
-filesystem specific information of a global nature. This allocated region if
-important because it allows us to mount the same filesystem type more than once
-under the RTEMS system. Each instance of the mounted filesystem has its own
-set of global management information that is separate from the global
-management information associated with the other instances of the mounted
-filesystem type.
+ This points to an allocated block of memory the will be used to hold any
+ filesystem specific information of a global nature. This allocated region
+ if important because it allows us to mount the same filesystem type more
+ than once under the RTEMS system. Each instance of the mounted filesystem
+ has its own set of global management information that is separate from the
+ global management information associated with the other instances of the
+ mounted filesystem type.
-.. code-block:: c
+ .. code-block:: c
- rtems_filesystem_limits_and_options_t pathconf_info,
+ rtems_filesystem_limits_and_options_t pathconf_info,
-The table contains the following set of values associated with the mounted
-filesystem:
+ The table contains the following set of values associated with the mounted
+ filesystem:
-- link_max
+ - link_max
-- max_canon
+ - max_canon
-- max_input
+ - max_input
-- name_max
+ - name_max
-- path_max
+ - path_max
-- pipe_buf
+ - pipe_buf
-- posix_async_io
+ - posix_async_io
-- posix_chown_restrictions
+ - posix_chown_restrictions
-- posix_no_trunc
+ - posix_no_trunc
-- posix_prio_io
+ - posix_prio_io
-- posix_sync_io
+ - posix_sync_io
-- posix_vdisable
+ - posix_vdisable
-These values are accessed with the pathconf() and the fpathconf () functions.
+ These values are accessed with the pathconf() and the fpathconf () functions.
-.. code-block:: c
+ .. code-block:: c
- const char *dev
+ const char *dev
-The is intended to contain a string that identifies the device that contains
-the filesystem information. The filesystems that are currently implemented are
-memory based and don't require a device specification.
+ The is intended to contain a string that identifies the device that
+ contains the filesystem information. The filesystems that are currently
+ implemented are memory based and don't require a device specification.
-If the mt_point_node.node_access is NULL then we are mounting the base file
-system.
+ If the mt_point_node.node_access is NULL then we are mounting the base file
+ system.
-The routine will create a directory node for the root of the IMFS file system.
+ The routine will create a directory node for the root of the IMFS file
+ system.
-The node will have read, write and execute permissions for owner, group and
-others.
+ The node will have read, write and execute permissions for owner, group and
+ others.
-The node's name will be a null string.
+ The node's name will be a null string.
-A filesystem information structure(fs_info) will be allocated and initialized
-for the IMFS filesystem. The fs_info pointer in the mount table entry will be
-set to point the filesystem information structure.
+ A filesystem information structure(fs_info) will be allocated and
+ initialized for the IMFS filesystem. The fs_info pointer in the mount table
+ entry will be set to point the filesystem information structure.
-The pathconf_info element of the mount table will be set to the appropriate
-table of path configuration constants (LIMITS_AND_OPTIONS).
+ The pathconf_info element of the mount table will be set to the appropriate
+ table of path configuration constants (LIMITS_AND_OPTIONS).
-The fs_root_node structure will be filled in with the following:
+ The fs_root_node structure will be filled in with the following:
-- pointer to the allocated root node of the filesystem
+ - pointer to the allocated root node of the filesystem
-- directory handlers for a directory node under the IMFS filesystem
+ - directory handlers for a directory node under the IMFS filesystem
-- OPS table functions for the IMFS
+ - OPS table functions for the IMFS
-A 0 will be returned to the calling routine if the process succeeded, otherwise
-a 1 will be returned.
+ A 0 will be returned to the calling routine if the process succeeded,
+ otherwise a 1 will be returned.
unmount Handler
-~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
+^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
-
-XXX
+Description:
+ XXX
fsunmount_me Handler
-~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_fsunmount_me()
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^
-.. code-block:: c
+Corresponding Structure Element:
+ ``imfs_fsunmount_me()``
- rtems_filesystem_mount_table_entry_t *mt_entry
+Arguments:
+ .. code-block:: c
-**Description:**
+ rtems_filesystem_mount_table_entry_t *mt_entry
-XXX
+Description:
+ XXX
utime Handler
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
+^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
-
-XXX
+Description:
+ XXX
eval_link Handler
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**Description:**
+Arguments:
+ XXX
-XXX
+Description:
+ XXX
symlink Handler
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Arguments:**
-
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
File Handler Table Functions
----------------------------
@@ -762,291 +712,241 @@ this function management structure.
} rtems_filesystem_file_handlers_r;
open Handler
-~~~~~~~~~~~~
+^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``open()``
-open()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_libio_t *iop,
+ const char *pathname,
+ unsigned32 flag,
+ unsigned32 mode
-.. code-block:: c
-
- rtems_libio_t *iop,
- const char *pathname,
- unsigned32 flag,
- unsigned32 mode
-
-**Description:**
-
-XXX
+Description:
+ XXX
close Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-close()
-
-**Arguments:**
-
-.. code-block:: c
-
- rtems_libio_t *iop
+Corresponding Structure Element:
+ ``close()``
-**Description:**
+Arguments:
+ .. code-block:: c
-XXX
+ rtems_libio_t *iop
-**NOTES:**
+Description:
+ XXX
-XXX
+NOTES:
+ XXX
read Handler
~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-read()
-
-**Arguments:**
-
-.. code-block:: c
+Corresponding Structure Element:
+ ``read()``
- rtems_libio_t *iop,
- void *buffer,
- unsigned32 count
+Arguments:
+ .. code-block:: c
-**Description:**
+ rtems_libio_t *iop,
+ void *buffer,
+ unsigned32 count
-XXX
+Description:
+ XXX
-**NOTES:**
-
-XXX
+NOTES:
+ XXX
write Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+Corresponding Structure Element:
+ XXX
-**Description:**
+Arguments:
+ XXX
-XXX
+Description:
+ XXX
-**NOTES:**
-
-XXX
+NOTES:
+ XXX
ioctl Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-.. code-block:: c
-
- rtems_libio_t *iop,
- unsigned32 command,
- void *buffer
+Corresponding Structure Element:
+ XXX
-**Description:**
+Arguments:
+ .. code-block:: c
-XXX
+ rtems_libio_t *iop,
+ unsigned32 command,
+ void *buffer
-**NOTES:**
+Description:
+ XXX
-XXX
+NOTES:
+ XXX
lseek Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``lseek()``
-lseek()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ rtems_libio_t *iop,
+ off_t offset,
+ int whence
- rtems_libio_t *iop,
- off_t offset,
- int whence
+Description:
+ XXX
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
+NOTES:
+ XXX
fstat Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``fstat()``
-fstat()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ rtems_filesystem_location_info_t *loc,
+ struct stat *buf
- rtems_filesystem_location_info_t *loc,
- struct stat *buf
+Description:
+ The following information is extracted from the filesystem specific node
+ and placed in the ``stat`` structure:
-**Description:**
+ - st_mode
-The following information is extracted from the filesystem specific node and
-placed in the ``stat`` structure:
+ - st_nlink
-- st_mode
+ - st_ino
-- st_nlink
+ - st_uid
-- st_ino
+ - st_gid
-- st_uid
+ - st_atime
-- st_gid
+ - st_mtime
-- st_atime
+ - st_ctime
-- st_mtime
+NOTES:
+ Both the ``stat()`` and ``lstat()`` services are implemented directly using
+ the ``fstat()`` handler. The difference in behavior is determined by how
+ the path is evaluated prior to this handler being called on a particular
+ file entity.
-- st_ctime
-
-**NOTES:**
-
-Both the ``stat()`` and ``lstat()`` services are implemented directly using the
-``fstat()`` handler. The difference in behavior is determined by how the path
-is evaluated prior to this handler being called on a particular file entity.
-
-The ``fstat()`` system call is implemented directly on top of this filesystem
-handler.
+ The ``fstat()`` system call is implemented directly on top of this
+ filesystem handler.
fchmod Handler
~~~~~~~~~~~~~~
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``fchmod()``
-fchmod()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_libio_t *iop
+ mode_t mode
-.. code-block:: c
+Description:
+ XXX
- rtems_libio_t *iop
- mode_t mode
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
+NOTES:
+ XXX
ftruncate Handler
~~~~~~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**NOTES:**
+Description:
+ XXX
-XXX
+NOTES:
+ XXX
fpathconf Handler
~~~~~~~~~~~~~~~~~
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Arguments:**
+Description:
+ XXX
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
+NOTES:
+ XXX
fsync Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**NOTES:**
+Description:
+ XXX
-XXX
+NOTES:
+ XXX
fdatasync Handler
~~~~~~~~~~~~~~~~~
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Arguments:**
+Description:
+ XXX
-XXX
-
-**Description:**
-
-XXX
-
-**NOTES:**
-
-XXX
+NOTES:
+ XXX
fcntl Handler
~~~~~~~~~~~~~
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**Description:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**NOTES:**
+Description:
+ XXX
-XXX
+NOTES:
+ XXX
diff --git a/filesystem/in-memory.rst b/filesystem/in-memory.rst
index b80d42f..937058b 100644
--- a/filesystem/in-memory.rst
+++ b/filesystem/in-memory.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
In-Memory Filesystem
-####################
+********************
This chapter describes the In-Memory FileSystem (IMFS). The IMFS is a full
featured POSIX filesystem that keeps all information in memory.
@@ -130,6 +130,8 @@ explanation of their role in the filesystem.
Miscellaneous IMFS Information
==============================
+TBD
+
Memory associated with the IMFS
===============================
@@ -197,532 +199,474 @@ function management structure.
.. COMMENT: @page
IMFS_evalpath()
-~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
IMFS_evalformake()
-~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
IMFS_link()
-~~~~~~~~~~~
+^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``link``
-link
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_location_info_t *to_loc, /* IN */
+ rtems_filesystem_location_info_t *parent_loc, /* IN */
+ const char *token /* IN */
-.. code-block:: c
-
- rtems_filesystem_location_info_t *to_loc, /* IN */
- rtems_filesystem_location_info_t *parent_loc, /* IN */
- const char *token /* IN */
-
-**File:**
-
-imfs_link.c
+File:
+ ``imfs_link.c``
-**Description:**
+Description:
-This routine is used in the IMFS filesystem to create a hard-link.
+ This routine is used in the IMFS filesystem to create a hard-link.
-It will first examine the st_nlink count of the node that we are trying to. If
-the link count exceeds LINK_MAX an error will be returned.
+ It will first examine the st_nlink count of the node that we are trying to.
+ If the link count exceeds LINK_MAX an error will be returned.
-The name of the link will be normalized to remove extraneous separators from
-the end of the name.
+ The name of the link will be normalized to remove extraneous separators
+ from the end of the name.
-IMFS_create_node will be used to create a filesystem node that will have the
-following characteristics:
+ IMFS_create_node will be used to create a filesystem node that will have
+ the following characteristics:
-- parent that was determined in the link() function in file link.c
+ - parent that was determined in the link() function in file link.c
-- Type will be set to IMFS_HARD_LINK
+ - Type will be set to IMFS_HARD_LINK
-- name will be set to the normalized name
+ - name will be set to the normalized name
-- mode of the hard-link will be set to the mode of the target node
+ - mode of the hard-link will be set to the mode of the target node
-If there was trouble allocating memory for the new node an error will be
-returned.
+ If there was trouble allocating memory for the new node an error will be
+ returned.
-The st_nlink count of the target node will be incremented to reflect the new
-link.
+ The st_nlink count of the target node will be incremented to reflect the
+ new link.
-The time fields of the link will be set to reflect the creation time of the
-hard-link.
+ The time fields of the link will be set to reflect the creation time of the
+ hard-link.
IMFS_unlink()
-~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
IMFS_node_type()
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``IMFS_node_type()``
-IMFS_node_type()
-
-**Arguments:**
-
-.. code-block:: c
+Arguments:
+ .. code-block:: c
- rtems_filesystem_location_info_t *pathloc /* IN */
+ rtems_filesystem_location_info_t *pathloc /* IN */
-**File:**
+File:
+ ``imfs_ntype.c``
-imfs_ntype.c
+Description:
+ This routine will locate the IMFS_jnode_t structure that holds ownership
+ information for the selected node in the filesystem.
-**Description:**
+ This structure is pointed to by pathloc->node_access.
-This routine will locate the IMFS_jnode_t structure that holds ownership
-information for the selected node in the filesystem.
+ The IMFS_jnode_t type element indicates one of the node types listed below:
-This structure is pointed to by pathloc->node_access.
+ - RTEMS_FILESYSTEM_DIRECTORY
-The IMFS_jnode_t type element indicates one of the node types listed below:
+ - RTEMS_FILESYSTEM_DEVICE
-- RTEMS_FILESYSTEM_DIRECTORY
+ - RTEMS_FILESYSTEM_HARD_LINK
-- RTEMS_FILESYSTEM_DEVICE
-
-- RTEMS_FILESYSTEM_HARD_LINK
-
-- RTEMS_FILESYSTEM_MEMORY_FILE
+ - RTEMS_FILESYSTEM_MEMORY_FILE
.. COMMENT: @page
IMFS_mknod()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_mknod()
-
-**Arguments:**
-
-.. code-block:: c
+^^^^^^^^^^^^
- const char *token, /* IN */
- mode_t mode, /* IN */
- dev_t dev, /* IN */
- rtems_filesystem_location_info_t *pathloc /* IN/OUT */
+Corresponding Structure Element:
+ ``IMFS_mknod()``
-**File:**
+Arguments:
+ .. code-block:: c
-imfs_mknod.c
+ const char *token, /* IN */
+ mode_t mode, /* IN */
+ dev_t dev, /* IN */
+ rtems_filesystem_location_info_t *pathloc /* IN/OUT */
-**Description:**
+File:
+ ``imfs_mknod.c``
-This routine will examine the mode argument to determine is we are trying to
-create a directory, regular file and a device node. The creation of other node
-types is not permitted and will cause an assert.
+Description:
+ This routine will examine the mode argument to determine is we are trying
+ to create a directory, regular file and a device node. The creation of
+ other node types is not permitted and will cause an assert.
-Memory space will be allocated for a ``jnode`` and the node will be set up
-according to the nodal type that was specified. The IMFS_create_node() function
-performs the allocation and setup of the node.
+ Memory space will be allocated for a ``jnode`` and the node will be set up
+ according to the nodal type that was specified. The IMFS_create_node()
+ function performs the allocation and setup of the node.
-The only problem that is currently reported is the lack of memory when we
-attempt to allocate space for the ``jnode`` (ENOMEN).
+ The only problem that is currently reported is the lack of memory when we
+ attempt to allocate space for the ``jnode`` (ENOMEN).
IMFS_rmnod()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
IMFS_chown()
-~~~~~~~~~~~~
+^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``IMFS_chown()``
-IMFS_chown()
-
-**Arguments:**
-
-.. code-block:: c
-
- rtems_filesystem_location_info_t *pathloc /* IN */
- uid_t owner /* IN */
- gid_t group /* IN */
+Arguments:
+ .. code-block:: c
-**File:**
+ rtems_filesystem_location_info_t *pathloc /* IN */
+ uid_t owner /* IN */
+ gid_t group /* IN */
-imfs_chown.c
+File:
+ ``imfs_chown.c``
-**Description:**
+Description:
+ This routine will locate the IMFS_jnode_t structure that holds ownership
+ information for the selected node in the filesystem.
-This routine will locate the IMFS_jnode_t structure that holds ownership
-information for the selected node in the filesystem.
+ This structure is pointed to by pathloc->node_access.
-This structure is pointed to by pathloc->node_access.
-
-The st_uid and st_gid fields of the node are then modified. Since this is a
-memory based filesystem, no further action is required to alter the ownership
-of the IMFS_jnode_t structure.
+ The st_uid and st_gid fields of the node are then modified. Since this is a
+ memory based filesystem, no further action is required to alter the
+ ownership of the IMFS_jnode_t structure.
IMFS_freenod()
-~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^
-IMFS_freenod()
+Corresponding Structure Element:
+ ``IMFS_freenod()``
-**Arguments:**
+Arguments:
+ .. code-block:: c
-.. code-block:: c
+ rtems_filesystem_location_info_t *pathloc /* IN */
- rtems_filesystem_location_info_t *pathloc /* IN */
+File:
+ ``imfs_free.c``
-**File:**
+Description:
+ This method is a private function to the IMFS. It is called by IMFS
+ routines to free nodes that have been allocated. Examples of where this
+ routine may be called from are unlink and rmnod.
-imfs_free.c
-
-**Description:**
-
-This method is a private function to the IMFS. It is called by IMFS routines
-to free nodes that have been allocated. Examples of where this routine may be
-called from are unlink and rmnod.
-
-Note: This routine should not be confused with the filesystem callback freenod.
-The IMFS allocates memory until the node no longer exists.
-
-IMFS_freenodinfo()
-~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+ Note: This routine should not be confused with the filesystem callback
+ freenod. The IMFS allocates memory until the node no longer exists.
IMFS_freenodinfo()
+^^^^^^^^^^^^^^^^^^
-**Arguments:**
-
-.. code-block:: c
+Corresponding Structure Element:
+ ``IMFS_freenodinfo()``
- rtems_filesystem_location_info_t *pathloc /* IN */
+Arguments:
+ .. code-block:: c
-**File:**
+ rtems_filesystem_location_info_t *pathloc /* IN */
-imfs_free.c
+File:
+ ``imfs_free.c``
-**Description:**
-
-The In-Memory File System does not need to allocate memory during the evaluate
-routines. Therefore, this routine simply routines PASS.
-
-IMFS_mount()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+Description:
+ The In-Memory File System does not need to allocate memory during the
+ evaluate routines. Therefore, this routine simply routines PASS.
IMFS_mount()
+^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ ``IMFS_mount()``
-.. code-block:: c
-
- rtems_filesystem_mount_table_entry_t *mt_entry
+Arguments:
+ .. code-block:: c
-**File:**
+ rtems_filesystem_mount_table_entry_t *mt_entry
-imfs_mount.c
+File:
+ ``imfs_mount.c``
-**Description:**
+Description:
+ This routine provides the filesystem specific processing required to mount
+ a filesystem for the system that contains the mount point. It will
+ determine if the point that we are trying to mount onto is a node of
+ IMFS_DIRECTORY type.
-This routine provides the filesystem specific processing required to mount a
-filesystem for the system that contains the mount point. It will determine if
-the point that we are trying to mount onto is a node of IMFS_DIRECTORY type.
-
-If it is the node's info element is altered so that the info.directory.mt_fs
-element points to the mount table chain entry that is associated with the
-mounted filesystem at this point. The info.directory.mt_fs element can be
-examined to determine if a filesystem is mounted at a directory. If it is NULL,
-the directory does not serve as a mount point. A non-NULL entry indicates that
-the directory does serve as a mount point and the value of info.directory.mt_fs
-can be used to locate the mount table chain entry that describes the filesystem
-mounted at this point.
+ If it is the node's info element is altered so that the
+ info.directory.mt_fs element points to the mount table chain entry that is
+ associated with the mounted filesystem at this point. The
+ info.directory.mt_fs element can be examined to determine if a filesystem
+ is mounted at a directory. If it is NULL, the directory does not serve as a
+ mount point. A non-NULL entry indicates that the directory does serve as a
+ mount point and the value of info.directory.mt_fs can be used to locate the
+ mount table chain entry that describes the filesystem mounted at this
+ point.
IMFS_fsmount_me()
-~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^
-IMFS_initialize()
+Corresponding Structure Element:
+ ``IMFS_initialize()``
-**Arguments:**
+Arguments:
+ .. code-block:: c
-.. code-block:: c
-
- rtems_filesystem_mount_table_entry_t *mt_entry
+ rtems_filesystem_mount_table_entry_t *mt_entry
-**File:**
+File:
+ ``imfs_init.c``
-imfs_init.c
+Description:
+ This function is provided with a filesystem to take care of the internal
+ filesystem management details associated with mounting that filesystem
+ under the RTEMS environment.
-**Description:**
+ It is not responsible for the mounting details associated the filesystem
+ containing the mount point.
-This function is provided with a filesystem to take care of the internal
-filesystem management details associated with mounting that filesystem under
-the RTEMS environment.
+ The rtems_filesystem_mount_table_entry_t structure contains the key
+ elements below:
-It is not responsible for the mounting details associated the filesystem
-containing the mount point.
+ .. code-block:: c
-The rtems_filesystem_mount_table_entry_t structure contains the key elements
-below:
+ rtems_filesystem_location_info_t *mt_point_node,
-.. code-block:: c
+ This structure contains information about the mount point. This allows us
+ to find the ops-table and the handling functions associated with the
+ filesystem containing the mount point.
- rtems_filesystem_location_info_t *mt_point_node,
+ .. code-block:: c
-This structure contains information about the mount point. This
-allows us to find the ops-table and the handling functions
-associated with the filesystem containing the mount point.
+ rtems_filesystem_location_info_t *fs_root_node,
-.. code-block:: c
+ This structure contains information about the root node in the file system
+ to be mounted. It allows us to find the ops-table and the handling
+ functions associated with the filesystem to be mounted.
- rtems_filesystem_location_info_t *fs_root_node,
+ .. code-block:: c
-This structure contains information about the root node in the file
-system to be mounted. It allows us to find the ops-table and the
-handling functions associated with the filesystem to be mounted.
+ rtems_filesystem_options_t options,
-.. code-block:: c
+ Read only or read/write access
- rtems_filesystem_options_t options,
+ .. code-block:: c
-Read only or read/write access
+ void *fs_info,
-.. code-block:: c
+ This points to an allocated block of memory the will be used to hold any
+ filesystem specific information of a global nature. This allocated region
+ if important because it allows us to mount the same filesystem type more
+ than once under the RTEMS system. Each instance of the mounted filesystem
+ has its own set of global management information that is separate from the
+ global management information associated with the other instances of the
+ mounted filesystem type.
- void *fs_info,
+ .. code-block:: c
-This points to an allocated block of memory the will be used to hold any
-filesystem specific information of a global nature. This allocated region if
-important because it allows us to mount the same filesystem type more than once
-under the RTEMS system. Each instance of the mounted filesystem has its own
-set of global management information that is separate from the global
-management information associated with the other instances of the mounted
-filesystem type.
+ rtems_filesystem_limits_and_options_t pathconf_info,
-.. code-block:: c
+ The table contains the following set of values associated with the mounted
+ filesystem:
- rtems_filesystem_limits_and_options_t pathconf_info,
+ - link_max
-The table contains the following set of values associated with the mounted
-filesystem:
+ - max_canon
-- link_max
+ - max_input
-- max_canon
+ - name_max
-- max_input
+ - path_max
-- name_max
+ - pipe_buf
-- path_max
+ - posix_async_io
-- pipe_buf
+ - posix_chown_restrictions
-- posix_async_io
+ - posix_no_trunc
-- posix_chown_restrictions
+ - posix_prio_io
-- posix_no_trunc
+ - posix_sync_io
-- posix_prio_io
+ - posix_vdisable
-- posix_sync_io
+ These values are accessed with the pathconf() and the fpathconf ()
+ functions.
-- posix_vdisable
+ .. code-block:: c
-These values are accessed with the pathconf() and the fpathconf () functions.
+ const char *dev
-.. code-block:: c
+ The is intended to contain a string that identifies the device that
+ contains the filesystem information. The filesystems that are currently
+ implemented are memory based and don't require a device specification.
- const char *dev
+ If the mt_point_node.node_access is NULL then we are mounting the base file
+ system.
-The is intended to contain a string that identifies the device that contains
-the filesystem information. The filesystems that are currently implemented are
-memory based and don't require a device specification.
+ The routine will create a directory node for the root of the IMFS file
+ system.
-If the mt_point_node.node_access is NULL then we are mounting the base file
-system.
+ The node will have read, write and execute permissions for owner, group and
+ others.
-The routine will create a directory node for the root of the IMFS file system.
+ The node's name will be a null string.
-The node will have read, write and execute permissions for owner, group and
-others.
+ A filesystem information structure(fs_info) will be allocated and
+ initialized for the IMFS filesystem. The fs_info pointer in the mount table
+ entry will be set to point the filesystem information structure.
-The node's name will be a null string.
+ The pathconf_info element of the mount table will be set to the appropriate
+ table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
-A filesystem information structure(fs_info) will be allocated and initialized
-for the IMFS filesystem. The fs_info pointer in the mount table entry will be
-set to point the filesystem information structure.
+ The fs_root_node structure will be filled in with the following:
-The pathconf_info element of the mount table will be set to the appropriate
-table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
+ - pointer to the allocated root node of the filesystem
-The fs_root_node structure will be filled in with the following:
+ - directory handlers for a directory node under the IMFS filesystem
-- pointer to the allocated root node of the filesystem
+ - OPS table functions for the IMFS
-- directory handlers for a directory node under the IMFS filesystem
-
-- OPS table functions for the IMFS
-
-A 0 will be returned to the calling routine if the process succeeded, otherwise
-a 1 will be returned.
+ A 0 will be returned to the calling routine if the process succeeded,
+ otherwise a 1 will be returned.
IMFS_unmount()
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``IMFS_unmount()``
-IMFS_unmount()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ rtems_filesystem_mount_table_entry_t *mt_entry
- rtems_filesystem_mount_table_entry_t *mt_entry
+File:
+ ``imfs_unmount.c``
-**File:**
+Description:
+ This routine allows the IMFS to unmount a filesystem that has been mounted
+ onto a IMFS directory.
-imfs_unmount.c
-
-**Description:**
-
-This routine allows the IMFS to unmount a filesystem that has been mounted onto
-a IMFS directory.
-
-The mount entry mount point node access is verified to be a mounted directory.
-It's mt_fs is set to NULL. This identifies to future calles into the IMFS that
-this directory node is no longer a mount point. Additionally, it will allow
-any directories that were hidden by the mounted system to again become visible.
+ The mount entry mount point node access is verified to be a mounted
+ directory. It's mt_fs is set to NULL. This identifies to future calles
+ into the IMFS that this directory node is no longer a mount point.
+ Additionally, it will allow any directories that were hidden by the mounted
+ system to again become visible.
IMFS_fsunmount()
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``imfs_fsunmount()``
-imfs_fsunmount()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_mount_table_entry_t *mt_entry
-.. code-block:: c
+File:
+ ``imfs_init.c``
- rtems_filesystem_mount_table_entry_t *mt_entry
+Description:
+ This method unmounts this instance of the IMFS file system. It is the
+ counterpart to the IMFS_initialize routine. It is called by the generic
+ code under the fsunmount_me callback.
-**File:**
-
-imfs_init.c
-
-**Description:**
-
-This method unmounts this instance of the IMFS file system. It is the
-counterpart to the IMFS_initialize routine. It is called by the generic code
-under the fsunmount_me callback.
-
-All method loops finding the first encountered node with no children and
-removing the node from the tree, thus returning allocated resources. This is
-done until all allocated nodes are returned.
+ All method loops finding the first encountered node with no children and
+ removing the node from the tree, thus returning allocated resources. This
+ is done until all allocated nodes are returned.
IMFS_utime()
-~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
IMFS_eval_link()
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Arguments:**
+File:
+ XXX
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
Regular File Handler Table Functions
------------------------------------
@@ -753,326 +697,281 @@ this function management structure.
};
memfile_open() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-memfile_open()
-
-**Arguments:**
-
-.. code-block:: c
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- rtems_libio_t *iop,
- const char *pathname,
- unsigned32 flag,
- unsigned32 mode
+Corresponding Structure Element:
+ ``memfile_open()``
-**File:**
+Arguments:
+ .. code-block:: c
-memfile.c
+ rtems_libio_t *iop,
+ const char *pathname,
+ unsigned32 flag,
+ unsigned32 mode
-**Description:**
+File:
+ ``memfile.c``
-Currently this function is a shell. No meaningful processing is performed and a
-success code is always returned.
+Description:
+ Currently this function is a shell. No meaningful processing is performed
+ and a success code is always returned.
memfile_close() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-memfile_close()
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: c
-
- rtems_libio_t *iop
+Corresponding Structure Element:
+ ``memfile_close()``
-**File:**
+Arguments:
+ .. code-block:: c
-memfile.c
+ rtems_libio_t *iop
-**Description:**
+File:
+ ``memfile.c``
-This routine is a dummy for regular files under the base filesystem. It
-performs a capture of the IMFS_jnode_t pointer from the file control block and
-then immediately returns a success status.
+Description:
+ This routine is a dummy for regular files under the base filesystem. It
+ performs a capture of the IMFS_jnode_t pointer from the file control block
+ and then immediately returns a success status.
memfile_read() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``memfile_read()``
-memfile_read()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ rtems_libio_t *iop,
+ void *buffer,
+ unsigned32 count
- rtems_libio_t *iop,
- void *buffer,
- unsigned32 count
+File:
+ ``memfile.c``
-**File:**
+Description:
+ This routine will determine the ``jnode`` that is associated with this
+ file.
-memfile.c
+ It will then call IMFS_memfile_read() with the ``jnode``, file position
+ index, buffer and transfer count as arguments.
-**Description:**
+ IMFS_memfile_read() will do the following:
-This routine will determine the ``jnode`` that is associated with this file.
+ - Verify that the ``jnode`` is associated with a memory file
-It will then call IMFS_memfile_read() with the ``jnode``, file position index,
-buffer and transfer count as arguments.
+ - Verify that the destination of the read is valid
-IMFS_memfile_read() will do the following:
+ - Adjust the length of the read if it is too long
-- Verify that the ``jnode`` is associated with a memory file
+ - Acquire data from the memory blocks associated with the file
-- Verify that the destination of the read is valid
-
-- Adjust the length of the read if it is too long
-
-- Acquire data from the memory blocks associated with the file
-
-- Update the access time for the data in the file
+ - Update the access time for the data in the file
memfile_write() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**Arguments:**
+Arguments:
+ XXX
-XXX
+File:
+ XXX
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
memfile_ioctl() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**Arguments:**
+Arguments:
+ .. code-block:: c
-.. code-block:: c
-
- rtems_libio_t *iop,
- unsigned32 command,
- void *buffer
-
-**File:**
-
-memfile.c
+ rtems_libio_t *iop,
+ unsigned32 command,
+ void *buffer
-**Description:**
+File:
+ ``memfile.c``
-The current code is a placeholder for future development. The routine returns
-a successful completion status.
+Description:
+ The current code is a placeholder for future development. The routine
+ returns a successful completion status.
memfile_lseek() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-Memfile_lseek()
-
-**Arguments:**
-
-.. code-block:: c
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- rtems_libio_t *iop,
- off_t offset,
- int whence
+Corresponding Structure Element:
+ ``Memfile_lseek()``
-**File:**
+Arguments:
+ .. code-block:: c
-memfile.c
+ rtems_libio_t *iop,
+ off_t offset,
+ int whence
-**Description:**
+File:
+ ``memfile.c``
-This routine make sure that the memory based file is sufficiently large to
-allow for the new file position index.
+Description:
+ This routine make sure that the memory based file is sufficiently large to
+ allow for the new file position index.
-The IMFS_memfile_extend() function is used to evaluate the current size of the
-memory file and allocate additional memory blocks if required by the new file
-position index. A success code is always returned from this routine.
+ The IMFS_memfile_extend() function is used to evaluate the current size of
+ the memory file and allocate additional memory blocks if required by the
+ new file position index. A success code is always returned from this
+ routine.
IMFS_stat() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_stat()
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: c
-
- rtems_filesystem_location_info_t *loc,
- struct stat *buf
+Corresponding Structure Element:
+ ``IMFS_stat()``
-**File:**
+Arguments:
+ .. code-block:: c
-imfs_stat.c
+ rtems_filesystem_location_info_t *loc,
+ struct stat *buf
-**Description:**
+File:
+ ``imfs_stat.c``
-This routine actually performs status processing for both devices and regular
-files.
+Description:
+ This routine actually performs status processing for both devices and
+ regular files.
-The IMFS_jnode_t structure is referenced to determine the type of node under
-the filesystem.
+ The IMFS_jnode_t structure is referenced to determine the type of node
+ under the filesystem.
-If the node is associated with a device, node information is extracted and
-transformed to set the st_dev element of the stat structure.
+ If the node is associated with a device, node information is extracted and
+ transformed to set the st_dev element of the stat structure.
-If the node is a regular file, the size of the regular file is extracted from
-the node.
+ If the node is a regular file, the size of the regular file is extracted
+ from the node.
-This routine rejects other node types.
+ This routine rejects other node types.
-The following information is extracted from the node and placed in the stat
-structure:
+ The following information is extracted from the node and placed in the stat
+ structure:
-- st_mode
+ - st_mode
-- st_nlink
+ - st_nlink
-- st_ino
+ - st_ino
-- st_uid
+ - st_uid
-- st_gid
+ - st_gid
-- st_atime
+ - st_atime
-- st_mtime
+ - st_mtime
-- st_ctime
+ - st_ctime
IMFS_fchmod() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-IMFS_fchmod()
+Corresponding Structure Element:
+ ``IMFS_fchmod()``
-**Arguments:**
+Arguments:
+ .. code-block:: c
-.. code-block:: c
-
- rtems_libio_t *iop
- mode_t mode
-
-**File:**
-
-imfs_fchmod.c
+ rtems_libio_t *iop
+ mode_t mode
-**Description:**
+File:
+ ``imfs_fchmod.c``
-This routine will obtain the pointer to the IMFS_jnode_t structure from the
-information currently in the file control block.
+Description:
+ This routine will obtain the pointer to the IMFS_jnode_t structure from the
+ information currently in the file control block.
-Based on configuration the routine will acquire the user ID from a call to
-getuid() or from the IMFS_jnode_t structure.
+ Based on configuration the routine will acquire the user ID from a call to
+ getuid() or from the IMFS_jnode_t structure.
-It then checks to see if we have the ownership rights to alter the mode of the
-file. If the caller does not, an error code is returned.
+ It then checks to see if we have the ownership rights to alter the mode of
+ the file. If the caller does not, an error code is returned.
-An additional test is performed to verify that the caller is not trying to
-alter the nature of the node. If the caller is attempting to alter more than
-the permissions associated with user group and other, an error is returned.
+ An additional test is performed to verify that the caller is not trying to
+ alter the nature of the node. If the caller is attempting to alter more
+ than the permissions associated with user group and other, an error is
+ returned.
-If all the preconditions are met, the user, group and other fields are set
-based on the mode calling parameter.
+ If all the preconditions are met, the user, group and other fields are set
+ based on the mode calling parameter.
memfile_ftruncate() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
No pathconf() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``NULL``
-NULL
+Arguments:
+ Not Implemented
-**Arguments:**
+File:
+ Not Implemented
-Not Implemented
-
-**File:**
-
-Not Implemented
-
-**Description:**
-
-Not Implemented
+Description:
+ Not Implemented
No fsync() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**File:**
+File:
+ XXX
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
IMFS_fdatasync() for Regular Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**File:**
+File:
+ XXX
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
Directory Handler Table Functions
---------------------------------
@@ -1103,304 +1002,259 @@ this function management structure.
};
IMFS_dir_open() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``imfs_dir_open()``
-imfs_dir_open()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ rtems_libio_t *iop,
+ const char *pathname,
+ unsigned32 flag,
+ unsigned32 mode
- rtems_libio_t *iop,
- const char *pathname,
- unsigned32 flag,
- unsigned32 mode
+File:
+ ``imfs_directory.c``
-**File:**
+Description:
+ This routine will look into the file control block to find the ``jnode``
+ that is associated with the directory.
-imfs_directory.c
+ The routine will verify that the node is a directory. If its not a
+ directory an error code will be returned.
-**Description:**
-
-This routine will look into the file control block to find the ``jnode`` that
-is associated with the directory.
-
-The routine will verify that the node is a directory. If its not a directory an
-error code will be returned.
-
-If it is a directory, the offset in the file control block will be set to 0.
-This allows us to start reading at the beginning of the directory.
+ If it is a directory, the offset in the file control block will be set
+ to 0. This allows us to start reading at the beginning of the directory.
IMFS_dir_close() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_close()
-
-**Arguments:**
-
-.. code-block:: c
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- rtems_libio_t *iop
+Corresponding Structure Element:
+ ``imfs_dir_close()``
-**File:**
+Arguments:
+ .. code-block:: c
-imfs_directory.c
+ rtems_libio_t *iop
-**Description:**
+File:
+ ``imfs_directory.c``
-This routine is a dummy for directories under the base filesystem. It
-immediately returns a success status.
+Description:
+ This routine is a dummy for directories under the base filesystem. It
+ immediately returns a success status.
IMFS_dir_read() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``imfs_dir_read``
-imfs_dir_read
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_libio_t *iop,
+ void *buffer,
+ unsigned32 count
-.. code-block:: c
-
- rtems_libio_t *iop,
- void *buffer,
- unsigned32 count
-
-**File:**
-
-imfs_directory.c
+File:
+ ``imfs_directory.c``
-**Description:**
-
-This routine will read a fixed number of directory entries from the current
-directory offset. The number of directory bytes read will be returned from this
-routine.
+Description:
+ This routine will read a fixed number of directory entries from the current
+ directory offset. The number of directory bytes read will be returned from
+ this routine.
No write() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**File:**
+Arguments:
+ XXX
-XXX
+File:
+ XXX
-**Description:**
-
-XXX
+Description:
+ XXX
No ioctl() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-ioctl
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ ``ioctl``
-**File:**
+Arguments:
+ Not supported
-Not supported
+File:
+ Not supported
-**Description:**
-
-XXX
+Description:
+ XXX
IMFS_dir_lseek() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-imfs_dir_lseek()
-
-**Arguments:**
-
-.. code-block:: c
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- rtems_libio_t *iop,
- off_t offset,
- int whence
+Corresponding Structure Element:
+ ``imfs_dir_lseek()``
-**File:**
+Arguments:
+ .. code-block:: c
-imfs_directory.c
+ rtems_libio_t *iop,
+ off_t offset,
+ int whence
-**Description:**
+File:
+ ``imfs_directory.c``
-This routine alters the offset in the file control block.
+Description:
+ This routine alters the offset in the file control block.
-No test is performed on the number of children under the current open
-directory. The imfs_dir_read() function protects against reads beyond the
-current size to the directory by returning a 0 bytes transfered to the calling
-programs whenever the file position index exceeds the last entry in the open
-directory.
+ No test is performed on the number of children under the current open
+ directory. The imfs_dir_read() function protects against reads beyond the
+ current size to the directory by returning a 0 bytes transfered to the
+ calling programs whenever the file position index exceeds the last entry in
+ the open directory.
IMFS_dir_fstat() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``imfs_dir_fstat()``
-imfs_dir_fstat()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_filesystem_location_info_t *loc,
+ struct stat *buf
-.. code-block:: c
-
- rtems_filesystem_location_info_t *loc,
- struct stat *buf
-
-**File:**
-
-imfs_directory.c
+File:
+ ``imfs_directory.c``
-**Description:**
+Description:
+ The node access information in the rtems_filesystem_location_info_t
+ structure is used to locate the appropriate IMFS_jnode_t structure. The
+ following information is taken from the IMFS_jnode_t structure and placed
+ in the stat structure:
-The node access information in the rtems_filesystem_location_info_t structure
-is used to locate the appropriate IMFS_jnode_t structure. The following
-information is taken from the IMFS_jnode_t structure and placed in the stat
-structure:
-
-- st_ino
+ - st_ino
-- st_mode
+ - st_mode
-- st_nlink
+ - st_nlink
-- st_uid
+ - st_uid
-- st_gid
+ - st_gid
-- st_atime
+ - st_atime
-- st_mtime
+ - st_mtime
-- st_ctime
+ - st_ctime
-The st_size field is obtained by running through the chain of directory entries
-and summing the sizes of the dirent structures associated with each of the
-children of the directory.
+ The st_size field is obtained by running through the chain of directory
+ entries and summing the sizes of the dirent structures associated with each
+ of the children of the directory.
IMFS_fchmod() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``IMFS_fchmod()``
-IMFS_fchmod()
+Arguments:
+ .. code-block:: c
-**Arguments:**
-
-.. code-block:: c
+ rtems_libio_t *iop
+ mode_t mode
- rtems_libio_t *iop
- mode_t mode
+File:
+ ``imfs_fchmod.c``
-**File:**
+Description:
+ This routine will obtain the pointer to the IMFS_jnode_t structure from the
+ information currently in the file control block.
-imfs_fchmod.c
+ Based on configuration the routine will acquire the user ID from a call to
+ getuid() or from the IMFS_jnode_t structure.
-**Description:**
+ It then checks to see if we have the ownership rights to alter the mode of
+ the file. If the caller does not, an error code is returned.
-This routine will obtain the pointer to the IMFS_jnode_t structure from the
-information currently in the file control block.
+ An additional test is performed to verify that the caller is not trying to
+ alter the nature of the node. If the caller is attempting to alter more
+ than the permissions associated with user group and other, an error is
+ returned.
-Based on configuration the routine will acquire the user ID from a call to
-getuid() or from the IMFS_jnode_t structure.
-
-It then checks to see if we have the ownership rights to alter the mode of the
-file. If the caller does not, an error code is returned.
-
-An additional test is performed to verify that the caller is not trying to
-alter the nature of the node. If the caller is attempting to alter more than
-the permissions associated with user group and other, an error is returned.
-
-If all the preconditions are met, the user, group and other fields are set
-based on the mode calling parameter.
+ If all the preconditions are met, the user, group and other fields are set
+ based on the mode calling parameter.
No ftruncate() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**Arguments:**
+Arguments:
+ XXX
-XXX
+File:
+ XXX
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
No fpathconf() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-fpathconf
+Corresponding Structure Element:
+ ``fpathconf``
-**Arguments:**
+Arguments:
+ Not Implemented
-Not Implemented
-
-**File:**
-
-Not Implemented
+File:
+ Not Implemented
-**Description:**
-
-Not Implemented
+Description:
+ Not Implemented
No fsync() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**File:**
+File:
+ XXX
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
IMFS_fdatasync() for Directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**File:**
+Arguments:
+ XXX
-XXX
+File:
+ XXX
-**Description:**
-
-XXX
+Description:
+ XXX
Device Handler Table Functions
------------------------------
@@ -1430,351 +1284,305 @@ function management structure.
} rtems_filesystem_file_handlers_r;
device_open() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^
-device_open()
+Corresponding Structure Element:
+ ``device_open()``
-**Arguments:**
-
-.. code-block:: c
+Arguments:
+ .. code-block:: c
- rtems_libio_t *iop,
- const char *pathname,
- unsigned32 flag,
- unsigned32 mode
+ rtems_libio_t *iop,
+ const char *pathname,
+ unsigned32 flag,
+ unsigned32 mode
-**File:**
+File:
+ ``deviceio.c``
-deviceio.c
+Description:
+ This routine will use the file control block to locate the node structure
+ for the device.
-**Description:**
+ It will extract the major and minor device numbers from the ``jnode``.
-This routine will use the file control block to locate the node structure for
-the device.
-
-It will extract the major and minor device numbers from the ``jnode``.
-
-The major and minor device numbers will be used to make a rtems_io_open()
-function call to open the device driver. An argument list is sent to the driver
-that contains the file control block, flags and mode information.
+ The major and minor device numbers will be used to make a rtems_io_open()
+ function call to open the device driver. An argument list is sent to the
+ driver that contains the file control block, flags and mode information.
device_close() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-device_close()
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ ``device_close()``
-.. code-block:: c
-
- rtems_libio_t *iop
+Arguments:
+ .. code-block:: c
-**File:**
+ rtems_libio_t *iop
-deviceio.c
+File:
+ ``deviceio.c``
-**Description:**
+Description:
+ This routine extracts the major and minor device driver numbers from the
+ IMFS_jnode_t that is referenced in the file control block.
-This routine extracts the major and minor device driver numbers from the
-IMFS_jnode_t that is referenced in the file control block.
+ It also forms an argument list that contains the file control block.
-It also forms an argument list that contains the file control block.
-
-A rtems_io_close() function call is made to close the device specified by the
-major and minor device numbers.
+ A rtems_io_close() function call is made to close the device specified by
+ the major and minor device numbers.
device_read() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``device_read()``
-device_read()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_libio_t *iop,
+ void *buffer,
+ unsigned32 count
-.. code-block:: c
+File:
+ ``deviceio.c``
- rtems_libio_t *iop,
- void *buffer,
- unsigned32 count
+Description:
+ This routine will extract the major and minor numbers for the device from
+ the - jnode- associated with the file descriptor.
-**File:**
+ A rtems_io_read() call will be made to the device driver associated with
+ the file descriptor. The major and minor device number will be sent as
+ arguments as well as an argument list consisting of:
-deviceio.c
+ - file control block
-**Description:**
+ - file position index
-This routine will extract the major and minor numbers for the device from the -
-jnode- associated with the file descriptor.
+ - buffer pointer where the data read is to be placed
-A rtems_io_read() call will be made to the device driver associated with the
-file descriptor. The major and minor device number will be sent as arguments as
-well as an argument list consisting of:
+ - count indicating the number of bytes that the program wishes to read from
+ the device
-- file control block
+ - flags from the file control block
-- file position index
-
-- buffer pointer where the data read is to be placed
-
-- count indicating the number of bytes that the program wishes to read
- from the device
-
-- flags from the file control block
-
-On return from the rtems_io_read() the number of bytes that were actually read
-will be returned to the calling program.
+ On return from the rtems_io_read() the number of bytes that were actually
+ read will be returned to the calling program.
device_write() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
device_ioctl() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``ioctl``
-ioctl
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_libio_t *iop,
+ unsigned32 command,
+ void *buffer
-.. code-block:: c
-
- rtems_libio_t *iop,
- unsigned32 command,
- void *buffer
-
-**File:**
-
-deviceio.c
+File:
+ ``deviceio.c``
-**Description:**
+Description:
+ This handler will obtain status information about a device.
-This handler will obtain status information about a device.
+ The form of status is device dependent.
-The form of status is device dependent.
+ The rtems_io_control() function uses the major and minor number of the
+ device to obtain the status information.
-The rtems_io_control() function uses the major and minor number of the device
-to obtain the status information.
+ rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
+ contains the file control block, device specific command and a buffer
+ pointer to return the device status information.
-rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
-contains the file control block, device specific command and a buffer pointer
-to return the device status information.
+ The device specific command should indicate the nature of the information
+ that is desired from the device.
-The device specific command should indicate the nature of the information that
-is desired from the device.
+ After the rtems_io_control() is processed, the buffer should contain the
+ requested device information.
-After the rtems_io_control() is processed, the buffer should contain the
-requested device information.
-
-If the device information is not obtained properly a -1 will be returned to the
-calling program, otherwise the ioctl_return value is returned.
+ If the device information is not obtained properly a -1 will be returned to
+ the calling program, otherwise the ioctl_return value is returned.
device_lseek() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-device_lseek()
+Corresponding Structure Element:
+ ``device_lseek()``
-**Arguments:**
-
-.. code-block:: c
+Arguments:
+ .. code-block:: c
- rtems_libio_t *iop,
- off_t offset,
- int whence
+ rtems_libio_t *iop,
+ off_t offset,
+ int whence
-**File:**
+File:
+ ``deviceio.c``
-deviceio.c
-
-**Description:**
-
-At the present time this is a placeholder function. It always returns a
-successful status.
+Description:
+ At the present time this is a placeholder function. It always returns a
+ successful status.
IMFS_stat() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-IMFS_stat()
+^^^^^^^^^^^^^^^^^^^^^^^
-**Arguments:**
+Corresponding Structure Element:
+ ``IMFS_stat()``
-.. code-block:: c
-
- rtems_filesystem_location_info_t *loc,
- struct stat *buf
+Arguments:
+ .. code-block:: c
-**File:**
+ rtems_filesystem_location_info_t *loc,
+ struct stat *buf
-imfs_stat.c
+File:
+ ``imfs_stat.c``
-**Description:**
+Description:
+ This routine actually performs status processing for both devices and
+ regular files.
-This routine actually performs status processing for both devices and regular files.
+ The IMFS_jnode_t structure is referenced to determine the type of node
+ under the filesystem.
-The IMFS_jnode_t structure is referenced to determine the type of node under
-the filesystem.
+ If the node is associated with a device, node information is extracted and
+ transformed to set the st_dev element of the stat structure.
-If the node is associated with a device, node information is extracted and
-transformed to set the st_dev element of the stat structure.
+ If the node is a regular file, the size of the regular file is extracted
+ from the node.
-If the node is a regular file, the size of the regular file is extracted from
-the node.
+ This routine rejects other node types.
-This routine rejects other node types.
-
-The following information is extracted from the node and placed in the stat
-structure:
+ The following information is extracted from the node and placed in the stat
+ structure:
-- st_mode
+ - st_mode
-- st_nlink
+ - st_nlink
-- st_ino
+ - st_ino
-- st_uid
+ - st_uid
-- st_gid
+ - st_gid
-- st_atime
+ - st_atime
-- st_mtime
+ - st_mtime
-- st_ctime
+ - st_ctime
IMFS_fchmod() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ ``IMFS_fchmod()``
-IMFS_fchmod()
+Arguments:
+ .. code-block:: c
-**Arguments:**
+ rtems_libio_t *iop
+ mode_t mode
-.. code-block:: c
-
- rtems_libio_t *iop
- mode_t mode
-
-**File:**
-
-imfs_fchmod.c
+File:
+ ``imfs_fchmod.c``
-**Description:**
+Description:
+ This routine will obtain the pointer to the IMFS_jnode_t structure from the
+ information currently in the file control block.
-This routine will obtain the pointer to the IMFS_jnode_t structure from the
-information currently in the file control block.
+ Based on configuration the routine will acquire the user ID from a call to
+ getuid() or from the IMFS_jnode_t structure.
-Based on configuration the routine will acquire the user ID from a call to
-getuid() or from the IMFS_jnode_t structure.
+ It then checks to see if we have the ownership rights to alter the mode of
+ the file. If the caller does not, an error code is returned.
-It then checks to see if we have the ownership rights to alter the mode of the
-file. If the caller does not, an error code is returned.
+ An additional test is performed to verify that the caller is not trying to
+ alter the nature of the node. If the caller is attempting to alter more
+ than the permissions associated with user group and other, an error is
+ returned.
-An additional test is performed to verify that the caller is not trying to
-alter the nature of the node. If the caller is attempting to alter more than
-the permissions associated with user group and other, an error is returned.
-
-If all the preconditions are met, the user, group and other fields are set
-based on the mode calling parameter.
+ If all the preconditions are met, the user, group and other fields are set
+ based on the mode calling parameter.
No ftruncate() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-XXX
+Corresponding Structure Element:
+ XXX
-**File:**
+Arguments:
+ XXX
-XXX
+File:
+ XXX
-**Description:**
-
-XXX
+Description:
+ XXX
No fpathconf() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Corresponding Structure Element:**
-
-fpathconf
-
-**Arguments:**
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-Not Implemented
-
-**File:**
+Corresponding Structure Element:
+ ``fpathconf``
-Not Implemented
+Arguments:
+ Not Implemented
-**Description:**
+File:
+ Not Implemented
-Not Implemented
+Description:
+ Not Implemented
No fsync() for Devices
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
-**Corresponding Structure Element:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Arguments:**
+File:
+ XXX
-XXX
-
-**File:**
-
-XXX
-
-**Description:**
-
-XXX
+Description:
+ XXX
No fdatasync() for Devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
Not Implemented
-**Corresponding Structure Element:**
-
-XXX
-
-**Arguments:**
-
-XXX
-
-**File:**
+Corresponding Structure Element:
+ XXX
-XXX
+Arguments:
+ XXX
-**Description:**
+File:
+ XXX
-XXX
+Description:
+ XXX
diff --git a/filesystem/index.rst b/filesystem/index.rst
index 75309df..01df7f1 100644
--- a/filesystem/index.rst
+++ b/filesystem/index.rst
@@ -4,6 +4,9 @@
RTEMS Filesystem Design Guide
=============================
+RTEMS Filesystem Design Guide
+-----------------------------
+
| COPYRIGHT (c) 1988 - 2015.
| On-Line Applications Research Corporation (OAR).
@@ -32,7 +35,7 @@ to the Community Project hosted at http://www.rtems.org/.
================ =============================
.. toctree::
- :maxdepth: 3
+ :maxdepth: 5
:numbered:
preface
diff --git a/filesystem/minature_in-memory.rst b/filesystem/minature_in-memory.rst
index 3bb994d..091ad2a 100644
--- a/filesystem/minature_in-memory.rst
+++ b/filesystem/minature_in-memory.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
Miniature In-Memory Filesystem
-##############################
+******************************
This chapter describes the Miniature In-Memory FileSystem (miniIMFS). The
miniIMFS is a reduced feature version of the IMFS designed to provide minimal
diff --git a/filesystem/mounting_and_unmounting.rst b/filesystem/mounting_and_unmounting.rst
index 00463ec..c3ef44e 100644
--- a/filesystem/mounting_and_unmounting.rst
+++ b/filesystem/mounting_and_unmounting.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
Mounting and Unmounting Filesystems
-###################################
+***********************************
Mount Points
============
diff --git a/filesystem/pathname_eval.rst b/filesystem/pathname_eval.rst
index 4813f86..af61c5e 100644
--- a/filesystem/pathname_eval.rst
+++ b/filesystem/pathname_eval.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
Pathname Evaluation
-###################
+*******************
This chapter describes the pathname evaluation process for the RTEMS Filesystem
Infrastructure.
diff --git a/filesystem/preface.rst b/filesystem/preface.rst
index e19d8b1..c80f9b3 100644
--- a/filesystem/preface.rst
+++ b/filesystem/preface.rst
@@ -4,9 +4,8 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
-=======
Preface
-=======
+*******
This document describes the implementation of the RTEMS filesystem
infrastructure. This infrastructure supports the following capabilities:
@@ -19,12 +18,12 @@ infrastructure. This infrastructure supports the following capabilities:
- Individual file and directory support for the following:
- # Permissions for read, write and execute
- # User ID
- # Group ID
- # Access time
- # Modification time
- # Creation time
+ #. Permissions for read, write and execute
+ #. User ID
+ #. Group ID
+ #. Access time
+ #. Modification time
+ #. Creation time
- Hard links to files and directories
diff --git a/filesystem/system_init.rst b/filesystem/system_init.rst
index 541ab66..94b2861 100644
--- a/filesystem/system_init.rst
+++ b/filesystem/system_init.rst
@@ -5,7 +5,7 @@
.. COMMENT: All rights reserved.
System Initialization
-#####################
+*********************
After the RTEMS initialization is performed, the application's initialization
will be performed. Part of initialization is a call to
diff --git a/filesystem/trivial_ftp.rst b/filesystem/trivial_ftp.rst
index 4ed197d..72154bc 100644
--- a/filesystem/trivial_ftp.rst
+++ b/filesystem/trivial_ftp.rst
@@ -1,7 +1,7 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Trivial FTP Client Filesystem
-#############################
+*****************************
This chapter describes the Trivial FTP (TFTP) Client Filesystem.