From daf1622eddf251d0cdb7a3d755af89930bbeadbd Mon Sep 17 00:00:00 2001
From: Joel Sherrill <joel.sherrill@OARcorp.com>
Date: Mon, 11 Oct 1999 13:50:13 +0000
Subject: New files.

---
 doc/filesystem/imfs.t     | 1875 +++++++++++++++++++++++++++++++++++++++++++++
 doc/filesystem/syscalls.t | 1093 ++++++++++++++++++++++++++
 2 files changed, 2968 insertions(+)
 create mode 100644 doc/filesystem/imfs.t
 create mode 100644 doc/filesystem/syscalls.t

(limited to 'doc/filesystem')

diff --git a/doc/filesystem/imfs.t b/doc/filesystem/imfs.t
new file mode 100644
index 0000000000..0127261d5d
--- /dev/null
+++ b/doc/filesystem/imfs.t
@@ -0,0 +1,1875 @@
+
+@chapter In-Memory File System 
+
+This chapter describes the In-Memory File System.
+
+@section OPS Table Functions
+
+OPS table functions are defined in a rtems_filesystem_operations_table
+structure.  It defines functions that are specific to a given file system.
+One table exists for each file system that is supported in the RTEMS
+configuration. The structure definition appears below and is followed by
+general developmental information on each of the functions contained in this
+function management structure.
+
+@example
+typedef struct @{
+  rtems_filesystem_evalpath_t        evalpath;
+  rtems_filesystem_evalmake_t        evalformake;
+  rtems_filesystem_link_t            link;
+  rtems_filesystem_unlink_t          unlink;
+  rtems_filesystem_node_type_t       node_type;
+  rtems_filesystem_mknod_t           mknod;
+  rtems_filesystem_rmnod_t           rmnod;
+  rtems_filesystem_chown_t           chown;
+  rtems_filesystem_freenode_t        freenod;
+  rtems_filesystem_mount_t           mount;
+  rtems_filesystem_fsmount_me_t      fsmount_me;
+  rtems_filesystem_unmount_t         unmount;
+  rtems_filesystem_fsunmount_me_t    fsunmount_me;
+  rtems_filesystem_utime_t           utime;
+  rtems_filesystem_evaluate_link_t   eval_link;
+  rtems_filesystem_symlink_t         symlink;
+@} rtems_filesystem_operations_table;
+@end example
+
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection evalpath()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection evalformake()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection link()
+
+@subheading Slot Function:
+
+link
+
+@subheading Arguments:
+
+
+@example
+rtems_filesystem_location_info_t    *to_loc,      /* IN */
+rtems_filesystem_location_info_t    *parent_loc,  /* IN */
+const char                          *token        /* IN */
+@end example
+
+@subheading File:
+
+imfs_link.c
+
+@subheading Development Comments:
+
+
+This routine is used in the IMFS file system 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.
+
+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 file system node that will have the
+following characteristics:
+
+@itemize @bullet
+
+@item parent that was determined in the link() function in file link.c
+
+@item Type will be set to IMFS_HARD_LINK
+
+@item name will be set to the normalized name
+
+@item mode of the hard-link will be set to the mode of the target node
+
+@end itemize
+
+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 time fields of the link will be set to reflect the creation time of the
+hard-link.
+
+
+@c @c @c
+
+@page
+
+@subsection unlink()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection node_type()
+
+@subheading Slot Function:
+
+IMFS_node_type()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_location_info_t    *pathloc        /* IN */
+@end example
+
+@subheading File:
+
+imfs_ntype.c
+
+@subheading Development Comments:
+
+This routine will locate the IMFS_jnode_t structure that holds ownership
+information for the selected node in the file system.
+
+This structure is pointed to by pathloc->node_access.
+
+The IMFS_jnode_t type element indicates one of the node types listed below:
+
+@itemize @bullet
+
+@item RTEMS_FILESYSTEM_DIRECTORY
+
+@item RTEMS_FILESYSTEM_DEVICE
+
+@item RTEMS_FILESYSTEM_HARD_LINK
+
+@item RTEMS_FILESYSTEM_MEMORY_FILE
+
+@end itemize
+
+@c
+@c
+@c
+
+@page
+
+@subsection mknod()
+
+@subheading Slot Function:
+
+IMFS_mknod()
+
+@subheading Arguments:
+
+@example
+const char                          *token,        /* IN */
+mode_t                               mode,         /* IN */
+dev_t                                dev,          /* IN */
+rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
+@end example
+
+@subheading File:
+
+imfs_mknod.c
+
+@subheading Development Comments:
+
+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.
+
+The only problem that is currently reported is the lack of memory when we
+attempt to allocate space for the -jnode- (ENOMEN).
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection rmnod()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection chown()
+
+@subheading Slot Function:
+
+IMFS_chown()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_location_info_t    *pathloc        /* IN */
+uid_t                                owner          /* IN */
+gid_t                                group          /* IN */
+@end example
+
+@subheading File:
+
+imfs_chown.c
+
+@subheading Development Comments:
+
+This routine will locate the IMFS_jnode_t structure that holds ownership
+information for the selected node in the file system.
+
+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 file system, no further action is required to alter the
+ownership of the IMFS_jnode_t structure.
+
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection freenod()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX 
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection mount()
+
+@subheading Slot Function:
+
+IMFS_mount()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_mount_table_entry_t   *mt_entry
+@end example
+
+@subheading File:
+
+imfs_mount.c
+
+@subheading Development Comments:
+
+This routine provides the file system specific processing required to mount a
+file system 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 file system at this point. The info.directory.mt_fs element can be
+examined to determine if a file system 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 file system mounted at this point.
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection fsmount_me()
+
+@subheading Slot Function:
+
+IMFS_initialize()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_mount_table_entry_t   *mt_entry    
+@end example
+
+@subheading File:
+
+imfs_init.c
+
+@subheading Development Comments:
+
+This function is provided with a file system to take care of the internal
+file system management details associated with mounting that file system
+under the RTEMS environment.
+
+It is not responsible for the mounting details associated the file system
+containing the mount point.
+
+The rtems_filesystem_mount_table_entry_t structure contains the key elements
+below:
+
+rtems_filesystem_location_info_t         *mt_point_node,
+
+This structure contains information about the mount point. This 
+allows us to find the ops-table and the handling functions 
+associated with the file system containing the mount point.
+
+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 file system to be mounted.
+
+rtems_filesystem_options_t                 options,
+
+Read only or read/write access
+
+void                                         *fs_info,
+
+This points to an allocated block of memory the will be used to 
+hold any file system specific information of a global nature. This 
+allocated region if important because it allows us to mount the 
+same file system type more than once under the RTEMS system. 
+Each instance of the mounted file system has its own set of global 
+management information that is separate from the global 
+management information associated with the other instances of the 
+mounted file system type.
+
+rtems_filesystem_limits_and_options_t    pathconf_info,
+
+The table contains the following set of values associated with the 
+mounted file system:
+
+@itemize @bullet
+
+@item link_max
+
+@item max_canon
+
+@item max_input
+
+@item name_max
+
+@item path_max
+
+@item pipe_buf
+
+@item posix_async_io
+
+@item posix_chown_restrictions
+
+@item posix_no_trunc
+
+@item posix_prio_io
+
+@item posix_sync_io
+
+@item posix_vdisable
+
+@end itemize
+
+These values are accessed with the pathconf() and the fpathconf ()  
+functions.
+
+const char                                   *dev
+
+The is intended to contain a string that identifies the device that contains
+the file system information. The file systems 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.
+
+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's name will be a null string.
+
+A file system information structure(fs_info) will be allocated and
+initialized for the IMFS file system. The fs_info pointer in the mount table
+entry will be set to point the file system information structure.
+
+The pathconf_info element of the mount table will be set to the appropriate
+table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
+
+The fs_root_node structure will be filled in with the following:
+
+@itemize @bullet
+
+@item pointer to the allocated root node of the file system
+
+@item directory handlers for a directory node under the IMFS file system
+
+@item OPS table functions for the IMFS
+
+@end itemize
+
+A 0 will be returned to the calling routine if the process succeeded,
+otherwise a 1 will be returned.
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection unmount()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX 
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection fsunmount_me()
+
+@subheading Slot Function:
+
+imfs_fsunmount_me()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_mount_table_entry_t   *mt_entry    
+@end example
+
+@subheading File:
+
+imfs_fsunmount_me.c
+
+@subheading Development Comments:
+
+XXX 
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection utime()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX 
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection eval_link()
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+@page
+@section Handler Table Functions for Regular Files
+
+Handler table functions are defined in a rtems_filesystem_file_handlers_r
+structure. It defines functions that are specific to a node type in a given
+file system. One table exists for each of the file system's node types. The
+structure definition appears below. It is followed by general developmental
+information on each of the functions associated with regular files contained
+in this function management structure.
+
+@example
+typedef struct @{
+    rtems_filesystem_open_t           open;
+    rtems_filesystem_close_t          close;
+    rtems_filesystem_read_t           read;
+    rtems_filesystem_write_t          write;
+    rtems_filesystem_ioctl_t          ioctl;
+    rtems_filesystem_lseek_t          lseek;
+    rtems_filesystem_fstat_t          fstat;
+    rtems_filesystem_fchmod_t         fchmod;
+    rtems_filesystem_ftruncate_t      ftruncate;
+    rtems_filesystem_fpathconf_t      fpathconf;
+    rtems_filesystem_fsync_t          fsync;
+    rtems_filesystem_fdatasync_t      fdatasync;
+@} rtems_filesystem_file_handlers_r;
+@end example
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection open() for Regular File
+
+@subheading Slot Function:
+
+memfile_open()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t   *iop,
+const char      *pathname,
+unsigned32       flag,
+unsigned32       mode
+@end example
+
+@subheading File:
+
+memfile.c
+
+@subheading Development Comments:
+
+Currently this function is a shell. No meaningful processing is performed and
+a success code is always returned.
+
+@c
+@c
+@c
+
+@page
+
+@subsection close() for Regular File
+
+@subheading Slot Function:
+
+memfile_close()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop
+@end example
+
+@subheading File:
+
+memfile.c
+
+@subheading Development Comments:
+
+This routine is a dummy for regular files under the base file system. It
+performs a capture of the IMFS_jnode_t pointer from the file control block
+and then immediately returns a success status.
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection read() for Regular File
+
+@subheading Slot Function:
+
+memfile_read()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+void              *buffer,
+unsigned32         count
+@end example
+
+@subheading File:
+
+memfile.c
+
+@subheading Development Comments:
+
+This routine will determine the -jnode- that is associated with this file.
+
+It will then call IMFS_memfile_read() with the -jnode-, file position index,
+buffer and transfer count as arguments.
+
+IMFS_memfile_read() will do the following:
+
+@itemize @bullet
+
+@item Verify that the -jnode- is associated with a memory file
+
+@item Verify that the destination of the read is valid
+
+@item Adjust the length of the read if it is too long
+
+@item Acquire data from the memory blocks associated with the file
+
+@item Update the access time for the data in the file
+
+@end itemize
+
+@c
+@c
+@c
+
+@page
+
+@subsection write() for Regular File
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@subsection ioctl() for Regular File
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+unsigned32       command,
+void              *buffer
+@end example
+
+@subheading File:
+
+memfile.c
+
+@subheading Development Comments:
+
+The current code is a placeholder for future development. The routine returns
+a successful completion status.
+
+@c
+@c
+@c
+
+@page
+
+@subsection lseek() for Regular File
+
+@subheading Slot Function:
+
+Memfile_lseek()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+off_t              offset,
+int                whence
+@end example
+
+@subheading File:
+
+memfile.c
+
+@subheading Development Comments:
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@subsection fstat() for Regular File
+
+@subheading Slot Function:
+
+IMFS_stat()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_location_info_t   *loc,
+struct stat                        *buf
+@end example
+
+@subheading File:
+
+imfs_stat.c
+
+@subheading Development Comments:
+
+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 file system.
+
+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.
+
+This routine rejects other node types.
+
+The following information is extracted from the node and placed in the stat
+structure:
+
+@itemize @bullet
+
+@item st_mode
+
+@item st_nlink
+
+@item st_ino
+
+@item st_uid
+
+@item st_gid
+
+@item st_atime
+
+@item st_mtime
+
+@item st_ctime
+
+@end itemize
+
+@c
+@c
+@c
+
+@page
+
+@subsection fchmod() for Regular File
+
+@subheading Slot Function:
+
+IMFS_fchmod()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop
+mode_t              mode
+@end example
+
+@subheading File:
+
+imfs_fchmod.c
+
+@subheading Development Comments:
+
+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.
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@subsection ftruncate() for Regular File
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@subsection fpathconf() for Regular File
+
+@subheading Slot Function:
+
+NULL
+
+@subheading Arguments:
+
+Not Implemented
+
+@subheading File:
+
+Not Implemented
+
+@subheading Development Comments:
+
+Not Implemented
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection fsync() for Regular File
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection fdatasync() for Regular File
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+@page
+@section Handler Table Functions for Directories
+
+Handler table functions are defined in a rtems_filesystem_file_handlers_r
+structure. It defines functions that are specific to a node type in a given
+file system. One table exists for each of the file system's node types. The
+structure definition appears below. It is followed by general developmental
+information on each of the functions associated with directories contained in
+this function management structure.
+
+@example
+typedef struct @{
+    rtems_filesystem_open_t           open;
+    rtems_filesystem_close_t          close;
+    rtems_filesystem_read_t           read;
+    rtems_filesystem_write_t          write;
+    rtems_filesystem_ioctl_t          ioctl;
+    rtems_filesystem_lseek_t          lseek;
+    rtems_filesystem_fstat_t          fstat;
+    rtems_filesystem_fchmod_t         fchmod;
+    rtems_filesystem_ftruncate_t      ftruncate;
+    rtems_filesystem_fpathconf_t      fpathconf;
+    rtems_filesystem_fsync_t          fsync;
+    rtems_filesystem_fdatasync_t      fdatasync;
+@} rtems_filesystem_file_handlers_r;
+@end example
+
+
+@c
+@c
+@c
+
+@page
+
+@section open() for Directories
+
+@subheading Slot Function:
+
+imfs_dir_open()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t  *iop,
+const char     *pathname,
+unsigned32      flag,
+unsigned32      mode
+@end example
+
+@subheading File:
+
+imfs_directory.c
+
+@subheading Development Comments:
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@section close() for Directories
+
+@subheading Slot Function:
+
+imfs_dir_close()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop
+@end example
+
+@subheading File:
+
+imfs_directory.c
+
+@subheading Development Comments:
+
+This routine is a dummy for directories under the base file system. It
+immediately returns a success status.
+
+@c
+@c
+@c
+
+@page
+
+@section read() for Directories
+
+@subheading Slot Function:
+
+imfs_dir_read
+
+@subheading Arguments:
+
+@example
+rtems_libio_t  *iop,
+void           *buffer,
+unsigned32      count
+@end example
+
+@subheading File:
+
+imfs_directory.c
+
+@subheading Development Comments:
+
+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.
+
+
+@c
+@c
+@c
+
+@page
+
+@section write() for Directories
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@section ioctl() for Directories
+
+@subheading Slot Function:
+
+ioctl
+
+@subheading Arguments:
+
+
+@subheading File:
+
+Not supported
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@section lseek() for Directories
+
+@subheading Slot Function:
+
+imfs_dir_lseek()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t      *iop,
+off_t               offset,
+int                 whence
+@end example
+
+@subheading File:
+
+imfs_directory.c
+
+@subheading Development Comments:
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@section fstat() for Directories
+
+@subheading Slot Function:
+
+imfs_dir_fstat()
+
+@subheading Arguments:
+
+
+@example
+rtems_filesystem_location_info_t   *loc,
+struct stat                        *buf
+@end example
+
+@subheading File:
+
+imfs_directory.c
+
+@subheading Development Comments:
+
+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:
+
+@itemize @bullet
+@item st_ino
+@item st_mode
+@item st_nlink
+@item st_uid
+@item st_gid
+@item st_atime
+@item st_mtime
+@item st_ctime
+@end itemize
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@section fchmod() for Directories
+
+@subheading Slot Function:
+
+IMFS_fchmod()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop
+mode_t             mode
+@end example
+
+@subheading File:
+
+imfs_fchmod.c
+
+@subheading Development Comments:
+
+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.
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@section ftruncate() for Directories
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@section fpathconf() for Directories
+
+@subheading Slot Function:
+
+fpathconf
+
+@subheading Arguments:
+
+Not Implemented
+
+@subheading File:
+
+Not Implemented
+
+@subheading Development Comments:
+
+Not Implemented
+
+
+@c
+@c
+@c
+
+@page
+
+@section fsync() for Directories
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@section fdatasync() for Directories
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@section Handler Table Functions for Devices
+
+Handler table functions are defined in a rtems_filesystem_file_handlers_r
+structure. It defines functions that are specific to a node type in a given
+file system. One table exists for each of the file system's node types. The
+structure definition appears below. It is followed by general developmental
+information on each of the functions associated with devices contained in
+this function management structure.
+
+@example
+typedef struct @{
+  rtems_filesystem_open_t           open;
+  rtems_filesystem_close_t          close;
+  rtems_filesystem_read_t           read;
+  rtems_filesystem_write_t          write;
+  rtems_filesystem_ioctl_t          ioctl;
+  rtems_filesystem_lseek_t          lseek;
+  rtems_filesystem_fstat_t          fstat;
+  rtems_filesystem_fchmod_t         fchmod;
+  rtems_filesystem_ftruncate_t      ftruncate;
+  rtems_filesystem_fpathconf_t      fpathconf;
+  rtems_filesystem_fsync_t          fsync;
+  rtems_filesystem_fdatasync_t      fdatasync;
+@} rtems_filesystem_file_handlers_r;
+@end example
+
+@c
+@c
+@c
+
+@page
+
+@section open() for Devices
+
+@subheading Slot Function:
+
+device_open()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+const char        *pathname,
+unsigned32         flag,
+unsigned32         mode
+@end example
+
+@subheading File:
+
+deviceio.c
+
+@subheading Development Comments:
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@section close() for Devices
+
+@subheading Slot Function:
+
+device_close()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop
+@end example
+
+@subheading File:
+
+deviceio.c
+
+@subheading Development Comments:
+
+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.
+
+A rtems_io_close() function call is made to close the device specified by the
+major and minor device numbers.
+
+
+@c
+@c
+@c
+
+@page
+
+@section read() for Devices
+
+@subheading Slot Function:
+
+device_read()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+void              *buffer,
+unsigned32         count
+@end example
+
+@subheading File:
+
+deviceio.c
+
+@subheading Development Comments:
+
+This routine will extract the major and minor numbers for the device from the -
+jnode- associated with the file descriptor.
+
+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:
+
+@itemize @bullet
+@item file control block
+
+@item file position index
+
+@item buffer pointer where the data read is to be placed
+
+@item count indicating the number of bytes that the program wishes to read 
+from the device
+
+@item flags from the file control block
+
+@end itemize
+
+On return from the rtems_io_read() the number of bytes that were actually
+read will be returned to the calling program.
+
+
+@c
+@c
+@c
+
+@page
+
+@section write() for Devices
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@section ioctl() for Devices
+
+@subheading Slot Function:
+
+ioctl
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+unsigned32         command,
+void              *buffer
+@end example
+
+@subheading File:
+
+deviceio.c
+
+@subheading Development Comments:
+
+This handler will obtain status information about a device.
+
+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.
+
+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.
+
+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.
+
+@c
+@c
+@c
+
+@page
+
+@section lseek() for Devices
+
+@subheading Slot Function:
+
+device_lseek()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop,
+off_t              offset,
+int                whence
+@end example
+
+@subheading File:
+
+deviceio.c
+
+@subheading Development Comments:
+
+At the present time this is a placeholder function. It always returns a
+successful status.
+
+@c
+@c
+@c
+
+@page
+
+@section fstat() for Devices
+
+@subheading Slot Function:
+
+IMFS_stat()
+
+@subheading Arguments:
+
+@example
+rtems_filesystem_location_info_t   *loc,
+struct stat                        *buf
+@end example
+
+@subheading File:
+
+imfs_stat.c
+
+@subheading Development Comments:
+
+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 
+file system. 
+
+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.
+
+This routine rejects other node types.
+
+The following information is extracted from the node and placed in the stat 
+structure:
+
+@itemize @bullet
+
+@item st_mode
+
+@item st_nlink
+
+@item st_ino
+
+@item st_uid
+
+@item st_gid
+
+@item st_atime
+
+@item st_mtime
+
+@item st_ctime
+
+@end itemize
+
+
+
+@c
+@c
+@c
+
+@page
+
+@section fchmod() for Devices
+
+@subheading Slot Function:
+
+IMFS_fchmod()
+
+@subheading Arguments:
+
+@example
+rtems_libio_t     *iop
+mode_t             mode
+@end example
+
+@subheading File:
+
+imfs_fchmod.c
+
+@subheading Development Comments:
+
+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.
+
+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.
+
+
+@c
+@c
+@c
+
+@page
+
+@section ftruncate() for Devices
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@c
+@c
+@c
+
+@page
+
+@section fpathconf() for Devices
+
+@subheading Slot Function:
+
+fpathconf
+
+@subheading Arguments:
+
+Not Implemented
+
+@subheading File:
+
+Not Implemented
+
+@subheading Development Comments:
+
+Not Implemented
+
+
+@c
+@c
+@c
+
+@page
+
+@section fsync() for Devices
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+
+@c
+@c
+@c
+
+@page
+
+@subsection fdatasync() for Devices
+
+Not Implemented
+
+@subheading Slot Function:
+
+XXX
+
+@subheading Arguments:
+
+XXX
+
+@subheading File:
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
diff --git a/doc/filesystem/syscalls.t b/doc/filesystem/syscalls.t
new file mode 100644
index 0000000000..7948a8796a
--- /dev/null
+++ b/doc/filesystem/syscalls.t
@@ -0,0 +1,1093 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter System Call Development Notes
+
+This set of routines represents the application's interface to files and directories 
+under the RTEMS file system. All routines are compliant with POSIX standards if a 
+specific interface has been established. The list below represents the routines that have 
+been included as part of the application's interface.
+
+@enumerate
+@item access()
+@item chdir()
+@item chmod()
+@item chown()
+@item close()
+@item closedir()
+@item dup()
+@item dup2()
+@item fchmod()
+@item fcntl()
+@item fdatasync()
+@item fpathconf()
+@item fstat()
+@item ioctl()
+@item link()
+@item lseek()
+@item mkdir()
+@item mkfifo()
+@item mknod()
+@item mount()
+@item open()
+@item opendir()
+@item pathconf()
+@item read()
+@item readdir()
+@item unmount()
+@end enumerate
+
+The sections that follow provide developmental information concerning each of these functions.
+
+ 
+@page
+@section access
+
+@subheading File:
+
+access.c
+
+@subheading Processing: 
+
+This routine is layered on the stat() function. It acquires the current status 
+information for the specified file and then determines if the caller has the ability 
+to access the file for read, write or execute according to the mode argument to this 
+function.
+
+@subheading Development Comments:
+
+This routine is layered on top of the stat() function. As long as the st_mode 
+element in the returned structure follow the standard UNIX conventions, this 
+function should support other file systems without alteration.
+
+@page
+@section chdir
+
+@subheading File:
+
+chdir.c
+
+
+@subheading Processing: 
+
+This routine will determine if the pathname that we are attempting to make that 
+current directory exists and is in fact a directory. If these conditions are met the 
+global indication of the current directory (rtems_filesystem_current) is set to the 
+rtems_filesystem_location_info_t structure that is returned by the 
+rtems_filesystem_evaluate_path() routine.
+
+@subheading Development Comments:
+
+This routine is layered on the rtems_filesystem_evaluate_path() routine and the 
+file system specific OP table function node_type().
+
+The routine node_type() must be a routine provided for each file system since it 
+must access the file systems node information to determine which of the 
+following types the node is:
+
+@itemize @bullet
+@item RTEMS_FILESYSTEM_DIRECTORY
+@item RTEMS_FILESYSTEM_DEVICE
+@item RTEMS_FILESYSTEM_HARD_LINK
+@item RTEMS_FILESYSTEM_MEMORY_FILE
+@end itemize
+
+This acknowledges that the form of the node management information can vary 
+from one file system 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.
+
+@page
+@section chmod
+
+@subheading File:
+
+chmod.c
+
+@subheading Processing: 
+
+This routine is layered on the open(), fchmod () and close () functions. As long as 
+the standard interpretation of the mode_t value is maintained, this routine should 
+not need modification to support other file systems.
+
+@subheading Development Comments:
+
+The routine first determines if the selected file can be open with read/write access. 
+This is required to allow modification of the mode associated with the selected 
+path. 
+
+The 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.
+
+@page
+@section chown
+
+@subheading File:
+
+chown.c
+
+@subheading Processing: 
+
+This routine is layered on the rtems_filesystem_evaluate_path() and the file 
+system specific chown() routine that is specified in the OPS table for the file 
+system.
+
+@subheading Development Comments:
+
+rtems_filesystem_evaluate_path() is used to determine if the path specified 
+actually exists. If it does a rtems_filesystem_location_info_t structure will be 
+obtained that allows the shell function to locate the OPS table that is to be used 
+for this file system.
+
+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.
+
+@page
+@section close
+
+@subheading File:
+
+close.c
+
+@subheading Processing: 
+
+This routine will allow for the closing of both network connections and file 
+system devices. If the file descriptor is associated with a network device, the 
+appropriate network function handler will be selected from a table of previously 
+registered network functions (rtems_libio_handlers) and that function will be 
+invoked.
+
+If the file descriptor refers to an entry in the file system, the appropriate handler 
+will be selected using information that has been placed in the file control block for 
+the device (rtems_libio_t structure).
+
+@subheading Development Comments:
+
+rtems_file_descriptor_type examines some of the upper bits of the file descriptor 
+index. If it finds that the upper bits are set in the file descriptor index, the device 
+referenced is a network device.
+
+Network device handlers are obtained from a special registration table 
+(rtems_libio_handlers) that is set up during network initialization. The network 
+handler invoked and the status of the network handler will be returned to the 
+calling process.
+
+If none of the upper bits are set in the file descriptor index, the file descriptor 
+refers to an element of the RTEMS file system.
+
+The following sequence will be performed for any file system file descriptor:
+
+@enumerate
+
+@item Use the rtems_libio_iop() function to obtain the rtems_libio_t structure for the 
+file descriptor
+
+@item Range check the file descriptor using rtems_libio_check_fd()
+
+@item Determine if there is actually a function in the selected handler table that 
+processes the close() operation for the file system and node type selected. 
+This is generally done to avoid execution attempts on functions that have not 
+been implemented.
+
+@item If the function has been defined it is invoked with the file control block 
+pointer as its argument.
+
+@item The file control block that was associated with the open file descriptor is 
+marked as free using rtems_libio_free().
+
+@item The return code from the close handler is then passed back to the calling 
+program.
+
+@end enumerate
+
+@page
+@section closedir
+
+@subheading File:
+
+closedir.c
+
+@subheading Processing: 
+
+The code was obtained from the BSD group. This routine must clean up the 
+memory resources that are required to track an open directory. The code is layered 
+on the close() function and standard memory free () functions. It should not 
+require alterations to support other file systems.
+
+@subheading Development Comments:
+
+The routine alters the file descriptor and the index into the DIR structure to make 
+it an invalid file descriptor. Apparently the memory that is about to be freed may 
+still be referenced before it is reallocated.
+
+The 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.
+
+
+@page
+@section dup()      Unimplemented
+
+@subheading File:
+
+dup.c
+
+@subheading Processing: 
+
+
+@subheading Development Comments:
+
+
+
+
+
+@page
+@section dup2()      Unimplemented
+
+@subheading File:
+
+dup2.c
+
+@subheading Processing: 
+
+
+@subheading Development Comments:
+
+
+
+
+
+
+@page
+@section fchmod
+
+@subheading File:
+
+fchmod.c
+
+@subheading Processing: 
+
+This routine will alter the permissions of a node in a file system. It is layered on 
+the following functions and macros:
+
+@itemize @bullet
+@item rtems_file_descriptor_type()
+
+@item rtems_libio_iop()
+
+@item rtems_libio_check_fd()
+
+@item rtems_libio_check_permissions()
+
+@item fchmod() function that is referenced by the handler table in the file control block associated with this file descriptor
+
+@end itemize
+
+@subheading Development Comments:
+
+The routine will test to see if the file descriptor index is associated with a network 
+connection. If it is, an error is returned from this routine.
+
+The file descriptor index is used to obtain the associated file control block.
+
+The file descriptor value is range checked.
+
+The file control block is examined to determine if it has write permissions to 
+allow us to alter the mode of the file.
+
+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.
+
+@page
+@section fcntl()
+
+@subheading File:
+
+fcntl.c
+
+@subheading Processing: 
+
+This routine currently only interacts with the file control block. If the structure of 
+the file control block and the associated meanings do not change, the partial 
+implementation of fcntl() should remain unaltered for other file system 
+implementations.
+
+@subheading Development Comments:
+
+The only commands that have been implemented are the F_GETFD and 
+F_SETFD. The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC 
+bit in the -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:
+
+@enumerate
+
+@item Test to see if we are trying to operate on a file descriptor associated with a 
+network connection
+
+@item Obtain the file control block that is associated with the file descriptor index
+
+@item Perform a range check on the file descriptor index.
+
+@end enumerate
+
+
+
+@page
+@section fdatasync
+
+@subheading File:
+
+fdatasync.c
+
+@subheading Processing: 
+
+This routine is a template in the in memory file system that will route us to the 
+appropriate handler function to carry out the fdatasync() processing. In the in 
+memory file system 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:
+
+@itemize @bullet
+
+@item rtems_file_descriptor_type()
+
+@item rtems_libio_iop()
+
+@item rtems_libio_check_fd()
+
+@item rtems_libio_check_permissions()
+
+@item fdatasync() function that is referenced by the handler table in the file control block associated with this file descriptor
+
+@end itemize
+
+@subheading Development Comments:
+
+The routine will test to see if the file descriptor index is associated with a network 
+connection. If it is, an error is returned from this routine.
+
+The file descriptor index is used to obtain the associated file control block.
+
+The file descriptor value is range checked.
+
+The file control block is examined to determine if it has write permissions to the 
+file.
+
+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.
+
+@page
+@section fpathconf
+
+@subheading File:
+
+fpathconf.c
+
+@subheading Processing: 
+
+This routine is layered on the following functions and macros:
+
+@itemize @bullet
+
+@item rtems_file_descriptor_type()
+
+@item rtems_libio_iop()
+
+@item rtems_libio_check_fd()
+
+@item rtems_libio_check_permissions()
+
+@end itemize
+
+When a file system is mounted, a set of constants is specified for the file system. 
+These constants are stored with the mount table entry for the file system. These 
+constants appear in the POSIX standard and are listed below.
+
+@itemize @bullet
+
+@item PCLINKMAX
+
+@item PCMAXCANON
+
+@item PCMAXINPUT
+
+@item PCNAMEMAX
+
+@item PCPATHMAX
+
+@item PCPIPEBUF
+
+@item PCCHOWNRESTRICTED
+
+@item PCNOTRUNC
+
+@item PCVDISABLE
+
+@item PCASYNCIO
+
+@item PCPRIOIO
+
+@item PCSYNCIO
+
+
+@end itemize
+
+This routine will find the mount table information associated the file control block 
+for the specified file descriptor parameter. The mount table entry structure 
+contains a set of file system specific constants that can be accessed by individual 
+identifiers. 
+
+@subheading Development Comments:
+
+The routine will test to see if the file descriptor index is associated with a network 
+connection. If it is, an error is returned from this routine.
+
+The file descriptor index is used to obtain the associated file control block.
+
+The file descriptor value is range checked.
+
+The file control block is examined to determine if it has read permissions to the 
+file.
+
+Pathinfo in the file control block is used to locate the mount table entry for the 
+file system 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 file system. 
+
+The name argument is used to reference the desired constant from the 
+pathconf_limits_and_options table.
+
+
+@page
+@section fstat
+
+@subheading File:
+
+fstat.c
+
+@subheading Processing: 
+
+This routine will return information concerning a file or network connection. If 
+the file descriptor is associated with a network connection, the current 
+implementation of fstat() will return a mode set to S_IFSOCK. In a later version, 
+this routine will map the status of a network connection to an external handler 
+routine. 
+
+If the file descriptor is associated with a node under a file system, the fstat() 
+routine will map to the fstat() function taken from the node handler table. 
+
+@subheading Development Comments:
+
+This routine validates that the struct stat pointer is not NULL so that the return 
+location is valid.
+
+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.
+
+If the file descriptor is associated with a node under a file system, the following 
+steps are performed:
+
+@enumerate
+
+@item Obtain the file control block that is associated with the file descriptor 
+index.
+
+@item Range check the file descriptor index.
+
+@item Test to see if there is a non-NULL function pointer in the handler table 
+for the fstat() function. If there is, invoke the function with the file 
+control block and the pointer to the stat structure.
+
+@end enumerate
+
+@page
+@section ioctl
+
+@subheading File:
+
+ioctl.c
+
+@subheading Processing: 
+
+Not defined in the POSIX 1003.1b standard but commonly supported in most 
+UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine is 
+layered on external network handlers and file system specific handlers. The 
+development of new file systems should not alter the basic processing performed 
+by this routine.
+
+@subheading Development Comments:
+
+
+The file descriptor is examined to determine if it is associated with a network 
+device. If it is processing is mapped to an external network handler. The value 
+returned by this handler is then returned to the calling program.
+
+File descriptors that are associated with a file system undergo the following 
+processing:
+
+@enumerate
+
+@item The file descriptor index is used to obtain the associated file control block.
+
+@item The file descriptor value is range checked.
+
+@item A test is made to determine if the handler table that is referenced in the file 
+control block contains an entry for the ioctl() handler function. If it does 
+not, an error is returned to the calling routine.
+
+@item If the ioctl() handler function exists, it is called with the file control block, 
+the command and buffer as its parameters.
+
+@item The return code from this function is then sent to the calling routine.
+
+@end enumerate
+
+
+@page
+@section link
+
+@subheading File:
+
+link.c
+
+@subheading Processing: 
+
+This routine will establish a hard link to a file, directory or a device. The target of 
+the hard link must be in the same file system as the new link being created. A link 
+to an existing link is also permitted but the existing link is evaluated before the 
+new link is made. This implies that links to links are reduced to links to files, 
+directories or devices before they are made.
+
+@subheading Development Comments:
+
+Calling parameters:
+const char   *existing
+    const char   *new
+
+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 file system; otherwise the 
+search will start from the current directory.
+
+The OPS table evalformake() function for the parent's file system 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 file system boundary. This is not permitted for hard-links.
+
+If the hard-link does not cross a file system 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 file system.
+
+The return code from the OPS table link() function is returned to the calling 
+program.
+
+@page
+@section lseek
+
+@subheading File:
+
+lseek.c
+
+@subheading Processing: 
+
+This routine is layered on both external handlers and file system / node type 
+specific handlers. This routine should allow for the support of new file systems 
+without modification.
+
+@subheading Development Comments:
+
+This routine will determine if the file descriptor is associated with a network 
+device. If it is lseek will map to an external network handler. The handler will be 
+called with the file descriptor, offset and whence as its calling parameters. The 
+return code from the external handler will be returned to the calling routine.
+
+If the file descriptor is not associated with a network connection, it is associated 
+with a node in a file system. The following steps will be performed for file system nodes:
+
+@enumerate
+
+@item The file descriptor is used to obtain the file control block for the node.
+
+@item The file descriptor is range checked.
+
+@item The offset element of the file control block is altered as indicated by 
+the offset and whence calling parameters
+
+@item The handler table in the file control block is examined to determine if 
+it contains an entry for the lseek() function. If it does not an error is 
+returned to the calling program.
+
+@item The lseek() function from the designated handler table is called with 
+the file control block, offset and whence as calling arguments
+
+@item The return code from the lseek() handler function is returned to the 
+calling program
+
+@end enumerate
+
+
+@page
+@section mkdir
+
+@subheading File:
+
+mkdir.c
+
+@subheading Processing: 
+
+This routine attempts to create a directory node under the file system. The routine 
+is layered the mknod() function. 
+
+@subheading Development Comments:
+
+See mknod() for developmental comments.
+
+@page
+@section mkfifo
+
+@subheading File:
+
+mkfifo.c
+
+@subheading Processing: 
+
+This routine attempts to create a FIFO node under the file system. The routine is 
+layered the mknod() function. 
+
+@subheading Development Comments:
+
+See mknod() for developmental comments
+
+@page
+@section mknod
+
+@subheading File:
+
+mknod.c
+
+@subheading Processing: 
+
+This function will allow for the creation of the following types of nodes under the 
+file system:
+
+@itemize @bullet
+
+@item directories
+
+@item regular files
+
+@item character devices
+
+@item block devices
+
+@item fifos
+
+@end itemize
+
+At the present time, an attempt to create a FIFO will result in an ENOTSUP error 
+to the calling function. This routine is layered the file system specific routines 
+evalformake and mknod. The introduction of a new file system must include its 
+own evalformake and mknod function to support the generic mknod() function. 
+Under this condition the generic mknod() function should accommodate other 
+file system types without alteration. 
+
+@subheading Development Comments:
+
+Test for nodal types - I thought that this test should look like the following code:
+
+@example
+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);
+
+@end example
+
+Where:
+
+@itemize @bullet
+@item S_IFREG (0100000) - Creation of a regular file
+@item S_IFCHR (0020000) - Creation of a character device
+@item S_IFBLK (0060000) - Creation of a block device
+@item S_IFIFO (0010000) - Creation of a FIFO
+@end itemize
+
+Determine if the pathname that we are trying to create starts at the root directory 
+or is relative to the current directory using the rtems_filesystem_get_start_loc() 
+function.
+
+Determine if the pathname 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 file system 
+specific mknod() function exists.
+
+If the mknod() function exists, call the file system specific mknod () function. 
+Pass the name, mode, device type and the location information associated with the 
+directory under which the node will be created. 
+
+@page
+@section mount
+
+@subheading File:
+
+mount.c
+
+
+Arguments (Not a standard POSIX call): 
+
+Rtems_filesystem_mount_table_entry_t   **mt_entry,
+
+If the mount operation is successful, this pointer to a pointer will be set to 
+reference the mount table chain entry that has been allocated for this file 
+system mount. 
+
+rtems_filesystem_operations_table   *fs_ops,
+
+This is a pointer to a table of functions that are associated with the file 
+system that we are about to mount. This is the mechanism to selected file 
+system type without keeping a dynamic database of all possible file 
+system types that are valid for the mount operation. Using this method, it 
+is only necessary to configure the file systems that we wish to use into the 
+RTEMS build. Unused file systems types will not be drawn into the build.
+
+char                      *fsoptions,
+
+This argument points to a string that selects mounting for read only access 
+or read/write access. Valid states are "RO" and "RW"
+
+char                      *device,
+
+This argument is reserved for the name of a device that will be used to 
+access the file system information. Current file system implementations 
+are memory based and do not require a device to access file system 
+information.
+
+char                      *mount_point
+
+This is a pathname to a directory in a currently mounted file system that 
+allows read, write and execute permissions.
+
+@subheading Processing: 
+
+This routine will handle the mounting of a file system on a mount point. If the 
+operation is successful, a pointer to the mount table chain entry associated with 
+the mounted file system will be returned to the calling function. The specifics 
+about the processing required at the mount point and within the file system being 
+mounted is isolated in the file system specific mount() and fsmount_me () 
+functions. This allows the generic mount() function to remain unaltered even if 
+new file system types are introduced.
+
+
+
+@subheading Development Comments:
+
+This routine will use get_file_system_options() to determine if the mount options 
+are valid ("RO" or "RW").
+
+It confirms that a file system ops-table has been selected.
+
+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 file system to be mounted.
+
+The current mount table chain is searched to determine that there is not 
+another file system mounted at the mount point we are trying to mount 
+onto.
+
+If a mount function is defined in the ops table for the file system 
+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 
+file system.
+
+If the fsmount_me() function is specified for ops-table of the file system being 
+mounted, that function is called to initialize for the new file system.
+
+On successful completion, the temporary mount table entry will be placed on the 
+mount table chain to record the presence of the mounted file system.
+
+@page
+@section open
+
+@subheading File:
+
+open.c
+
+@subheading Processing: 
+
+This routine is layered on both RTEMS calls and file system specific 
+implementations of the open() function. These functional interfaces should not 
+change for new file systems and therefore this code should be stable as new file 
+systems are introduced.
+
+@subheading Development Comments:
+
+This routine will allocate a file control block for the file or device that we are 
+about to open.
+
+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, file system specific 
+functions and mount table chain information with the pathname.
+
+If the create option has been it will attempt to create a node for a regular file along 
+the specified path. If a file already exists along this path, an error will be 
+generated; otherwise, a node will be allocated for the file under the file system 
+that contains the pathname. When a new node is created, it is also evaluated so 
+that an appropriate rtems_filesystem_location_info_t data structure can be filled 
+out for the newly created node. 
+
+If the file exists or the new file was created successfully, the file control block 
+structure will be initialized with handler table information, node information and 
+the rtems_filesystem_location_info_t data structure that describes the node and 
+file system data in detail.
+
+If an open() function exists in the file system 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.
+
+@page
+@section opendir
+
+@subheading File:
+
+opendir.c
+
+@subheading Processing: 
+
+This routine will attempt to open a directory for read access. It will setup a DIR 
+control structure that will be used to access directory information. This routine is 
+layered on the generic open() routine and file system specific directory 
+processing routines. 
+
+@subheading Development Comments:
+
+The BSD group provided this routine.
+
+@page
+@section pathconf
+
+@subheading File:
+
+pathconf.c
+
+@subheading Processing: 
+
+This routine will obtain the value of one of the path configuration parameters and 
+return it to the calling routine. It is layered on the generic open() and fpathconf () 
+functions. These interfaces should not change with the addition of new file system 
+types.
+
+@subheading Development Comments:
+
+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.
+
+The file that was accessed is then closed.
+
+@page
+@section read
+
+@subheading File:
+
+deviceio.c
+
+@subheading Processing: 
+
+This routine is layered on a set of RTEMS calls and file system specific read 
+operations. The functions are layered in such a way as to isolate them from 
+change as new file systems are introduced.
+
+@subheading Development Comments:
+
+This routine will examine the type of file descriptor it is sent.
+
+If the file descriptor is associated with a network device, the read function will be 
+mapped to a special network handler. The return code from the network handler 
+will then be sent as the return code from generic read() function.
+
+For file descriptors that are associated with the file system the following sequence 
+will be performed:
+
+@enumerate
+
+@item Obtain the file control block associated with the file descriptor
+
+@item Range check the file descriptor
+
+@item Determine that the buffer pointer is not invalid
+
+@item Check that the count is not zero
+
+@item Check the file control block to see if we have permissions to read
+
+@item If  there is a read function in the handler table, invoke the handler table 
+read() function
+
+@item Use the return code from the handler table read function(number of 
+bytes read) to increment the offset element of the file control block
+
+@item Return the number of bytes read to the calling program
+
+@end enumerate
+
+@page
+@section readdir
+
+@subheading File:
+
+readdir.c
+
+@subheading Processing: 
+
+This routine was acquired from the BSD group. It has not been altered from its 
+original form. 
+
+@subheading Development Comments:
+
+The routine calls a customized getdents() function that is provided by the user. 
+This routine provides the file system 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.
+
+@page
+@section unmount
+
+@subheading File:
+
+unmount.c
+
+@subheading Processing: 
+
+This routine will attempt to dismount a mounted file system and then free all 
+resources that were allocated for the management of that file system.
+
+@subheading Development Comments:
+
+@itemize @bullet
+
+@item This routine will determine if there are any file systems currently mounted 
+under the file system that we are trying to dismount. This would prevent the 
+dismount of the file system.
+
+@item It will test to see if the current directory is in the file system that we are 
+attempting to dismount. This would prevent the dismount of the file system.
+
+@item It will scan all the currently open file descriptors to determine is there is an 
+open file descriptor to a file in the file system that we are attempting to 
+unmount().
+
+@end itemize
+
+If the above preconditions are met then the following sequence is performed:
+
+@enumerate
+
+@item Call the file system specific unmount() function for the file system that 
+contains the mount point. This routine should indicate that the mount point 
+no longer has a file system mounted below it.
+
+@item Call the file system specific fsunmount_me() function for the mounted 
+file system that we are trying to unmount(). This routine should clean up 
+any resources that are no longer needed for the management of the file 
+system being un-mounted.
+
+@item Extract the mount table entry for the file system that was just dismounted 
+from the mount table chain.
+
+@item Free the memory associated with the extracted mount table entry.
+
+@end enumerate
+
+@page
+@section eval
+
+@subheading File:
+
+XXX
+
+@subheading Processing: 
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
+@page
+@section getdentsc
+
+@subheading File:
+
+XXX
+
+@subheading Processing: 
+
+XXX
+
+@subheading Development Comments:
+
+XXX
+
-- 
cgit v1.2.3