source: rtems-docs/filesystem/filesystem.rst @ c142f5b

4.115am
Last change on this file since c142f5b was c142f5b, checked in by Amar Takhar <verm@…>, on 01/16/16 at 14:48:19

Fix markup warnings.

  • Property mode set to 100644
File size: 108.8 KB
Line 
1:orphan:
2
3
4
5.. COMMENT: %**end of header
6
7.. COMMENT: COPYRIGHT (c) 1989-2013.
8
9.. COMMENT: On-Line Applications Research Corporation (OAR).
10
11.. COMMENT: All rights reserved.
12
13.. COMMENT: Master file for the Filesystem Design Guide
14
15.. COMMENT: COPYRIGHT (c) 1988-2002.
16
17.. COMMENT: On-Line Applications Research Corporation (OAR).
18
19.. COMMENT: All rights reserved.
20
21.. COMMENT: The following determines which set of the tables and figures we will use.
22
23.. COMMENT: We default to ASCII but if available TeX or HTML versions will
24
25.. COMMENT: be used instead.
26
27.. COMMENT: @clear use-html
28
29.. COMMENT: @clear use-tex
30
31.. COMMENT: The following variable says to use texinfo or html for the two column
32
33.. COMMENT: texinfo tables.  For somethings the format does not look good in html.
34
35.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
36
37.. COMMENT: good printed.
38
39.. COMMENT: Custom whitespace adjustments.  We could fiddle a bit more.
40
41.. COMMENT: Title Page Stuff
42
43.. COMMENT: I don't really like having a short title page.  -joel
44
45.. COMMENT: @shorttitlepage RTEMS Filesystem Design Guide
46
47=============================
48RTEMS Filesystem Design Guide
49=============================
50
51.. COMMENT: COPYRIGHT (c) 1988-2015.
52
53.. COMMENT: On-Line Applications Research Corporation (OAR).
54
55.. COMMENT: All rights reserved.
56
57.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
58
59.. COMMENT: can force the copyright description onto a left hand page.
60
61COPYRIGHT © 1988 - 2015.
62
63On-Line Applications Research Corporation (OAR).
64
65The authors have used their best efforts in preparing
66this material.  These efforts include the development, research,
67and testing of the theories and programs to determine their
68effectiveness.  No warranty of any kind, expressed or implied,
69with regard to the software or the material contained in this
70document is provided.  No liability arising out of the
71application or use of any product described in this document is
72assumed.  The authors reserve the right to revise this material
73and to make changes from time to time in the content hereof
74without obligation to notify anyone of such revision or changes.
75
76The RTEMS Project is hosted at http://www.rtems.org.  Any
77inquiries concerning RTEMS, its related support components, or its
78documentation should be directed to the Community Project hosted athttp://www.rtems.org.
79
80Any inquiries for commercial services including training, support, custom
81development, application development assistance should be directed tohttp://www.rtems.com.
82
83.. COMMENT: This prevents a black box from being printed on "overflow" lines.
84
85.. COMMENT: The alternative is to rework a sentence to avoid this problem.
86
87RTEMS Filesystem Design Guide
88#############################
89
90.. COMMENT: COPYRIGHT (c) 1989-2011.
91
92.. COMMENT: On-Line Applications Research Corporation (OAR).
93
94.. COMMENT: All rights reserved.
95
96Preface
97#######
98
99This document describes the implementation of the RTEMS filesystem
100infrastructure.  This infrastructure supports the following
101capabilities:
102
103- Mountable file systems
104
105- Hierarchical file system directory structure
106
107- POSIX compliant set of routines for the manipulation of files and directories
108
109- Individual file and directory support for the following:
110  # Permissions for read, write and execute
111  # User ID
112  # Group ID
113  # Access time
114  # Modification time
115  # Creation time
116
117- Hard links to files and directories
118
119- Symbolic links to files and directories
120
121This has been implemented to provide the framework for a UNIX-like
122file system support. POSIX file and directory functions have been
123implemented that allow a standard method of accessing file, device and
124directory information within file systems. The file system concept that
125has been implemented allows for expansion and adaptation of the file
126system to a variety of existing and future data storage devices. To this
127end, file system mount and unmount capabilities have been included in this
128RTEMS framework.
129
130This framework slightly alters the manner in which devices are handled
131under RTEMS from that of public release 4.0.0 and earlier.  Devices that
132are defined under a given RTEMS configuration will now be registered as
133files in a mounted file system.  Access to these device drivers and their
134associated devices may now be performed through the traditional file system
135open(), read(), write(), lseek(), fstat() and ioctl() functions in addition
136to the interface provided by the IO Manager in the RTEMS Classic API.
137
138An In-Memory File System (IMFS) is included which provides full POSIX
139filesystem functionality yet is RAM based.  The IMFS maintains a
140node structure for each file, device, and directory in each mounted
141instantiation of its file system. The node structure is used to
142manage ownership, access rights, access time, modification time,
143and creation time.  A union of structures within the IMFS nodal
144structure provide for manipulation of file data, device selection,
145or directory content as required by the nodal type. Manipulation of
146these properties is accomplished through the POSIX set of file and
147directory functions.  In addition to being useful in its own right,
148the IMFS serves as a full featured example filesystem.
149
150The intended audience for this document is those persons implementing
151their own filesystem.  Users of the filesystem may find information
152on the implementation useful.  But the user interface to the filesystem
153is through the ISO/ANSI C Library and POSIX 1003.1b file and directory
154APIs.
155
156.. COMMENT: COPYRIGHT (c) 1988-2002.
157
158.. COMMENT: On-Line Applications Research Corporation (OAR).
159
160.. COMMENT: All rights reserved.
161
162Pathname Evaluation
163###################
164
165This chapter describes the pathname evaluation process for the
166RTEMS Filesystem Infrastructure.
167.. code:: c
168
169    XXX Include graphic of the path evaluation process
170
171Pathname Evaluation Handlers
172============================
173
174There are two pathname evaluation routines.  The handler patheval()
175is called to find, verify privlages on and return information on a node
176that exists.  The handler evalformake() is called to find, verify
177permissions, and return information on a node that is to become a parent.
178Additionally, evalformake() returns a pointer to the start of the name of
179the new node to be created.
180
181Pathname evaluation is specific to a filesystem.
182Each filesystem is required to provide both a patheval() and an evalformake()
183routine.  Both of these routines gets a name to evaluate and a node indicating
184where to start the evaluation.
185
186Crossing a Mount Point During Path Evaluation
187=============================================
188
189If the filesystem supports the mount command, the evaluate routines
190must handle crossing the mountpoint.  The evaluate routine should evaluate
191the name upto the first directory node where the new filesystem is mounted.
192The filesystem may process terminator characters prior to calling the
193evaluate routine for the new filesystem.   A pointer to the portion of the
194name which has not been evaluated along with the root node of the new
195file system ( gotten from the mount table entry ) is passed to the correct
196mounted filesystem evaluate routine.
197
198The rtems_filesystem_location_info_t Structure
199==============================================
200
201The ``rtems_filesystem_location_info_t`` structure contains all information
202necessary for identification of a node.
203
204The generic rtems filesystem code defines two global
205rtems_filesystem_location_info_t structures, the``rtems_filesystem_root`` and the ``rtems_filesystem_current``.
206Both are initially defined to be the root node of the base filesystem.
207Once the chdir command is correctly used the ``rtems_filesystem_current``
208is set to the location specified by the command.
209
210The filesystem generic code peeks at the first character in the name to be
211evaluated.  If this character is a valid seperator, the``rtems_filesystem_root`` is used as the node to start the evaluation
212with.  Otherwise, the ``rtems_filesystem_current`` node is used as the
213node to start evaluating with.  Therefore, a valid
214rtems_filesystem_location_info_t is given to the evaluate routine to start
215evaluation with.  The evaluate routines are then responsible for making
216any changes necessary to this structure to correspond to the name being
217parsed.
218.. code:: c
219
220    struct rtems_filesystem_location_info_tt {
221    void                                     \*node_access;
222    rtems_filesystem_file_handlers_r         \*handlers;
223    rtems_filesystem_operations_table        \*ops;
224    rtems_filesystem_mount_table_entry_t     \*mt_entry;
225    };
226
227*node_access*
228    This element is filesystem specific.  A filesystem can define and store
229    any information necessary to identify a node at this location.  This element
230    is normally filled in by the filesystem’s evaluate routine. For the
231    filesystem’s root node, the filesystem’s initilization routine should
232    fill this in, and it should remain valid until the instance of the
233    filesystem is unmounted.
234
235*handlers*
236    This element is defined as a set of routines that may change within a
237    given filesystem based upon node type.  For example a directory and a
238    memory file may have to completely different read routines.  This element
239    is set to an initialization state defined by the mount table, and may
240    be set to the desired state by the evaluation routines.
241
242*ops*
243    This element is defined as a set of routines that remain static for the
244    filesystem.  This element identifies entry points into the filesystem
245    to the generic code.
246
247*mt_entry*
248    This element identifies the mount table entry for this instance of the
249    filesystem.
250
251.. COMMENT: COPYRIGHT (c) 1988-2002.
252
253.. COMMENT: On-Line Applications Research Corporation (OAR).
254
255.. COMMENT: All rights reserved.
256
257System Initialization
258#####################
259
260After the RTEMS initialization is performed, the application’s
261initialization will be performed. Part of initialization is a call to
262rtems_filesystem_initialize(). This routine will mount the ‘In Memory File
263System’ as the base filesystem.  Mounting the base filesystem consists
264of the following:
265
266- Initialization of mount table chain control structure
267
268- Allocation of a ``jnode`` structure that will server as the root node
269  of the ‘In Memory Filesystem’
270
271- Initialization of the allocated ``jnode`` with the appropriate OPS,
272  directory handlers and pathconf limits and options.
273
274- Allocation of a memory region for filesystem specific global
275  management variables
276
277- Creation of first mount table entry for the base filesystem
278
279- Initialization of the first mount table chain entry to indicate that
280  the mount point is NULL and the mounted filesystem is the base file
281  system
282
283After the base filesystem has been mounted, the following operations are
284performed under its directory structure:
285
286- Creation of the /dev directory
287
288- Registration of devices under /dev directory
289
290Base Filesystem
291===============
292
293RTEMS initially mounts a RAM based file system known as the base file system.
294The root directory of this file system tree serves as the logical root of the
295directory hierarchy (Figure 3). Under the root directory a ‘/dev’ directory
296is created under which all I/O device directories and files are registered as
297part of the file system hierarchy.
298.. code:: c
299
300    Figure of the tree structure goes here.
301
302A RAM based file system draws its management resources from memory. File and
303directory nodes are simply allocated blocks of memory. Data associated with
304regular files is stored in collections of memory blocks. When the system is
305turned off or restarted all memory-based components of the file system are
306lost.
307
308The base file system serves as a starting point for the mounting of file
309systems that are resident on semi-permanent storage media. Examples of such
310media include non- volatile memory, flash memory and IDE hard disk drives
311(Figure 3). File systems of other types will be mounted onto mount points
312within the base file system or other file systems that are subordinate to the
313base file system. The framework set up under the base file system will allow
314for these new file system types and the unique data and functionality that is
315required to manage the future file systems.
316
317Base Filesystem Mounting
318------------------------
319
320At present, the first file system to be mounted is the ‘In Memory File
321System’. It is mounted using a standard MOUNT() command in which the mount
322point is NULL.  This flags the mount as the first file system to be
323registered under the operating system and appropriate initialization of file
324system management information is performed (See figures 4 and 5). If a
325different file system type is desired as the base file system, alterations
326must be made to base_fs.c. This routine handles the mount of the base file
327system.
328
329.. code:: c
330
331    Figure of the mount table chain goes here.
332
333Once the root of the base file system has been established and it has been
334recorded as the mount point of the base file system, devices are integrated
335into the base file system. For every device that is configured into the
336system (See ioman.c) a device registration process is performed. Device
337registration produces a unique dev_t handle that consists of a major and
338minor device number. In addition, the configuration information for each
339device contains a text string that represents the fully qualified pathname to
340that device’s place in the base file system’s hierarchy. A file system node
341is created for the device along the specified registration path.
342
343.. code:: c
344
345    Figure  of the Mount Table Processing goes here.
346
347Note: Other file systems can be mounted but they are mounted onto points
348(directory mount points) in the base file system.
349
350.. COMMENT: COPYRIGHT (c) 1988-2002.
351
352.. COMMENT: On-Line Applications Research Corporation (OAR).
353
354.. COMMENT: All rights reserved.
355
356Mounting and Unmounting Filesystems
357###################################
358
359Mount Points
360============
361
362The following is the list of the characteristics of a mount point:
363
364- The mount point must be a directory. It may have files and other
365  directories under it. These files and directories will be hidden when the
366  filesystem is mounted.
367
368- The task must have read/write/execute permissions to the mount point
369  or the mount attempt will be rejected.
370
371- Only one filesystem can be mounted to a single mount point.
372
373- The Root of the mountable filesystem will be referenced by the name
374  of the mount point after the mount is complete.
375
376Mount Table Chain
377=================
378
379The mount table chain is a dynamic list of structures that describe
380mounted filesystems a specific points in the filesystem hierarchy. It is
381initialized to an empty state during the base filesystem initialization.
382The mount operation will add entries to the mount table chain. The
383un-mount operation will remove entries from the mount table chain.
384
385Each entry in the mount table chain is of the following type:
386.. code:: c
387
388    struct rtems_filesystem_mount_table_entry_tt
389    {
390    Chain_Node                             Node;
391    rtems_filesystem_location_info_t       mt_point_node;
392    rtems_filesystem_location_info_t       mt_fs_root;
393    int                                    options;
394    void                                  \*fs_info;
395    rtems_filesystem_limits_and_options_t  pathconf_limits_and_options;
396    /*
397    *  When someone adds a mounted filesystem on a real device,
398    *  this will need to be used.
399    *
400    *  The best option long term for this is probably an
401    *  open file descriptor.
402    \*/
403    char                                  \*dev;
404    };
405
406*Node*
407    The Node is used to produce a linked list of mount table entry nodes.
408
409*mt_point_node*
410    The mt_point_node contains all information necessary to access the
411    directory where a filesystem is mounted onto.  This element may contain
412    memory that is allocated during a path evaluation of the filesystem
413    containing the mountpoint directory.  The generic code allows this
414    memory to be returned by unmount when the filesystem identified by
415    mt_fs_root is unmounted.
416
417*mt_fs_root*
418    The mt_fs_root contains all information necessary to identify the root
419    of the mounted filesystem. The user is never allowed access to this
420    node by the generic code, but it is used to identify to the mounted
421    filesystem where to start evaluation of pathnames at.
422
423*options*
424    XXX
425
426*fs_info*
427    The fs_info element is a location available for use by the mounted file
428    system to identify unique things applicable to this instance of the file
429    system.  For example the IMFS uses this space to provide node
430    identification that is unique for each instance (mounting) of the filesystem.
431
432*pathconf_limits_and_options*
433    XXX
434
435*dev*
436    This character string represents the device where the filesystem will reside.
437
438Adding entries to the chain during mount
439========================================
440
441When a filesystem is mounted, its presence and location in the file
442system hierarchy is recorded in a dynamic list structure known as a chain.
443A unique rtems_filesystem_mount_table_entry_tt structure is logged for
444each filesystem that is mounted. This includes the base filesystem.
445
446Removing entries from the chain during unmount
447==============================================
448
449When a filesystem is dismounted its entry in the mount table chain is
450extracted and the memory for this entry is freed.
451
452.. COMMENT: COPYRIGHT (c) 1988-2002.
453
454.. COMMENT: On-Line Applications Research Corporation (OAR).
455
456.. COMMENT: All rights reserved.
457
458System Call Development Notes
459#############################
460
461This set of routines represents the application’s interface to files and directories
462under the RTEMS filesystem. All routines are compliant with POSIX standards if a
463specific interface has been established. The list below represents the routines that have
464been included as part of the application’s interface.
465
466# access()
467
468# chdir()
469
470# chmod()
471
472# chown()
473
474# close()
475
476# closedir()
477
478# dup()
479
480# dup2()
481
482# fchmod()
483
484# fcntl()
485
486# fdatasync()
487
488# fpathconf()
489
490# fstat()
491
492# ioctl()
493
494# link()
495
496# lseek()
497
498# mkdir()
499
500# mkfifo()
501
502# mknod()
503
504# mount()
505
506# open()
507
508# opendir()
509
510# pathconf()
511
512# read()
513
514# readdir()
515
516# unmount()
517
518The sections that follow provide developmental information concerning each
519of these functions.
520
521.. COMMENT: @page
522
523access
524======
525
526**File:**
527
528access.c
529
530**Processing:**
531
532This routine is layered on the stat() function. It acquires the current
533status information for the specified file and then determines if the
534caller has the ability to access the file for read, write or execute
535according to the mode argument to this function.
536
537**Development Comments:**
538
539This routine is layered on top of the stat() function. As long as the
540st_mode element in the returned structure follow the standard UNIX
541conventions, this function should support other filesystems without
542alteration.
543
544.. COMMENT: @page
545
546chdir
547=====
548
549**File:**
550
551chdir.c
552
553**Processing:**
554
555This routine will determine if the pathname that we are attempting to make
556that current directory exists and is in fact a directory. If these
557conditions are met the global indication of the current directory
558(rtems_filesystem_current) is set to the rtems_filesystem_location_info_t
559structure that is returned by the rtems_filesystem_evaluate_path()
560routine.
561
562**Development Comments:**
563
564This routine is layered on the rtems_filesystem_evaluate_path() routine
565and the filesystem specific OP table function node_type().
566
567The routine node_type() must be a routine provided for each filesystem
568since it must access the filesystems node information to determine which
569of the following types the node is:
570
571- RTEMS_FILESYSTEM_DIRECTORY
572
573- RTEMS_FILESYSTEM_DEVICE
574
575- RTEMS_FILESYSTEM_HARD_LINK
576
577- RTEMS_FILESYSTEM_MEMORY_FILE
578
579This acknowledges that the form of the node management information can
580vary from one filesystem implementation to another.
581
582RTEMS has a special global structure that maintains the current directory
583location. This global variable is of type rtems_filesystem_location_info_t
584and is called rtems_filesystem_current. This structure is not always
585valid. In order to determine if the structure is valid, you must first
586test the node_access element of this structure. If the pointer is NULL,
587then the structure does not contain a valid indication of what the current
588directory is.
589
590.. COMMENT: @page
591
592chmod
593=====
594
595**File:**
596
597chmod.c
598
599**Processing:**
600
601This routine is layered on the open(), fchmod() and close() functions. As
602long as the standard interpretation of the mode_t value is maintained,
603this routine should not need modification to support other filesystems.
604
605**Development Comments:**
606
607The routine first determines if the selected file can be open with
608read/write access.  This is required to allow modification of the mode
609associated with the selected path.
610
611The fchmod() function is used to actually change the mode of the path
612using the integer file descriptor returned by the open() function.
613
614After mode modification, the open file descriptor is closed.
615
616.. COMMENT: @page
617
618chown
619=====
620
621**File:**
622
623chown.c
624
625**Processing:**
626
627This routine is layered on the rtems_filesystem_evaluate_path() and the
628file system specific chown() routine that is specified in the OPS table
629for the file system.
630
631**Development Comments:**
632
633rtems_filesystem_evaluate_path() is used to determine if the path
634specified actually exists. If it does a rtems_filesystem_location_info_t
635structure will be obtained that allows the shell function to locate the
636OPS table that is to be used for this filesystem.
637
638It is possible that the chown() function that should be in the OPS table
639is not defined. A test for a non-NULL OPS table chown() entry is performed
640before the function is called.
641
642If the chown() function is defined in the indicated OPS table, the
643function is called with the rtems_filesystem_location_info_t structure
644returned from the path evaluation routine, the desired owner, and group
645information.
646
647.. COMMENT: @page
648
649close
650=====
651
652**File:**
653
654close.c
655
656**Processing:**
657
658This routine will allow for the closing of both network connections and
659file system devices. If the file descriptor is associated with a network
660device, the appropriate network function handler will be selected from a
661table of previously registered network functions (rtems_libio_handlers)
662and that function will be invoked.
663
664If the file descriptor refers to an entry in the filesystem, the
665appropriate handler will be selected using information that has been
666placed in the file control block for the device (rtems_libio_t structure).
667
668**Development Comments:**
669
670rtems_file_descriptor_type examines some of the upper bits of the file
671descriptor index. If it finds that the upper bits are set in the file
672descriptor index, the device referenced is a network device.
673
674Network device handlers are obtained from a special registration table
675(rtems_libio_handlers) that is set up during network initialization. The
676network handler invoked and the status of the network handler will be
677returned to the calling process.
678
679If none of the upper bits are set in the file descriptor index, the file
680descriptor refers to an element of the RTEMS filesystem.
681
682The following sequence will be performed for any filesystem file
683descriptor:
684
685# Use the rtems_libio_iop() function to obtain the rtems_libio_t
686  structure for the file descriptor
687
688# Range check the file descriptor using rtems_libio_check_fd()
689
690# Determine if there is actually a function in the selected handler
691  table that processes the close() operation for the filesystem and node
692  type selected.  This is generally done to avoid execution attempts on
693  functions that have not been implemented.
694
695# If the function has been defined it is invoked with the file control
696  block pointer as its argument.
697
698# The file control block that was associated with the open file
699  descriptor is marked as free using rtems_libio_free().
700
701# The return code from the close handler is then passed back to the
702  calling program.
703
704.. COMMENT: @page
705
706closedir
707========
708
709**File:**
710
711closedir.c
712
713**Processing:**
714
715The code was obtained from the BSD group. This routine must clean up the
716memory resources that are required to track an open directory. The code is
717layered on the close() function and standard memory free() functions. It
718should not require alterations to support other filesystems.
719
720**Development Comments:**
721
722The routine alters the file descriptor and the index into the DIR
723structure to make it an invalid file descriptor. Apparently the memory
724that is about to be freed may still be referenced before it is
725reallocated.
726
727The dd_buf structure’s memory is reallocated before the control structure
728that contains the pointer to the dd_buf region.
729
730DIR control memory is reallocated.
731
732The close() function is used to free the file descriptor index.
733
734.. COMMENT: @page
735
736dup()      Unimplemented
737========================
738
739**File:**
740
741dup.c
742
743**Processing:**
744
745**Development Comments:**
746
747.. COMMENT: @page
748
749dup2()      Unimplemented
750=========================
751
752**File:**
753
754dup2.c
755
756**Processing:**
757
758**Development Comments:**
759
760.. COMMENT: @page
761
762fchmod
763======
764
765**File:**
766
767fchmod.c
768
769**Processing:**
770
771This routine will alter the permissions of a node in a filesystem. It is
772layered on the following functions and macros:
773
774- rtems_file_descriptor_type()
775
776- rtems_libio_iop()
777
778- rtems_libio_check_fd()
779
780- rtems_libio_check_permissions()
781
782- fchmod() function that is referenced by the handler table in the
783  file control block associated with this file descriptor
784
785**Development Comments:**
786
787The routine will test to see if the file descriptor index is associated
788with a network connection. If it is, an error is returned from this
789routine.
790
791The file descriptor index is used to obtain the associated file control
792block.
793
794The file descriptor value is range checked.
795
796The file control block is examined to determine if it has write
797permissions to allow us to alter the mode of the file.
798
799A test is made to determine if the handler table that is referenced in the
800file control block contains an entry for the fchmod() handler function. If
801it does not, an error is returned to the calling routine.
802
803If the fchmod() handler function exists, it is called with the file
804control block and the desired mode as parameters.
805
806.. COMMENT: @page
807
808fcntl()
809=======
810
811**File:**
812
813fcntl.c
814
815**Processing:**
816
817This routine currently only interacts with the file control block. If the
818structure of the file control block and the associated meanings do not
819change, the partial implementation of fcntl() should remain unaltered for
820other filesystem implementations.
821
822**Development Comments:**
823
824The only commands that have been implemented are the F_GETFD and F_SETFD.
825The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the``flags`` element of the file control block associated with the file
826descriptor index.
827
828The current implementation of the function performs the sequence of
829operations below:
830
831# Test to see if we are trying to operate on a file descriptor
832  associated with a network connection
833
834# Obtain the file control block that is associated with the file
835  descriptor index
836
837# Perform a range check on the file descriptor index.
838
839.. COMMENT: @page
840
841fdatasync
842=========
843
844**File:**
845
846fdatasync.c
847
848**Processing:**
849
850This routine is a template in the in memory filesystem that will route us to the
851appropriate handler function to carry out the fdatasync() processing. In the in
852memory filesystem this function is not necessary. Its function in a disk based file
853system that employs a memory cache is to flush all memory based data buffers to
854disk. It is layered on the following functions and macros:
855
856- rtems_file_descriptor_type()
857
858- rtems_libio_iop()
859
860- rtems_libio_check_fd()
861
862- rtems_libio_check_permissions()
863
864- fdatasync() function that is referenced by the handler table in the
865  file control block associated with this file descriptor
866
867**Development Comments:**
868
869The routine will test to see if the file descriptor index is associated
870with a network connection. If it is, an error is returned from this
871routine.
872
873The file descriptor index is used to obtain the associated file control
874block.
875
876The file descriptor value is range checked.
877
878The file control block is examined to determine if it has write
879permissions to the file.
880
881A test is made to determine if the handler table that is referenced in the
882file control block contains an entry for the fdatasync() handler function.
883If it does not an error is returned to the calling routine.
884
885If the fdatasync() handler function exists, it is called with the file
886control block as its parameter.
887
888.. COMMENT: @page
889
890fpathconf
891=========
892
893**File:**
894
895fpathconf.c
896
897**Processing:**
898
899This routine is layered on the following functions and macros:
900
901- rtems_file_descriptor_type()
902
903- rtems_libio_iop()
904
905- rtems_libio_check_fd()
906
907- rtems_libio_check_permissions()
908
909When a filesystem is mounted, a set of constants is specified for the
910filesystem.  These constants are stored with the mount table entry for the
911filesystem. These constants appear in the POSIX standard and are listed
912below.
913
914- PCLINKMAX
915
916- PCMAXCANON
917
918- PCMAXINPUT
919
920- PCNAMEMAX
921
922- PCPATHMAX
923
924- PCPIPEBUF
925
926- PCCHOWNRESTRICTED
927
928- PCNOTRUNC
929
930- PCVDISABLE
931
932- PCASYNCIO
933
934- PCPRIOIO
935
936- PCSYNCIO
937
938This routine will find the mount table information associated the file
939control block for the specified file descriptor parameter. The mount table
940entry structure contains a set of filesystem specific constants that can
941be accessed by individual identifiers.
942
943**Development Comments:**
944
945The routine will test to see if the file descriptor index is associated
946with a network connection. If it is, an error is returned from this
947routine.
948
949The file descriptor index is used to obtain the associated file control
950block.
951
952The file descriptor value is range checked.
953
954The file control block is examined to determine if it has read permissions
955to the file.
956
957Pathinfo in the file control block is used to locate the mount table entry
958for the filesystem associated with the file descriptor.
959
960The mount table entry contains the pathconf_limits_and_options element.
961This element is a table of constants that is associated with the
962filesystem.
963
964The name argument is used to reference the desired constant from the
965pathconf_limits_and_options table.
966
967.. COMMENT: @page
968
969fstat
970=====
971
972**File:**
973
974fstat.c
975
976**Processing:**
977
978This routine will return information concerning a file or network
979connection. If the file descriptor is associated with a network
980connection, the current implementation of ``fstat()`` will return a
981mode set to ``S_IFSOCK``. In a later version, this routine will map the
982status of a network connection to an external handler routine.
983
984If the file descriptor is associated with a node under a filesystem, the
985fstat()  routine will map to the fstat() function taken from the node
986handler table.
987
988**Development Comments:**
989
990This routine validates that the struct stat pointer is not NULL so that
991the return location is valid.
992
993The struct stat is then initialized to all zeros.
994
995rtems_file_descriptor_type() is then used to determine if the file
996descriptor is associated with a network connection. If it is, network
997status processing is performed. In the current implementation, the file
998descriptor type processing needs to be improved. It currently just drops
999into the normal processing for file system nodes.
1000
1001If the file descriptor is associated with a node under a filesystem, the
1002following steps are performed:
1003
1004# Obtain the file control block that is associated with the file descriptor
1005  index.
1006
1007# Range check the file descriptor index.
1008
1009# Test to see if there is a non-NULL function pointer in the handler
1010  table for the fstat() function. If there is, invoke the function with the
1011  file control block and the pointer to the stat structure.
1012
1013.. COMMENT: @page
1014
1015ioctl
1016=====
1017
1018**File:**
1019
1020ioctl.c
1021
1022**Processing:**
1023
1024Not defined in the POSIX 1003.1b standard but commonly supported in most
1025UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine
1026is layered on external network handlers and filesystem specific handlers.
1027The development of new filesystems should not alter the basic processing
1028performed by this routine.
1029
1030**Development Comments:**
1031
1032The file descriptor is examined to determine if it is associated with a
1033network device. If it is processing is mapped to an external network
1034handler. The value returned by this handler is then returned to the
1035calling program.
1036
1037File descriptors that are associated with a filesystem undergo the
1038following processing:
1039
1040# The file descriptor index is used to obtain the associated file
1041  control block.
1042
1043# The file descriptor value is range checked.
1044
1045# A test is made to determine if the handler table that is referenced
1046  in the file control block contains an entry for the ioctl() handler
1047  function. If it does not, an error is returned to the calling routine.
1048
1049# If the ioctl() handler function exists, it is called with the file
1050  control block, the command and buffer as its parameters.
1051
1052# The return code from this function is then sent to the calling
1053  routine.
1054
1055.. COMMENT: @page
1056
1057link
1058====
1059
1060**File:**
1061
1062link.c
1063
1064**Processing:**
1065
1066This routine will establish a hard link to a file, directory or a device.
1067The target of the hard link must be in the same filesystem as the new link
1068being created. A link to an existing link is also permitted but the
1069existing link is evaluated before the new link is made. This implies that
1070links to links are reduced to links to files, directories or devices
1071before they are made.
1072
1073**Development Comments:**
1074
1075Calling parameters:
1076const char   \*existing
1077const char   \*new
1078
1079link() will determine if the target of the link actually exists using
1080rtems_filesystem_evaluate_path()
1081
1082rtems_filesystem_get_start_loc() is used to determine where to start the
1083path evaluation of the new name. This macro examines the first characters
1084of the name to see if the name of the new link starts with a
1085rtems_filesystem_is_separator. If it does the search starts from the root
1086of the RTEMS filesystem; otherwise the search will start from the current
1087directory.
1088
1089The OPS table evalformake() function for the parent’s filesystem is used
1090to locate the node that will be the parent of the new link. It will also
1091locate the start of the new path’s name. This name will be used to define
1092a child under the parent directory.
1093
1094If the parent is found, the routine will determine if the hard link that
1095we are trying to create will cross a filesystem boundary. This is not
1096permitted for hard-links.
1097
1098If the hard-link does not cross a filesystem boundary, a check is
1099performed to determine if the OPS table contains an entry for the link()
1100function.
1101
1102If a link() function is defined, the OPS table link() function will be
1103called to establish the actual link within the filesystem.
1104
1105The return code from the OPS table link() function is returned to the
1106calling program.
1107
1108.. COMMENT: @page
1109
1110lseek
1111=====
1112
1113**File:**
1114
1115lseek.c
1116
1117**Processing:**
1118
1119This routine is layered on both external handlers and filesystem / node
1120type specific handlers. This routine should allow for the support of new
1121filesystems without modification.
1122
1123**Development Comments:**
1124
1125This routine will determine if the file descriptor is associated with a
1126network device. If it is lseek will map to an external network handler.
1127The handler will be called with the file descriptor, offset and whence as
1128its calling parameters. The return code from the external handler will be
1129returned to the calling routine.
1130
1131If the file descriptor is not associated with a network connection, it is
1132associated with a node in a filesystem. The following steps will be
1133performed for filesystem nodes:
1134
1135# The file descriptor is used to obtain the file control block for the
1136  node.
1137
1138# The file descriptor is range checked.
1139
1140# The offset element of the file control block is altered as indicated
1141  by the offset and whence calling parameters
1142
1143# The handler table in the file control block is examined to determine
1144  if it contains an entry for the lseek() function. If it does not an error
1145  is returned to the calling program.
1146
1147# The lseek() function from the designated handler table is called
1148  with the file control block, offset and whence as calling arguments
1149
1150# The return code from the lseek() handler function is returned to the
1151  calling program
1152
1153.. COMMENT: @page
1154
1155mkdir
1156=====
1157
1158**File:**
1159
1160mkdir.c
1161
1162**Processing:**
1163
1164This routine attempts to create a directory node under the filesystem. The
1165routine is layered the mknod() function.
1166
1167**Development Comments:**
1168
1169See mknod() for developmental comments.
1170
1171.. COMMENT: @page
1172
1173mkfifo
1174======
1175
1176**File:**
1177
1178mkfifo.c
1179
1180**Processing:**
1181
1182This routine attempts to create a FIFO node under the filesystem. The
1183routine is layered the mknod() function.
1184
1185**Development Comments:**
1186
1187See mknod() for developmental comments
1188
1189.. COMMENT: @page
1190
1191mknod
1192=====
1193
1194**File:**
1195
1196mknod.c
1197
1198**Processing:**
1199
1200This function will allow for the creation of the following types of nodes
1201under the filesystem:
1202
1203- directories
1204
1205- regular files
1206
1207- character devices
1208
1209- block devices
1210
1211- fifos
1212
1213At the present time, an attempt to create a FIFO will result in an ENOTSUP
1214error to the calling function. This routine is layered the filesystem
1215specific routines evalformake and mknod. The introduction of a new
1216filesystem must include its own evalformake and mknod function to support
1217the generic mknod() function.  Under this condition the generic mknod()
1218function should accommodate other filesystem types without alteration.
1219
1220**Development Comments:**
1221
1222Test for nodal types - I thought that this test should look like the
1223following code:
1224.. code:: c
1225
1226    if ( (mode & S_IFDIR) = = S_IFDIR) \||
1227    (mode & S_IFREG) = = S_IFREG) \||
1228    (mode & S_IFCHR) = = S_IFCHR) \||
1229    (mode & S_IFBLK) = = S_IFBLK) \||
1230    (mode & S_IFIFO) = = S_IFIFO))
1231    Set_errno_and_return_minus_one (EINVAL);
1232
1233Where:
1234
1235- S_IFREG (0100000) - Creation of a regular file
1236
1237- S_IFCHR (0020000) - Creation of a character device
1238
1239- S_IFBLK (0060000) - Creation of a block device
1240
1241- S_IFIFO (0010000) - Creation of a FIFO
1242
1243Determine if the pathname that we are trying to create starts at the root
1244directory or is relative to the current directory using the
1245rtems_filesystem_get_start_loc()  function.
1246
1247Determine if the pathname leads to a valid directory that can be accessed
1248for the creation of a node.
1249
1250If the pathname is a valid location to create a node, verify that a
1251filesystem specific mknod() function exists.
1252
1253If the mknod() function exists, call the filesystem specific mknod()
1254function.  Pass the name, mode, device type and the location information
1255associated with the directory under which the node will be created.
1256
1257.. COMMENT: @page
1258
1259mount
1260=====
1261
1262**File:**
1263
1264mount.c
1265
1266Arguments (Not a standard POSIX call):
1267
1268rtems_filesystem_mount_table_entry_t   \**mt_entry,
1269
1270If the mount operation is successful, this pointer to a pointer will be
1271set to reference the mount table chain entry that has been allocated for
1272this file system mount.
1273
1274rtems_filesystem_operations_table   \*fs_ops,
1275
1276This is a pointer to a table of functions that are associated with the
1277file system that we are about to mount. This is the mechanism to selected
1278file system type without keeping a dynamic database of all possible file
1279system types that are valid for the mount operation. Using this method, it
1280is only necessary to configure the filesystems that we wish to use into
1281the RTEMS build. Unused filesystems types will not be drawn into the
1282build.
1283
1284char                      \*fsoptions,
1285
1286This argument points to a string that selects mounting for read only
1287access or read/write access. Valid states are "RO" and "RW"
1288
1289char                      \*device,
1290
1291This argument is reserved for the name of a device that will be used to
1292access the filesystem information. Current filesystem implementations are
1293memory based and do not require a device to access filesystem information.
1294
1295char                      \*mount_point
1296
1297This is a pathname to a directory in a currently mounted filesystem that
1298allows read, write and execute permissions.  If successful, the node found
1299by evaluating this name, is stored in the mt_entry.
1300
1301**Processing:**
1302
1303This routine will handle the mounting of a filesystem on a mount point. If
1304the operation is successful, a pointer to the mount table chain entry
1305associated with the mounted filesystem will be returned to the calling
1306function. The specifics about the processing required at the mount point
1307and within the filesystem being mounted is isolated in the filesystem
1308specific mount() and fsmount_me()  functions. This allows the generic
1309mount() function to remain unaltered even if new filesystem types are
1310introduced.
1311
1312**Development Comments:**
1313
1314This routine will use get_file_system_options() to determine if the mount
1315options are valid ("RO" or "RW").
1316
1317It confirms that a filesystem ops-table has been selected.
1318
1319Space is allocated for a mount table entry and selective elements of the
1320temporary mount table entry are initialized.
1321
1322If a mount point is specified: The mount point is examined to determine
1323that it is a directory and also has the appropriate permissions to allow a
1324filesystem to be mounted.
1325
1326The current mount table chain is searched to determine that there is not
1327another filesystem mounted at the mount point we are trying to mount onto.
1328
1329If a mount function is defined in the ops table for the filesystem
1330containing the mount point, it is called at this time.
1331
1332If no mount point is specified: Processing if performed to set up the
1333mount table chain entry as the base filesystem.
1334
1335If the fsmount_me() function is specified for ops-table of the filesystem
1336being mounted, that function is called to initialize for the new
1337filesystem.
1338
1339On successful completion, the temporary mount table entry will be placed
1340on the mount table chain to record the presence of the mounted filesystem.
1341
1342.. COMMENT: @page
1343
1344open
1345====
1346
1347**File:**
1348
1349open.c
1350
1351**Processing:**
1352
1353This routine is layered on both RTEMS calls and filesystem specific
1354implementations of the open() function. These functional interfaces should
1355not change for new filesystems and therefore this code should be stable as
1356new file systems are introduced.
1357
1358**Development Comments:**
1359
1360This routine will allocate a file control block for the file or device
1361that we are about to open.
1362
1363It will then test to see if the pathname exists. If it does a
1364rtems_filesystem_location_info_t data structure will be filled out. This
1365structure contains information that associates node information,
1366filesystem specific functions and mount table chain information with the
1367pathname.
1368
1369If the create option has been it will attempt to create a node for a
1370regular file along the specified path. If a file already exists along this
1371path, an error will be generated; otherwise, a node will be allocated for
1372the file under the filesystem that contains the pathname. When a new node
1373is created, it is also evaluated so that an appropriate
1374rtems_filesystem_location_info_t data structure can be filled out for the
1375newly created node.
1376
1377If the file exists or the new file was created successfully, the file
1378control block structure will be initialized with handler table
1379information, node information and the rtems_filesystem_location_info_t
1380data structure that describes the node and filesystem data in detail.
1381
1382If an open() function exists in the filesystem specific handlers table for
1383the node that we are trying to open, it will be called at this time.
1384
1385If any error is detected in the process, cleanup is performed. It consists
1386of freeing the file control block structure that was allocated at the
1387beginning of the generic open() routine.
1388
1389On a successful open(), the index into the file descriptor table will be
1390calculated and returned to the calling routine.
1391
1392.. COMMENT: @page
1393
1394opendir
1395=======
1396
1397**File:**
1398
1399opendir.c
1400
1401**Processing:**
1402
1403This routine will attempt to open a directory for read access. It will
1404setup a DIR control structure that will be used to access directory
1405information. This routine is layered on the generic open() routine and
1406filesystem specific directory processing routines.
1407
1408**Development Comments:**
1409
1410The BSD group provided this routine.
1411
1412.. COMMENT: @page
1413
1414pathconf
1415========
1416
1417**File:**
1418
1419pathconf.c
1420
1421**Processing:**
1422
1423This routine will obtain the value of one of the path configuration
1424parameters and return it to the calling routine. It is layered on the
1425generic open() and fpathconf()  functions. These interfaces should not
1426change with the addition of new filesystem types.
1427
1428**Development Comments:**
1429
1430This routine will try to open the file indicated by path.
1431
1432If successful, the file descriptor will be used to access the pathconf
1433value specified by ``name`` using the fpathconf() function.
1434
1435The file that was accessed is then closed.
1436
1437.. COMMENT: @page
1438
1439read
1440====
1441
1442**File:**
1443
1444deviceio.c
1445
1446**Processing:**
1447
1448This routine is layered on a set of RTEMS calls and filesystem specific
1449read operations. The functions are layered in such a way as to isolate
1450them from change as new filesystems are introduced.
1451
1452**Development Comments:**
1453
1454This routine will examine the type of file descriptor it is sent.
1455
1456If the file descriptor is associated with a network device, the read
1457function will be mapped to a special network handler. The return code from
1458the network handler will then be sent as the return code from generic
1459read() function.
1460
1461For file descriptors that are associated with the filesystem the following
1462sequence will be performed:
1463
1464# Obtain the file control block associated with the file descriptor
1465
1466# Range check the file descriptor
1467
1468# Determine that the buffer pointer is not invalid
1469
1470# Check that the count is not zero
1471
1472# Check the file control block to see if we have permissions to read
1473
1474# If there is a read function in the handler table, invoke the handler
1475  table read() function
1476
1477# Use the return code from the handler table read function(number of
1478  bytes read) to increment the offset element of the file control block
1479
1480# Return the number of bytes read to the calling program
1481
1482.. COMMENT: @page
1483
1484readdir
1485=======
1486
1487**File:**
1488
1489readdir.c
1490
1491**Processing:**
1492
1493This routine was acquired from the BSD group. It has not been altered from
1494its original form.
1495
1496**Development Comments:**
1497
1498The routine calls a customized getdents() function that is provided by the
1499user.  This routine provides the filesystem specific aspects of reading a
1500directory.
1501
1502It is layered on the read() function in the directory handler table. This
1503function has been mapped to the Imfs_dir_read() function.
1504
1505.. COMMENT: @page
1506
1507unmount
1508=======
1509
1510**File:**
1511
1512unmount.c
1513
1514**Processing:**
1515
1516This routine will attempt to dismount a mounted filesystem and then free
1517all resources that were allocated for the management of that filesystem.
1518
1519**Development Comments:**
1520
1521- This routine will determine if there are any filesystems currently
1522  mounted under the filesystem that we are trying to dismount. This would
1523  prevent the dismount of the filesystem.
1524
1525- It will test to see if the current directory is in the filesystem
1526  that we are attempting to dismount. This would prevent the dismount of the
1527  filesystem.
1528
1529- It will scan all the currently open file descriptors to determine is
1530  there is an open file descriptor to a file in the filesystem that we are
1531  attempting to unmount().
1532
1533If the above preconditions are met then the following sequence is
1534performed:
1535
1536# Call the filesystem specific unmount() function for the filesystem
1537  that contains the mount point. This routine should indicate that the mount
1538  point no longer has a filesystem mounted below it.
1539
1540# Call the filesystem specific fsunmount_me() function for the mounted
1541  filesystem that we are trying to unmount(). This routine should clean up
1542  any resources that are no longer needed for the management of the file
1543  system being un-mounted.
1544
1545# Extract the mount table entry for the filesystem that was just
1546  dismounted from the mount table chain.
1547
1548# Free the memory associated with the extracted mount table entry.
1549
1550.. COMMENT: @page
1551
1552eval
1553====
1554
1555**File:**
1556
1557XXX
1558
1559**Processing:**
1560
1561XXX
1562
1563**Development Comments:**
1564
1565XXX
1566
1567.. COMMENT: @page
1568
1569getdentsc
1570=========
1571
1572**File:**
1573
1574XXX
1575
1576**Processing:**
1577
1578XXX
1579
1580**Development Comments:**
1581
1582XXX
1583
1584.. COMMENT: COPYRIGHT (c) 1988-2002.
1585
1586.. COMMENT: On-Line Applications Research Corporation (OAR).
1587
1588.. COMMENT: All rights reserved.
1589
1590Filesystem Implementation Requirements
1591######################################
1592
1593This chapter details the behavioral requirements that all filesystem
1594implementations must adhere to.
1595
1596General
1597=======
1598
1599The RTEMS filesystem framework was intended to be compliant with the
1600POSIX Files and Directories interface standard. The following filesystem
1601characteristics resulted in a functional switching layer.
1602.. code:: c
1603
1604    Figure of the Filesystem Functional Layering goes here.
1605    This figure includes networking and disk caching layering.
1606
1607# Application programs are presented with a standard set of POSIX
1608  compliant functions that allow them to interface with the files, devices
1609  and directories in the filesystem. The interfaces to these routines do
1610  not reflect the type of subordinate filesystem implementation in which
1611  the file will be found.
1612
1613# The filesystem framework developed under RTEMS allows for mounting
1614  filesystem of different types under the base filesystem.
1615
1616# The mechanics of locating file information may be quite different
1617  between filesystem types.
1618
1619# The process of locating a file may require crossing filesystem
1620  boundaries.
1621
1622# The transitions between filesystem and the processing required to
1623  access information in different filesystem is not visible at the level
1624  of the POSIX function call.
1625
1626# The POSIX interface standard provides file access by character
1627  pathname to the file in some functions and through an integer file
1628  descriptor in other functions.
1629
1630# The nature of the integer file descriptor and its associated
1631  processing is operating system and filesystem specific.
1632
1633# Directory and device information must be processed with some of the
1634  same routines that apply to files.
1635
1636# The form and content of directory and device information differs
1637  greatly from that of a regular file.
1638
1639# Files, directories and devices represent elements (nodes) of a tree
1640  hierarchy.
1641
1642# The rules for processing each of the node types that exist under the
1643  filesystem are node specific but are still not reflected in the POSIX
1644  interface routines.
1645
1646.. code:: c
1647
1648    Figure of the Filesystem Functional Layering goes here.
1649    This figure focuses on the Base Filesystem and IMFS.
1650
1651.. code:: c
1652
1653    Figure of the IMFS Memfile control blocks
1654
1655
1656File and Directory Removal Constraints
1657======================================
1658
1659The following POSIX constraints must be honored by all filesystems.
1660
1661- If a node is a directory with children it cannot be removed.
1662
1663- The root node of any filesystem, whether the base filesystem or a
1664  mounted filesystem, cannot be removed.
1665
1666- A node that is a directory that is acting as the mount point of a file
1667  system cannot be removed.
1668
1669- On filesystems supporting hard links, a link count is maintained.
1670  Prior to node removal, the node’s link count is decremented by one.  The
1671  link count must be less than one to allow for removal of the node.
1672
1673API Layering
1674============
1675
1676Mapping of Generic System Calls to Filesystem Specific Functions
1677----------------------------------------------------------------
1678
1679The list of generic system calls includes the routines open(), read(),
1680write(), close(), etc..
1681
1682The Files and Directories section of the POSIX Application Programs
1683Interface specifies a set of functions with calling arguments that are
1684used to gain access to the information in a filesystem. To the
1685application program, these functions allow access to information in any
1686mounted filesystem without explicit knowledge of the filesystem type or
1687the filesystem mount configuration. The following are functions that are
1688provided to the application:
1689
1690# access()
1691
1692# chdir()
1693
1694# chmod()
1695
1696# chown()
1697
1698# close()
1699
1700# closedir()
1701
1702# fchmod()
1703
1704# fcntl()
1705
1706# fdatasync()
1707
1708# fpathconf()
1709
1710# fstat()
1711
1712# fsync()
1713
1714# ftruncate()
1715
1716# link()
1717
1718# lseek()
1719
1720# mkdir()
1721
1722# mknod()
1723
1724# mount()
1725
1726# open()
1727
1728# opendir()
1729
1730# pathconf()
1731
1732# read()
1733
1734# readdir()
1735
1736# rewinddir()
1737
1738# rmdir()
1739
1740# rmnod()
1741
1742# scandir()
1743
1744# seekdir()
1745
1746# stat()
1747
1748# telldir()
1749
1750# umask()
1751
1752# unlink()
1753
1754# unmount()
1755
1756# utime()
1757
1758# write()
1759
1760The filesystem’s type as well as the node type within the filesystem
1761determine the nature of the processing that must be performed for each of
1762the functions above. The RTEMS filesystem provides a framework that
1763allows new filesystem to be developed and integrated without alteration
1764to the basic framework.
1765
1766To provide the functional switching that is required, each of the POSIX
1767file and directory functions have been implemented as a shell function.
1768The shell function adheres to the POSIX interface standard. Within this
1769functional shell, filesystem and node type information is accessed which
1770is then used to invoke the appropriate filesystem and node type specific
1771routine to process the POSIX function call.
1772
1773File/Device/Directory function access via file control block - rtems_libio_t structure
1774--------------------------------------------------------------------------------------
1775
1776The POSIX open() function returns an integer file descriptor that is used
1777as a reference to file control block information for a specific file. The
1778file control block contains information that is used to locate node, file
1779system, mount table and functional handler information. The diagram in
1780Figure 8 depicts the relationship between and among the following
1781components.
1782
1783# File Descriptor Table
1784  This is an internal RTEMS structure that tracks all currently defined file
1785  descriptors in the system. The index that is returned by the file open()
1786  operation references a slot in this table. The slot contains a pointer to
1787  the file descriptor table entry for this file. The rtems_libio_t structure
1788  represents the file control block.
1789
1790# Allocation of entry in the File Descriptor Table
1791  Access to the file descriptor table is controlled through a semaphore that
1792  is implemented using the rtems_libio_allocate() function. This routine
1793  will grab a semaphore and then scan the file control blocks to determine
1794  which slot is free for use. The first free slot is marked as used and the
1795  index to this slot is returned as the file descriptor for the open()
1796  request. After the alterations have been made to the file control block
1797  table, the semaphore is released to allow further operations on the table.
1798
1799# Maximum number of entries in the file descriptor table is
1800  configurable through the src/exec/sapi/headers/confdefs.h file. If the
1801  CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value
1802  will represent the maximum number of file descriptors that are allowed.
1803  If CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default
1804  value of 20 will be used as the maximum number of file descriptors
1805  allowed.
1806
1807# File control block - rtems_libio_t structure
1808
1809  .. code:: c
1810
1811      struct rtems_libio_tt {
1812      rtems_driver_name_t              \*driver;
1813      off_t                             size;
1814      off_t                             offset;
1815      unsigned32                        flags;
1816      rtems_filesystem_location_info_t  pathinfo;
1817      Objects_Id                        sem;
1818      unsigned32                        data0;
1819      void                              data1;
1820      void                              file_info;
1821      rtems_filesystem_file_handlers_r  handlers;
1822      };
1823
1824  A file control block can exist for regular files, devices and directories.
1825  The following fields are important for regular file and directory access:
1826
1827  - Size - For a file this represents the number of bytes currently
1828    stored in a file. For a directory this field is not filled in.
1829
1830  - Offset - For a file this is the byte file position index relative to
1831    the start of the file. For a directory this is the byte offset into a
1832    sequence of dirent structures.
1833
1834  - Pathinfo - This is a structure that provides a pointer to node
1835    information, OPS table functions, Handler functions and the mount table
1836    entry associated with this node.
1837
1838  - file_info - A pointer to node information that is used by Handler
1839    functions
1840
1841  - handlers - A pointer to a table of handler functions that operate on
1842    a file, device or directory through a file descriptor index
1843
1844File/Directory function access via rtems_filesystem_location_info_t structure
1845-----------------------------------------------------------------------------
1846
1847The rtems_filesystem_location_info_tt structure below provides sufficient
1848information to process nodes under a mounted filesystem.
1849
1850.. code:: c
1851
1852    struct rtems_filesystem_location_info_tt {
1853    void                                     \*node_access;
1854    rtems_filesystem_file_handlers_r         \*handlers;
1855    rtems_filesystem_operations_table        \*ops;
1856    rtems_filesystem_mount_table_entry_t     \*mt_entry;
1857    };
1858
1859It contains a void pointer to filesystem specific nodal structure,
1860pointers to the OPS table for the filesystem that contains the node, the
1861node type specific handlers for the node and a reference pointer to the
1862mount table entry associated with the filesystem containing the node
1863
1864Operation Tables
1865================
1866
1867Filesystem specific operations are invoked indirectly.  The set of
1868routines that implement the filesystem are configured into two tables.
1869The Filesystem Handler Table has routines that are specific to a
1870filesystem but remain constant regardless of the actual file type.
1871The File Handler Table has routines that are both filesystem and file type
1872specific.
1873
1874Filesystem Handler Table Functions
1875----------------------------------
1876
1877OPS table functions are defined in a ``rtems_filesystem_operations_table``
1878structure.  It defines functions that are specific to a given filesystem.
1879One table exists for each filesystem that is supported in the RTEMS
1880configuration. The structure definition appears below and is followed by
1881general developmental information on each of the functions contained in this
1882function management structure.
1883
1884.. code:: c
1885
1886    typedef struct {
1887    rtems_filesystem_evalpath_t        evalpath;
1888    rtems_filesystem_evalmake_t        evalformake;
1889    rtems_filesystem_link_t            link;
1890    rtems_filesystem_unlink_t          unlink;
1891    rtems_filesystem_node_type_t       node_type;
1892    rtems_filesystem_mknod_t           mknod;
1893    rtems_filesystem_rmnod_t           rmnod;
1894    rtems_filesystem_chown_t           chown;
1895    rtems_filesystem_freenode_t        freenod;
1896    rtems_filesystem_mount_t           mount;
1897    rtems_filesystem_fsmount_me_t      fsmount_me;
1898    rtems_filesystem_unmount_t         unmount;
1899    rtems_filesystem_fsunmount_me_t    fsunmount_me;
1900    rtems_filesystem_utime_t           utime;
1901    rtems_filesystem_evaluate_link_t   eval_link;
1902    rtems_filesystem_symlink_t         symlink;
1903    } rtems_filesystem_operations_table;
1904
1905.. COMMENT: @page
1906
1907evalpath Handler
1908~~~~~~~~~~~~~~~~
1909
1910**Corresponding Structure Element:**
1911
1912evalpath
1913
1914**Arguments:**
1915
1916.. code:: c
1917
1918    const char                        \*pathname,      /* IN     \*/
1919    int                                flags,         /* IN     \*/
1920    rtems_filesystem_location_info_t  \*pathloc        /* IN/OUT \*/
1921
1922**Description:**
1923
1924This routine is responsible for evaluating the pathname passed in
1925based upon the flags and the valid ``rthems_filesystem_location_info_t``.
1926Additionally, it must make any changes to pathloc necessary to identify
1927the pathname node.  This should include calling the evalpath for a mounted
1928filesystem, if the given filesystem supports the mount command.
1929
1930This routine returns a 0 if the evaluation was successful.
1931Otherwise, it returns a -1 and sets errno to the correct error.
1932
1933This routine is required and should NOT be set to NULL.
1934
1935.. COMMENT: @page
1936
1937evalformake Handler
1938~~~~~~~~~~~~~~~~~~~
1939
1940**Corresponding Structure Element:**
1941
1942evalformake
1943
1944**Arguments:**
1945
1946.. code:: c
1947
1948    const char                       \*path,       /* IN \*/
1949    rtems_filesystem_location_info_t \*pathloc,    /* IN/OUT \*/
1950    const char                      \**name        /* OUT    \*/
1951
1952**Description:**
1953
1954This method is given a path to evaluate and a valid start location.  It
1955is responsible for finding the parent node for a requested make command,
1956setting pathloc information to identify the parent node, and setting
1957the name pointer to the first character of the name of the new node.
1958Additionally, if the filesystem supports the mount command, this method
1959should call the evalformake routine for the mounted filesystem.
1960
1961This routine returns a 0 if the evaluation was successful.  Otherwise, it
1962returns a -1 and sets errno to the correct error.
1963
1964This routine is required and should NOT be set to NULL.  However, if
1965the filesystem does not support user creation of a new node, it may
1966set errno to ENOSYS and return -1.
1967
1968.. COMMENT: @page
1969
1970link Handler
1971~~~~~~~~~~~~
1972
1973**Corresponding Structure Element:**
1974
1975link
1976
1977**Arguments:**
1978
1979.. code:: c
1980
1981    rtems_filesystem_location_info_t    \*to_loc,      /* IN \*/
1982    rtems_filesystem_location_info_t    \*parent_loc,  /* IN \*/
1983    const char                          \*token        /* IN \*/
1984
1985**Description:**
1986
1987This routine is used to create a hard-link.
1988
1989It will first examine the st_nlink count of the node that we are trying to.
1990If the link count exceeds LINK_MAX an error will be returned.
1991
1992The name of the link will be normalized to remove extraneous separators from
1993the end of the name.
1994
1995This routine is not required and may be set to NULL.
1996
1997.. COMMENT: @page
1998
1999unlink Handler
2000~~~~~~~~~~~~~~
2001
2002**Corresponding Structure Element:**
2003
2004XXX
2005
2006**Arguments:**
2007
2008XXX
2009
2010**Description:**
2011
2012XXX
2013
2014.. COMMENT: @page
2015
2016node_type Handler
2017~~~~~~~~~~~~~~~~~
2018
2019**Corresponding Structure Element:**
2020
2021node_type()
2022
2023**Arguments:**
2024
2025.. code:: c
2026
2027    rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
2028
2029**Description:**
2030
2031XXX
2032
2033.. COMMENT: @page
2034
2035mknod Handler
2036~~~~~~~~~~~~~
2037
2038**Corresponding Structure Element:**
2039
2040mknod()
2041
2042**Arguments:**
2043
2044.. code:: c
2045
2046    const char                          \*token,        /* IN \*/
2047    mode_t                               mode,         /* IN \*/
2048    dev_t                                dev,          /* IN \*/
2049    rtems_filesystem_location_info_t    \*pathloc       /* IN/OUT \*/
2050
2051**Description:**
2052
2053XXX
2054
2055.. COMMENT: @page
2056
2057rmnod Handler
2058~~~~~~~~~~~~~
2059
2060**Corresponding Structure Element:**
2061
2062XXX
2063
2064**Arguments:**
2065
2066XXX
2067
2068**Description:**
2069
2070XXX
2071
2072.. COMMENT: @page
2073
2074chown Handler
2075~~~~~~~~~~~~~
2076
2077**Corresponding Structure Element:**
2078
2079chown()
2080
2081**Arguments:**
2082
2083.. code:: c
2084
2085    rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
2086    uid_t                                owner          /* IN \*/
2087    gid_t                                group          /* IN \*/
2088
2089**Description:**
2090
2091XXX
2092
2093.. COMMENT: @page
2094
2095freenod Handler
2096~~~~~~~~~~~~~~~
2097
2098**Corresponding Structure Element:**
2099
2100freenod()
2101
2102**Arguments:**
2103
2104.. code:: c
2105
2106    rtems_filesystem_location_info_t      \*pathloc       /* IN \*/
2107
2108**Description:**
2109
2110This routine is used by the generic code to allow memory to be allocated
2111during the evaluate routines, and set free when the generic code is finished
2112accessing a node.  If the evaluate routines allocate memory to identify
2113a node this routine should be utilized to free that memory.
2114
2115This routine is not required and may be set to NULL.
2116
2117.. COMMENT: @page
2118
2119mount Handler
2120~~~~~~~~~~~~~
2121
2122**Corresponding Structure Element:**
2123
2124mount()
2125
2126**Arguments:**
2127
2128.. code:: c
2129
2130    rtems_filesystem_mount_table_entry_t   \*mt_entry
2131
2132**Description:**
2133
2134XXX
2135
2136.. COMMENT: @page
2137
2138fsmount_me Handler
2139~~~~~~~~~~~~~~~~~~
2140
2141**Corresponding Structure Element:**
2142
2143XXX
2144
2145**Arguments:**
2146
2147.. code:: c
2148
2149    rtems_filesystem_mount_table_entry_t   \*mt_entry
2150
2151**Description:**
2152
2153This function is provided with a filesystem to take care of the internal
2154filesystem management details associated with mounting that filesystem
2155under the RTEMS environment.
2156
2157It is not responsible for the mounting details associated the filesystem
2158containing the mount point.
2159
2160The rtems_filesystem_mount_table_entry_t structure contains the key elements
2161below:
2162
2163rtems_filesystem_location_info_t         \*mt_point_node,
2164
2165This structure contains information about the mount point. This
2166allows us to find the ops-table and the handling functions
2167associated with the filesystem containing the mount point.
2168
2169rtems_filesystem_location_info_t         \*fs_root_node,
2170
2171This structure contains information about the root node in the file
2172system to be mounted. It allows us to find the ops-table and the
2173handling functions associated with the filesystem to be mounted.
2174
2175rtems_filesystem_options_t                 options,
2176
2177Read only or read/write access
2178
2179void                                         \*fs_info,
2180
2181This points to an allocated block of memory the will be used to
2182hold any filesystem specific information of a global nature. This
2183allocated region if important because it allows us to mount the
2184same filesystem type more than once under the RTEMS system.
2185Each instance of the mounted filesystem has its own set of global
2186management information that is separate from the global
2187management information associated with the other instances of the
2188mounted filesystem type.
2189
2190rtems_filesystem_limits_and_options_t    pathconf_info,
2191
2192The table contains the following set of values associated with the
2193mounted filesystem:
2194
2195- link_max
2196
2197- max_canon
2198
2199- max_input
2200
2201- name_max
2202
2203- path_max
2204
2205- pipe_buf
2206
2207- posix_async_io
2208
2209- posix_chown_restrictions
2210
2211- posix_no_trunc
2212
2213- posix_prio_io
2214
2215- posix_sync_io
2216
2217- posix_vdisable
2218
2219These values are accessed with the pathconf() and the fpathconf ()
2220functions.
2221
2222const char                                   \*dev
2223
2224The is intended to contain a string that identifies the device that contains
2225the filesystem information. The filesystems that are currently implemented
2226are memory based and don’t require a device specification.
2227
2228If the mt_point_node.node_access is NULL then we are mounting the base file
2229system.
2230
2231The routine will create a directory node for the root of the IMFS file
2232system.
2233
2234The node will have read, write and execute permissions for owner, group and
2235others.
2236
2237The node’s name will be a null string.
2238
2239A filesystem information structure(fs_info) will be allocated and
2240initialized for the IMFS filesystem. The fs_info pointer in the mount table
2241entry will be set to point the filesystem information structure.
2242
2243The pathconf_info element of the mount table will be set to the appropriate
2244table of path configuration constants (LIMITS_AND_OPTIONS).
2245
2246The fs_root_node structure will be filled in with the following:
2247
2248- pointer to the allocated root node of the filesystem
2249
2250- directory handlers for a directory node under the IMFS filesystem
2251
2252- OPS table functions for the IMFS
2253
2254A 0 will be returned to the calling routine if the process succeeded,
2255otherwise a 1 will be returned.
2256
2257.. COMMENT: @page
2258
2259unmount Handler
2260~~~~~~~~~~~~~~~
2261
2262**Corresponding Structure Element:**
2263
2264XXX
2265
2266**Arguments:**
2267
2268XXX
2269
2270**Description:**
2271
2272XXX
2273
2274.. COMMENT: @page
2275
2276fsunmount_me Handler
2277~~~~~~~~~~~~~~~~~~~~
2278
2279**Corresponding Structure Element:**
2280
2281imfs_fsunmount_me()
2282
2283**Arguments:**
2284
2285.. code:: c
2286
2287    rtems_filesystem_mount_table_entry_t   \*mt_entry
2288
2289**Description:**
2290
2291XXX
2292
2293.. COMMENT: @page
2294
2295utime Handler
2296~~~~~~~~~~~~~
2297
2298**Corresponding Structure Element:**
2299
2300XXX
2301
2302**Arguments:**
2303
2304XXX
2305
2306**Description:**
2307
2308XXX
2309
2310.. COMMENT: @page
2311
2312eval_link Handler
2313~~~~~~~~~~~~~~~~~
2314
2315**Corresponding Structure Element:**
2316
2317XXX
2318
2319**Arguments:**
2320
2321XXX
2322
2323**Description:**
2324
2325XXX
2326
2327.. COMMENT: @page
2328
2329symlink Handler
2330~~~~~~~~~~~~~~~
2331
2332**Corresponding Structure Element:**
2333
2334XXX
2335
2336**Arguments:**
2337
2338XXX
2339
2340**Description:**
2341
2342XXX
2343
2344.. COMMENT: @page
2345
2346File Handler Table Functions
2347----------------------------
2348
2349Handler table functions are defined in a ``rtems_filesystem_file_handlers_r``
2350structure. It defines functions that are specific to a node type in a given
2351filesystem. One table exists for each of the filesystem’s node types. The
2352structure definition appears below. It is followed by general developmental
2353information on each of the functions associated with regular files contained
2354in this function management structure.
2355.. code:: c
2356
2357    typedef struct {
2358    rtems_filesystem_open_t           open;
2359    rtems_filesystem_close_t          close;
2360    rtems_filesystem_read_t           read;
2361    rtems_filesystem_write_t          write;
2362    rtems_filesystem_ioctl_t          ioctl;
2363    rtems_filesystem_lseek_t          lseek;
2364    rtems_filesystem_fstat_t          fstat;
2365    rtems_filesystem_fchmod_t         fchmod;
2366    rtems_filesystem_ftruncate_t      ftruncate;
2367    rtems_filesystem_fpathconf_t      fpathconf;
2368    rtems_filesystem_fsync_t          fsync;
2369    rtems_filesystem_fdatasync_t      fdatasync;
2370    rtems_filesystem_fcntl_t          fcntl;
2371    } rtems_filesystem_file_handlers_r;
2372
2373.. COMMENT: @page
2374
2375open Handler
2376~~~~~~~~~~~~
2377
2378**Corresponding Structure Element:**
2379
2380open()
2381
2382**Arguments:**
2383
2384.. code:: c
2385
2386    rtems_libio_t   \*iop,
2387    const char      \*pathname,
2388    unsigned32       flag,
2389    unsigned32       mode
2390
2391**Description:**
2392
2393XXX
2394
2395.. COMMENT: @page
2396
2397close Handler
2398~~~~~~~~~~~~~
2399
2400**Corresponding Structure Element:**
2401
2402close()
2403
2404**Arguments:**
2405
2406.. code:: c
2407
2408    rtems_libio_t     \*iop
2409
2410**Description:**
2411
2412XXX
2413
2414**NOTES:**
2415
2416XXX
2417
2418.. COMMENT: @page
2419
2420read Handler
2421~~~~~~~~~~~~
2422
2423**Corresponding Structure Element:**
2424
2425read()
2426
2427**Arguments:**
2428
2429.. code:: c
2430
2431    rtems_libio_t     \*iop,
2432    void              \*buffer,
2433    unsigned32         count
2434
2435**Description:**
2436
2437XXX
2438
2439**NOTES:**
2440
2441XXX
2442
2443.. COMMENT: @page
2444
2445write Handler
2446~~~~~~~~~~~~~
2447
2448**Corresponding Structure Element:**
2449
2450XXX
2451
2452**Arguments:**
2453
2454XXX
2455
2456**Description:**
2457
2458XXX
2459
2460**NOTES:**
2461
2462XXX
2463
2464.. COMMENT: @page
2465
2466ioctl Handler
2467~~~~~~~~~~~~~
2468
2469**Corresponding Structure Element:**
2470
2471XXX
2472
2473**Arguments:**
2474
2475.. code:: c
2476
2477    rtems_libio_t     \*iop,
2478    unsigned32       command,
2479    void              \*buffer
2480
2481**Description:**
2482
2483XXX
2484
2485**NOTES:**
2486
2487XXX
2488
2489.. COMMENT: @page
2490
2491lseek Handler
2492~~~~~~~~~~~~~
2493
2494**Corresponding Structure Element:**
2495
2496lseek()
2497
2498**Arguments:**
2499
2500.. code:: c
2501
2502    rtems_libio_t     \*iop,
2503    off_t              offset,
2504    int                whence
2505
2506**Description:**
2507
2508XXX
2509
2510**NOTES:**
2511
2512XXX
2513
2514.. COMMENT: @page
2515
2516fstat Handler
2517~~~~~~~~~~~~~
2518
2519**Corresponding Structure Element:**
2520
2521fstat()
2522
2523**Arguments:**
2524
2525.. code:: c
2526
2527    rtems_filesystem_location_info_t   \*loc,
2528    struct stat                        \*buf
2529
2530**Description:**
2531
2532The following information is extracted from the filesystem
2533specific node and placed in the ``stat`` structure:
2534
2535- st_mode
2536
2537- st_nlink
2538
2539- st_ino
2540
2541- st_uid
2542
2543- st_gid
2544
2545- st_atime
2546
2547- st_mtime
2548
2549- st_ctime
2550
2551**NOTES:**
2552
2553Both the ``stat()`` and ``lstat()`` services are
2554implemented directly using the ``fstat()`` handler.  The
2555difference in behavior is determined by how the path is evaluated
2556prior to this handler being called on a particular
2557file entity.
2558
2559The ``fstat()`` system call is implemented directly
2560on top of this filesystem handler.
2561
2562.. COMMENT: @page
2563
2564fchmod Handler
2565~~~~~~~~~~~~~~
2566
2567**Corresponding Structure Element:**
2568
2569fchmod()
2570
2571**Arguments:**
2572
2573.. code:: c
2574
2575    rtems_libio_t     \*iop
2576    mode_t              mode
2577
2578**Description:**
2579
2580XXX
2581
2582**NOTES:**
2583
2584XXX
2585
2586.. COMMENT: @page
2587
2588ftruncate Handler
2589~~~~~~~~~~~~~~~~~
2590
2591**Corresponding Structure Element:**
2592
2593XXX
2594
2595**Arguments:**
2596
2597XXX
2598
2599**Description:**
2600
2601XXX
2602
2603**NOTES:**
2604
2605XXX
2606
2607fpathconf Handler
2608~~~~~~~~~~~~~~~~~
2609
2610**Corresponding Structure Element:**
2611
2612XXX
2613
2614**Arguments:**
2615
2616XXX
2617
2618**Description:**
2619
2620XXX
2621
2622**NOTES:**
2623
2624XXX
2625
2626.. COMMENT: @page
2627
2628fsync Handler
2629~~~~~~~~~~~~~
2630
2631**Corresponding Structure Element:**
2632
2633XXX
2634
2635**Arguments:**
2636
2637XXX
2638
2639**Description:**
2640
2641XXX
2642
2643**NOTES:**
2644
2645XXX
2646
2647.. COMMENT: @page
2648
2649fdatasync Handler
2650~~~~~~~~~~~~~~~~~
2651
2652**Corresponding Structure Element:**
2653
2654XXX
2655
2656**Arguments:**
2657
2658XXX
2659
2660**Description:**
2661
2662XXX
2663
2664**NOTES:**
2665
2666XXX
2667
2668.. COMMENT: @page
2669
2670fcntl Handler
2671~~~~~~~~~~~~~
2672
2673**Corresponding Structure Element:**
2674
2675XXX
2676
2677**Arguments:**
2678
2679XXX
2680
2681**Description:**
2682
2683XXX
2684
2685**NOTES:**
2686
2687XXX
2688
2689.. COMMENT: COPYRIGHT (c) 1988-2002.
2690
2691.. COMMENT: On-Line Applications Research Corporation (OAR).
2692
2693.. COMMENT: All rights reserved.
2694
2695In-Memory Filesystem
2696####################
2697
2698This chapter describes the In-Memory FileSystem (IMFS).  The IMFS is a
2699full featured POSIX filesystem that keeps all information in memory.
2700
2701IMFS Per Node Data Structure
2702============================
2703
2704Each regular file, device, hard link, and directory is represented by a data
2705structure called a ``jnode``. The ``jnode`` is formally represented by the
2706structure:
2707.. code:: c
2708
2709    struct IMFS_jnode_tt {
2710    Chain_Node          Node;             /* for chaining them together \*/
2711    IMFS_jnode_t       \*Parent;           /* Parent node \*/
2712    char                name[NAME_MAX+1]; /* "basename" \*/
2713    mode_t              st_mode;          /* File mode \*/
2714    nlink_t             st_nlink;         /* Link count \*/
2715    ino_t               st_ino;           /* inode \*/
2716    uid_t               st_uid;           /* User ID of owner \*/
2717    gid_t               st_gid;           /* Group ID of owner \*/
2718    time_t              st_atime;         /* Time of last access \*/
2719    time_t              st_mtime;         /* Time of last modification \*/
2720    time_t              st_ctime;         /* Time of last status change \*/
2721    IMFS_jnode_types_t  type;             /* Type of this entry \*/
2722    IMFS_typs_union     info;
2723    };
2724
2725The key elements of this structure are listed below together with a brief
2726explanation of their role in the filesystem.
2727
2728*Node*
2729    exists to allow the entire ``jnode`` structure to be included in a chain.
2730
2731*Parent*
2732    is a pointer to another ``jnode`` structure that is the logical parent of the
2733    node in which it appears.  This field may be NULL if the file associated with
2734    this node is deleted but there are open file descriptors on this file or
2735    there are still hard links to this node.
2736
2737*name*
2738    is the name of this node within the filesystem hierarchical tree. Example:  If
2739    the fully qualified pathname to the ``jnode`` was ``/a/b/c``, the``jnode`` name field would contain the null terminated string ``"c"``.
2740
2741*st_mode*
2742    is the standard Unix access permissions for the file or directory.
2743
2744*st_nlink*
2745    is the number of hard links to this file. When a ``jnode`` is first created
2746    its link count is set to 1. A ``jnode`` and its associated resources
2747    cannot be deleted unless its link count is less than 1.
2748
2749*st_ino*
2750    is a unique node identification number
2751
2752*st_uid*
2753    is the user ID of the file’s owner
2754
2755*st_gid*
2756    is the group ID of the file’s owner
2757
2758*st_atime*
2759    is the time of the last access to this file
2760
2761*st_mtime*
2762    is the time of the last modification of this file
2763
2764*st_ctime*
2765    is the time of the last status change to the file
2766
2767*type*
2768    is the indication of node type must be one of the following states:
2769    - IMFS_DIRECTORY
2770    - IMFS_MEMORY_FILE
2771    - IMFS_HARD_LINK
2772    - IMFS_SYM_LINK
2773    - IMFS_DEVICE
2774
2775*info*
2776    is this contains a structure that is unique to file type (See IMFS_typs_union
2777    in imfs.h).
2778
2779    - IMFS_DIRECTORY
2780
2781      An IMFS directory contains a dynamic chain structure that
2782      records all files and directories that are subordinate to the directory node.
2783
2784    - IMFS_MEMORY_FILE
2785
2786      Under the in memory filesystem regular files hold data. Data is dynamically
2787      allocated to the file in 128 byte chunks of memory.  The individual chunks of
2788      memory are tracked by arrays of pointers that record the address of the
2789      allocated chunk of memory. Single, double, and triple indirection pointers
2790      are used to record the locations of all segments of the file.  The
2791      memory organization of an IMFS file are discussed elsewhere in this manual.
2792
2793    - IMFS_HARD_LINK
2794
2795      The IMFS filesystem supports the concept of hard links to other nodes in the
2796      IMFS filesystem.  These hard links are actual pointers to other nodes in the
2797      same filesystem. This type of link cannot cross-filesystem boundaries.
2798
2799    - IMFS_SYM_LINK
2800
2801      The IMFS filesystem supports the concept of symbolic links to other nodes in
2802      any filesystem. A symbolic link consists of a pointer to a character string
2803      that represents the pathname to the target node. This type of link can
2804      cross-filesystem boundaries.  Just as with most versions of UNIX supporting
2805      symbolic links, a symbolic link can point to a non-existent file.
2806
2807    - IMFS_DEVICE
2808
2809      All RTEMS devices now appear as files under the in memory filesystem. On
2810      system initialization, all devices are registered as nodes under the file
2811      system.
2812
2813Miscellaneous IMFS Information
2814==============================
2815
2816Memory associated with the IMFS
2817===============================
2818
2819A memory based filesystem draws its resources for files and directories
2820from the memory resources of the system. When it is time to un-mount the
2821filesystem, the memory resources that supported filesystem are set free.
2822In order to free these resources, a recursive walk of the filesystems
2823tree structure will be performed. As the leaf nodes under the filesystem
2824are encountered their resources are freed. When directories are made empty
2825by this process, their resources are freed.
2826
2827Node removal constraints for the IMFS
2828-------------------------------------
2829
2830The IMFS conforms to the general filesystem requirements for node
2831removal.  See `File and Directory Removal Constraints`_.
2832
2833IMFS General Housekeeping Notes
2834-------------------------------
2835
2836The following is a list of odd housekeeping notes for the IMFS.
2837
2838- If the global variable rtems_filesystem_current refers to the node that
2839  we are trying to remove, the node_access element of this structure must be
2840  set to NULL to invalidate it.
2841
2842- If the node was of IMFS_MEMORY_FILE type, free the memory associated
2843  with the memory file before freeing the node. Use the IMFS_memfile_remove()
2844  function.
2845
2846IMFS Operation Tables
2847=====================
2848
2849IMFS Filesystem Handler Table Functions
2850---------------------------------------
2851
2852OPS table functions are defined in a rtems_filesystem_operations_table
2853structure.  It defines functions that are specific to a given filesystem.
2854One table exists for each filesystem that is supported in the RTEMS
2855configuration. The structure definition appears below and is followed by
2856general developmental information on each of the functions contained in this
2857function management structure.
2858.. code:: c
2859
2860    rtems_filesystem_operations_table  IMFS_ops = {
2861    IMFS_eval_path,
2862    IMFS_evaluate_for_make,
2863    IMFS_link,
2864    IMFS_unlink,
2865    IMFS_node_type,
2866    IMFS_mknod,
2867    IMFS_rmnod,
2868    IMFS_chown,
2869    IMFS_freenodinfo,
2870    IMFS_mount,
2871    IMFS_initialize,
2872    IMFS_unmount,
2873    IMFS_fsunmount,
2874    IMFS_utime,
2875    IMFS_evaluate_link,
2876    IMFS_symlink,
2877    IMFS_readlink
2878    };
2879
2880.. COMMENT: @page
2881
2882IMFS_evalpath()
2883~~~~~~~~~~~~~~~
2884
2885**Corresponding Structure Element:**
2886
2887XXX
2888
2889**Arguments:**
2890
2891XXX
2892
2893**File:**
2894
2895XXX
2896
2897**Description:**
2898
2899XXX
2900
2901.. COMMENT: @page
2902
2903IMFS_evalformake()
2904~~~~~~~~~~~~~~~~~~
2905
2906**Corresponding Structure Element:**
2907
2908XXX
2909
2910**Arguments:**
2911
2912XXX
2913
2914**File:**
2915
2916XXX
2917
2918**Description:**
2919
2920XXX
2921
2922.. COMMENT: @page
2923
2924IMFS_link()
2925~~~~~~~~~~~
2926
2927**Corresponding Structure Element:**
2928
2929link
2930
2931**Arguments:**
2932
2933.. code:: c
2934
2935    rtems_filesystem_location_info_t    \*to_loc,      /* IN \*/
2936    rtems_filesystem_location_info_t    \*parent_loc,  /* IN \*/
2937    const char                          \*token        /* IN \*/
2938
2939**File:**
2940
2941imfs_link.c
2942
2943**Description:**
2944
2945This routine is used in the IMFS filesystem to create a hard-link.
2946
2947It will first examine the st_nlink count of the node that we are trying to.
2948If the link count exceeds LINK_MAX an error will be returned.
2949
2950The name of the link will be normalized to remove extraneous separators from
2951the end of the name.
2952
2953IMFS_create_node will be used to create a filesystem node that will have the
2954following characteristics:
2955
2956- parent that was determined in the link() function in file link.c
2957
2958- Type will be set to IMFS_HARD_LINK
2959
2960- name will be set to the normalized name
2961
2962- mode of the hard-link will be set to the mode of the target node
2963
2964If there was trouble allocating memory for the new node an error will be
2965returned.
2966
2967The st_nlink count of the target node will be incremented to reflect the new
2968link.
2969
2970The time fields of the link will be set to reflect the creation time of the
2971hard-link.
2972
2973.. COMMENT: @page
2974
2975IMFS_unlink()
2976~~~~~~~~~~~~~
2977
2978**Corresponding Structure Element:**
2979
2980XXX
2981
2982**Arguments:**
2983
2984XXX
2985
2986**File:**
2987
2988XXX
2989
2990**Description:**
2991
2992XXX
2993
2994.. COMMENT: @page
2995
2996IMFS_node_type()
2997~~~~~~~~~~~~~~~~
2998
2999**Corresponding Structure Element:**
3000
3001IMFS_node_type()
3002
3003**Arguments:**
3004
3005.. code:: c
3006
3007    rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
3008
3009**File:**
3010
3011imfs_ntype.c
3012
3013**Description:**
3014
3015This routine will locate the IMFS_jnode_t structure that holds ownership
3016information for the selected node in the filesystem.
3017
3018This structure is pointed to by pathloc->node_access.
3019
3020The IMFS_jnode_t type element indicates one of the node types listed below:
3021
3022- RTEMS_FILESYSTEM_DIRECTORY
3023
3024- RTEMS_FILESYSTEM_DEVICE
3025
3026- RTEMS_FILESYSTEM_HARD_LINK
3027
3028- RTEMS_FILESYSTEM_MEMORY_FILE
3029
3030.. COMMENT: @page
3031
3032IMFS_mknod()
3033~~~~~~~~~~~~
3034
3035**Corresponding Structure Element:**
3036
3037IMFS_mknod()
3038
3039**Arguments:**
3040
3041.. code:: c
3042
3043    const char                          \*token,        /* IN \*/
3044    mode_t                               mode,         /* IN \*/
3045    dev_t                                dev,          /* IN \*/
3046    rtems_filesystem_location_info_t    \*pathloc       /* IN/OUT \*/
3047
3048**File:**
3049
3050imfs_mknod.c
3051
3052**Description:**
3053
3054This routine will examine the mode argument to determine is we are trying to
3055create a directory, regular file and a device node. The creation of other
3056node types is not permitted and will cause an assert.
3057
3058Memory space will be allocated for a ``jnode`` and the node will be set up
3059according to the nodal type that was specified. The IMFS_create_node()
3060function performs the allocation and setup of the node.
3061
3062The only problem that is currently reported is the lack of memory when we
3063attempt to allocate space for the ``jnode`` (ENOMEN).
3064
3065.. COMMENT: @page
3066
3067IMFS_rmnod()
3068~~~~~~~~~~~~
3069
3070**Corresponding Structure Element:**
3071
3072XXX
3073
3074**Arguments:**
3075
3076XXX
3077
3078**File:**
3079
3080XXX
3081
3082**Description:**
3083
3084XXX
3085
3086.. COMMENT: @page
3087
3088IMFS_chown()
3089~~~~~~~~~~~~
3090
3091**Corresponding Structure Element:**
3092
3093IMFS_chown()
3094
3095**Arguments:**
3096
3097.. code:: c
3098
3099    rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
3100    uid_t                                owner          /* IN \*/
3101    gid_t                                group          /* IN \*/
3102
3103**File:**
3104
3105imfs_chown.c
3106
3107**Description:**
3108
3109This routine will locate the IMFS_jnode_t structure that holds ownership
3110information for the selected node in the filesystem.
3111
3112This structure is pointed to by pathloc->node_access.
3113
3114The st_uid and st_gid fields of the node are then modified. Since this is a
3115memory based filesystem, no further action is required to alter the
3116ownership of the IMFS_jnode_t structure.
3117
3118.. COMMENT: @page
3119
3120IMFS_freenod()
3121~~~~~~~~~~~~~~
3122
3123**Corresponding Structure Element:**
3124
3125IMFS_freenod()
3126
3127**Arguments:**
3128
3129.. code:: c
3130
3131    rtems_filesystem_location_info_t      \*pathloc       /* IN \*/
3132
3133**File:**
3134
3135imfs_free.c
3136
3137**Description:**
3138
3139This method is a private function to the IMFS.  It is called by IMFS routines
3140to free nodes that have been allocated.  Examples of where this routine
3141may be called from are unlink and rmnod.
3142
3143Note:  This routine should not be confused with the filesystem callback
3144freenod.  The IMFS allocates memory until the node no longer exists.
3145
3146.. COMMENT: @page
3147
3148IMFS_freenodinfo()
3149~~~~~~~~~~~~~~~~~~
3150
3151**Corresponding Structure Element:**
3152
3153IMFS_freenodinfo()
3154
3155**Arguments:**
3156
3157.. code:: c
3158
3159    rtems_filesystem_location_info_t      \*pathloc       /* IN \*/
3160
3161**File:**
3162
3163imfs_free.c
3164
3165**Description:**
3166
3167The In-Memory File System does not need to allocate memory during the
3168evaluate routines. Therefore, this routine simply routines PASS.
3169
3170.. COMMENT: @page
3171
3172IMFS_mount()
3173~~~~~~~~~~~~
3174
3175**Corresponding Structure Element:**
3176
3177IMFS_mount()
3178
3179**Arguments:**
3180
3181.. code:: c
3182
3183    rtems_filesystem_mount_table_entry_t   \*mt_entry
3184
3185**File:**
3186
3187imfs_mount.c
3188
3189**Description:**
3190
3191This routine provides the filesystem specific processing required to mount a
3192filesystem for the system that contains the mount point. It will determine
3193if the point that we are trying to mount onto is a node of IMFS_DIRECTORY
3194type.
3195
3196If it is the node’s info element is altered so that the info.directory.mt_fs
3197element points to the mount table chain entry that is associated with the
3198mounted filesystem at this point. The info.directory.mt_fs element can be
3199examined to determine if a filesystem is mounted at a directory. If it is
3200NULL, the directory does not serve as a mount point. A non-NULL entry
3201indicates that the directory does serve as a mount point and the value of
3202info.directory.mt_fs can be used to locate the mount table chain entry that
3203describes the filesystem mounted at this point.
3204
3205.. COMMENT: @page
3206
3207IMFS_fsmount_me()
3208~~~~~~~~~~~~~~~~~
3209
3210**Corresponding Structure Element:**
3211
3212IMFS_initialize()
3213
3214**Arguments:**
3215
3216.. code:: c
3217
3218    rtems_filesystem_mount_table_entry_t   \*mt_entry
3219
3220**File:**
3221
3222imfs_init.c
3223
3224**Description:**
3225
3226This function is provided with a filesystem to take care of the internal
3227filesystem management details associated with mounting that filesystem
3228under the RTEMS environment.
3229
3230It is not responsible for the mounting details associated the filesystem
3231containing the mount point.
3232
3233The rtems_filesystem_mount_table_entry_t structure contains the key elements
3234below:
3235
3236rtems_filesystem_location_info_t         \*mt_point_node,
3237
3238This structure contains information about the mount point. This
3239allows us to find the ops-table and the handling functions
3240associated with the filesystem containing the mount point.
3241
3242rtems_filesystem_location_info_t         \*fs_root_node,
3243
3244This structure contains information about the root node in the file
3245system to be mounted. It allows us to find the ops-table and the
3246handling functions associated with the filesystem to be mounted.
3247
3248rtems_filesystem_options_t                 options,
3249
3250Read only or read/write access
3251
3252void                                         \*fs_info,
3253
3254This points to an allocated block of memory the will be used to
3255hold any filesystem specific information of a global nature. This
3256allocated region if important because it allows us to mount the
3257same filesystem type more than once under the RTEMS system.
3258Each instance of the mounted filesystem has its own set of global
3259management information that is separate from the global
3260management information associated with the other instances of the
3261mounted filesystem type.
3262
3263rtems_filesystem_limits_and_options_t    pathconf_info,
3264
3265The table contains the following set of values associated with the
3266mounted filesystem:
3267
3268- link_max
3269
3270- max_canon
3271
3272- max_input
3273
3274- name_max
3275
3276- path_max
3277
3278- pipe_buf
3279
3280- posix_async_io
3281
3282- posix_chown_restrictions
3283
3284- posix_no_trunc
3285
3286- posix_prio_io
3287
3288- posix_sync_io
3289
3290- posix_vdisable
3291
3292These values are accessed with the pathconf() and the fpathconf ()
3293functions.
3294
3295const char                                   \*dev
3296
3297The is intended to contain a string that identifies the device that contains
3298the filesystem information. The filesystems that are currently implemented
3299are memory based and don’t require a device specification.
3300
3301If the mt_point_node.node_access is NULL then we are mounting the base file
3302system.
3303
3304The routine will create a directory node for the root of the IMFS file
3305system.
3306
3307The node will have read, write and execute permissions for owner, group and
3308others.
3309
3310The node’s name will be a null string.
3311
3312A filesystem information structure(fs_info) will be allocated and
3313initialized for the IMFS filesystem. The fs_info pointer in the mount table
3314entry will be set to point the filesystem information structure.
3315
3316The pathconf_info element of the mount table will be set to the appropriate
3317table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
3318
3319The fs_root_node structure will be filled in with the following:
3320
3321- pointer to the allocated root node of the filesystem
3322
3323- directory handlers for a directory node under the IMFS filesystem
3324
3325- OPS table functions for the IMFS
3326
3327A 0 will be returned to the calling routine if the process succeeded,
3328otherwise a 1 will be returned.
3329
3330.. COMMENT: @page
3331
3332IMFS_unmount()
3333~~~~~~~~~~~~~~
3334
3335**Corresponding Structure Element:**
3336
3337IMFS_unmount()
3338
3339**Arguments:**
3340
3341.. code:: c
3342
3343    rtems_filesystem_mount_table_entry_t   \*mt_entry
3344
3345**File:**
3346
3347imfs_unmount.c
3348
3349**Description:**
3350
3351This routine allows the IMFS to unmount a filesystem that has been
3352mounted onto a IMFS directory.
3353
3354The mount entry mount point node access is verified to be a mounted
3355directory.  It’s mt_fs is set to NULL.  This identifies to future
3356calles into the IMFS that this directory node is no longer a mount
3357point.  Additionally, it will allow any directories that were hidden
3358by the mounted system to again become visible.
3359
3360.. COMMENT: @page
3361
3362IMFS_fsunmount()
3363~~~~~~~~~~~~~~~~
3364
3365**Corresponding Structure Element:**
3366
3367imfs_fsunmount()
3368
3369**Arguments:**
3370
3371.. code:: c
3372
3373    rtems_filesystem_mount_table_entry_t   \*mt_entry
3374
3375**File:**
3376
3377imfs_init.c
3378
3379**Description:**
3380
3381This method unmounts this instance of the IMFS file system.  It is the
3382counterpart to the IMFS_initialize routine.  It is called by the generic
3383code under the fsunmount_me callback.
3384
3385All method loops finding the first encountered node with no children and
3386removing the node from the tree, thus returning allocated resources.  This
3387is done until all allocated nodes are returned.
3388
3389.. COMMENT: @page
3390
3391IMFS_utime()
3392~~~~~~~~~~~~
3393
3394**Corresponding Structure Element:**
3395
3396XXX
3397
3398**Arguments:**
3399
3400XXX
3401
3402**File:**
3403
3404XXX
3405
3406**Description:**
3407
3408XXX
3409
3410.. COMMENT: @page
3411
3412IMFS_eval_link()
3413~~~~~~~~~~~~~~~~
3414
3415**Corresponding Structure Element:**
3416
3417XXX
3418
3419**Arguments:**
3420
3421XXX
3422
3423**File:**
3424
3425XXX
3426
3427**Description:**
3428
3429XXX
3430
3431.. COMMENT: @page
3432
3433Regular File Handler Table Functions
3434------------------------------------
3435
3436Handler table functions are defined in a rtems_filesystem_file_handlers_r
3437structure. It defines functions that are specific to a node type in a given
3438filesystem. One table exists for each of the filesystem’s node types. The
3439structure definition appears below. It is followed by general developmental
3440information on each of the functions associated with regular files contained
3441in this function management structure.
3442.. code:: c
3443
3444    rtems_filesystem_file_handlers_r IMFS_memfile_handlers = {
3445    memfile_open,
3446    memfile_close,
3447    memfile_read,
3448    memfile_write,
3449    memfile_ioctl,
3450    memfile_lseek,
3451    IMFS_stat,
3452    IMFS_fchmod,
3453    memfile_ftruncate,
3454    NULL,                /* fpathconf \*/
3455    NULL,                /* fsync \*/
3456    IMFS_fdatasync,
3457    IMFS_fcntl
3458    };
3459
3460.. COMMENT: @page
3461
3462memfile_open() for Regular Files
3463~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3464
3465**Corresponding Structure Element:**
3466
3467memfile_open()
3468
3469**Arguments:**
3470
3471.. code:: c
3472
3473    rtems_libio_t   \*iop,
3474    const char      \*pathname,
3475    unsigned32       flag,
3476    unsigned32       mode
3477
3478**File:**
3479
3480memfile.c
3481
3482**Description:**
3483
3484Currently this function is a shell. No meaningful processing is performed and
3485a success code is always returned.
3486
3487.. COMMENT: @page
3488
3489memfile_close() for Regular Files
3490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3491
3492**Corresponding Structure Element:**
3493
3494memfile_close()
3495
3496**Arguments:**
3497
3498.. code:: c
3499
3500    rtems_libio_t     \*iop
3501
3502**File:**
3503
3504memfile.c
3505
3506**Description:**
3507
3508This routine is a dummy for regular files under the base filesystem. It
3509performs a capture of the IMFS_jnode_t pointer from the file control block
3510and then immediately returns a success status.
3511
3512.. COMMENT: @page
3513
3514memfile_read() for Regular Files
3515~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3516
3517**Corresponding Structure Element:**
3518
3519memfile_read()
3520
3521**Arguments:**
3522
3523.. code:: c
3524
3525    rtems_libio_t     \*iop,
3526    void              \*buffer,
3527    unsigned32         count
3528
3529**File:**
3530
3531memfile.c
3532
3533**Description:**
3534
3535This routine will determine the ``jnode`` that is associated with this file.
3536
3537It will then call IMFS_memfile_read() with the ``jnode``, file position index,
3538buffer and transfer count as arguments.
3539
3540IMFS_memfile_read() will do the following:
3541
3542- Verify that the ``jnode`` is associated with a memory file
3543
3544- Verify that the destination of the read is valid
3545
3546- Adjust the length of the read if it is too long
3547
3548- Acquire data from the memory blocks associated with the file
3549
3550- Update the access time for the data in the file
3551
3552.. COMMENT: @page
3553
3554memfile_write() for Regular Files
3555~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3556
3557**Corresponding Structure Element:**
3558
3559XXX
3560
3561**Arguments:**
3562
3563XXX
3564
3565**File:**
3566
3567XXX
3568
3569**Description:**
3570
3571XXX
3572
3573.. COMMENT: @page
3574
3575memfile_ioctl() for Regular Files
3576~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3577
3578**Corresponding Structure Element:**
3579
3580XXX
3581
3582**Arguments:**
3583
3584.. code:: c
3585
3586    rtems_libio_t     \*iop,
3587    unsigned32       command,
3588    void              \*buffer
3589
3590**File:**
3591
3592memfile.c
3593
3594**Description:**
3595
3596The current code is a placeholder for future development. The routine returns
3597a successful completion status.
3598
3599.. COMMENT: @page
3600
3601memfile_lseek() for Regular Files
3602~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3603
3604**Corresponding Structure Element:**
3605
3606Memfile_lseek()
3607
3608**Arguments:**
3609
3610.. code:: c
3611
3612    rtems_libio_t     \*iop,
3613    off_t              offset,
3614    int                whence
3615
3616**File:**
3617
3618memfile.c
3619
3620**Description:**
3621
3622This routine make sure that the memory based file is sufficiently large to
3623allow for the new file position index.
3624
3625The IMFS_memfile_extend() function is used to evaluate the current size of
3626the memory file and allocate additional memory blocks if required by the new
3627file position index. A success code is always returned from this routine.
3628
3629.. COMMENT: @page
3630
3631IMFS_stat() for Regular Files
3632~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3633
3634**Corresponding Structure Element:**
3635
3636IMFS_stat()
3637
3638**Arguments:**
3639
3640.. code:: c
3641
3642    rtems_filesystem_location_info_t   \*loc,
3643    struct stat                        \*buf
3644
3645**File:**
3646
3647imfs_stat.c
3648
3649**Description:**
3650
3651This routine actually performs status processing for both devices and regular
3652files.
3653
3654The IMFS_jnode_t structure is referenced to determine the type of node under
3655the filesystem.
3656
3657If the node is associated with a device, node information is extracted and
3658transformed to set the st_dev element of the stat structure.
3659
3660If the node is a regular file, the size of the regular file is extracted from
3661the node.
3662
3663This routine rejects other node types.
3664
3665The following information is extracted from the node and placed in the stat
3666structure:
3667
3668- st_mode
3669
3670- st_nlink
3671
3672- st_ino
3673
3674- st_uid
3675
3676- st_gid
3677
3678- st_atime
3679
3680- st_mtime
3681
3682- st_ctime
3683
3684.. COMMENT: @page
3685
3686IMFS_fchmod() for Regular Files
3687~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3688
3689**Corresponding Structure Element:**
3690
3691IMFS_fchmod()
3692
3693**Arguments:**
3694
3695.. code:: c
3696
3697    rtems_libio_t     \*iop
3698    mode_t              mode
3699
3700**File:**
3701
3702imfs_fchmod.c
3703
3704**Description:**
3705
3706This routine will obtain the pointer to the IMFS_jnode_t structure from the
3707information currently in the file control block.
3708
3709Based on configuration the routine will acquire the user ID from a call to
3710getuid()  or from the IMFS_jnode_t structure.
3711
3712It then checks to see if we have the ownership rights to alter the mode of
3713the file.  If the caller does not, an error code is returned.
3714
3715An additional test is performed to verify that the caller is not trying to
3716alter the nature of the node. If the caller is attempting to alter more than
3717the permissions associated with user group and other, an error is returned.
3718
3719If all the preconditions are met, the user, group and other fields are set
3720based on the mode calling parameter.
3721
3722.. COMMENT: @page
3723
3724memfile_ftruncate() for Regular Files
3725~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3726
3727**Corresponding Structure Element:**
3728
3729XXX
3730
3731**Arguments:**
3732
3733XXX
3734
3735**File:**
3736
3737XXX
3738
3739**Description:**
3740
3741XXX
3742
3743No pathconf() for Regular Files
3744~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3745
3746**Corresponding Structure Element:**
3747
3748NULL
3749
3750**Arguments:**
3751
3752Not Implemented
3753
3754**File:**
3755
3756Not Implemented
3757
3758**Description:**
3759
3760Not Implemented
3761
3762.. COMMENT: @page
3763
3764No fsync() for Regular Files
3765~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3766
3767**Corresponding Structure Element:**
3768
3769XXX
3770
3771**Arguments:**
3772
3773XXX
3774
3775**File:**
3776
3777XXX
3778
3779**Description:**
3780
3781XXX
3782
3783.. COMMENT: @page
3784
3785IMFS_fdatasync() for Regular Files
3786~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3787
3788**Corresponding Structure Element:**
3789
3790XXX
3791
3792**Arguments:**
3793
3794XXX
3795
3796**File:**
3797
3798XXX
3799
3800**Description:**
3801
3802XXX
3803
3804.. COMMENT: @page
3805
3806Directory Handler Table Functions
3807---------------------------------
3808
3809Handler table functions are defined in a rtems_filesystem_file_handlers_r
3810structure. It defines functions that are specific to a node type in a given
3811filesystem. One table exists for each of the filesystem’s node types. The
3812structure definition appears below. It is followed by general developmental
3813information on each of the functions associated with directories contained in
3814this function management structure.
3815.. code:: c
3816
3817    rtems_filesystem_file_handlers_r IMFS_directory_handlers = {
3818    IMFS_dir_open,
3819    IMFS_dir_close,
3820    IMFS_dir_read,
3821    NULL,             /* write \*/
3822    NULL,             /* ioctl \*/
3823    IMFS_dir_lseek,
3824    IMFS_dir_fstat,
3825    IMFS_fchmod,
3826    NULL,             /* ftruncate \*/
3827    NULL,             /* fpathconf \*/
3828    NULL,             /* fsync \*/
3829    IMFS_fdatasync,
3830    IMFS_fcntl
3831    };
3832
3833.. COMMENT: @page
3834
3835IMFS_dir_open() for Directories
3836~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3837
3838**Corresponding Structure Element:**
3839
3840imfs_dir_open()
3841
3842**Arguments:**
3843
3844.. code:: c
3845
3846    rtems_libio_t  \*iop,
3847    const char     \*pathname,
3848    unsigned32      flag,
3849    unsigned32      mode
3850
3851**File:**
3852
3853imfs_directory.c
3854
3855**Description:**
3856
3857This routine will look into the file control block to find the ``jnode`` that
3858is associated with the directory.
3859
3860The routine will verify that the node is a directory. If its not a directory
3861an error code will be returned.
3862
3863If it is a directory, the offset in the file control block will be set to 0.
3864This allows us to start reading at the beginning of the directory.
3865
3866.. COMMENT: @page
3867
3868IMFS_dir_close() for Directories
3869~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3870
3871**Corresponding Structure Element:**
3872
3873imfs_dir_close()
3874
3875**Arguments:**
3876
3877.. code:: c
3878
3879    rtems_libio_t     \*iop
3880
3881**File:**
3882
3883imfs_directory.c
3884
3885**Description:**
3886
3887This routine is a dummy for directories under the base filesystem. It
3888immediately returns a success status.
3889
3890.. COMMENT: @page
3891
3892IMFS_dir_read() for Directories
3893~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3894
3895**Corresponding Structure Element:**
3896
3897imfs_dir_read
3898
3899**Arguments:**
3900
3901.. code:: c
3902
3903    rtems_libio_t  \*iop,
3904    void           \*buffer,
3905    unsigned32      count
3906
3907**File:**
3908
3909imfs_directory.c
3910
3911**Description:**
3912
3913This routine will read a fixed number of directory entries from the current
3914directory offset. The number of directory bytes read will be returned from
3915this routine.
3916
3917.. COMMENT: @page
3918
3919No write() for Directories
3920~~~~~~~~~~~~~~~~~~~~~~~~~~
3921
3922**Corresponding Structure Element:**
3923
3924XXX
3925
3926**Arguments:**
3927
3928XXX
3929
3930**File:**
3931
3932XXX
3933
3934**Description:**
3935
3936XXX
3937
3938.. COMMENT: @page
3939
3940No ioctl() for Directories
3941~~~~~~~~~~~~~~~~~~~~~~~~~~
3942
3943**Corresponding Structure Element:**
3944
3945ioctl
3946
3947**Arguments:**
3948
3949**File:**
3950
3951Not supported
3952
3953**Description:**
3954
3955XXX
3956
3957.. COMMENT: @page
3958
3959IMFS_dir_lseek() for Directories
3960~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3961
3962**Corresponding Structure Element:**
3963
3964imfs_dir_lseek()
3965
3966**Arguments:**
3967
3968.. code:: c
3969
3970    rtems_libio_t      \*iop,
3971    off_t               offset,
3972    int                 whence
3973
3974**File:**
3975
3976imfs_directory.c
3977
3978**Description:**
3979
3980This routine alters the offset in the file control block.
3981
3982No test is performed on the number of children under the current open
3983directory.  The imfs_dir_read() function protects against reads beyond the
3984current size to the directory by returning a 0 bytes transfered to the
3985calling programs whenever the file position index exceeds the last entry in
3986the open directory.
3987
3988.. COMMENT: @page
3989
3990IMFS_dir_fstat() for Directories
3991~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3992
3993**Corresponding Structure Element:**
3994
3995imfs_dir_fstat()
3996
3997**Arguments:**
3998
3999.. code:: c
4000
4001    rtems_filesystem_location_info_t   \*loc,
4002    struct stat                        \*buf
4003
4004**File:**
4005
4006imfs_directory.c
4007
4008**Description:**
4009
4010The node access information in the rtems_filesystem_location_info_t structure
4011is used to locate the appropriate IMFS_jnode_t structure. The following
4012information is taken from the IMFS_jnode_t structure and placed in the stat
4013structure:
4014
4015- st_ino
4016
4017- st_mode
4018
4019- st_nlink
4020
4021- st_uid
4022
4023- st_gid
4024
4025- st_atime
4026
4027- st_mtime
4028
4029- st_ctime
4030
4031The st_size field is obtained by running through the chain of directory
4032entries and summing the sizes of the dirent structures associated with each
4033of the children of the directory.
4034
4035.. COMMENT: @page
4036
4037IMFS_fchmod() for Directories
4038~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4039
4040**Corresponding Structure Element:**
4041
4042IMFS_fchmod()
4043
4044**Arguments:**
4045
4046.. code:: c
4047
4048    rtems_libio_t     \*iop
4049    mode_t             mode
4050
4051**File:**
4052
4053imfs_fchmod.c
4054
4055**Description:**
4056
4057This routine will obtain the pointer to the IMFS_jnode_t structure from the
4058information currently in the file control block.
4059
4060Based on configuration the routine will acquire the user ID from a call to
4061getuid()  or from the IMFS_jnode_t structure.
4062
4063It then checks to see if we have the ownership rights to alter the mode of
4064the file.  If the caller does not, an error code is returned.
4065
4066An additional test is performed to verify that the caller is not trying to
4067alter the nature of the node. If the caller is attempting to alter more than
4068the permissions associated with user group and other, an error is returned.
4069
4070If all the preconditions are met, the user, group and other fields are set
4071based on the mode calling parameter.
4072
4073.. COMMENT: @page
4074
4075No ftruncate() for Directories
4076~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4077
4078**Corresponding Structure Element:**
4079
4080XXX
4081
4082**Arguments:**
4083
4084XXX
4085
4086**File:**
4087
4088XXX
4089
4090**Description:**
4091
4092XXX
4093
4094.. COMMENT: @page
4095
4096No fpathconf() for Directories
4097~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4098
4099**Corresponding Structure Element:**
4100
4101fpathconf
4102
4103**Arguments:**
4104
4105Not Implemented
4106
4107**File:**
4108
4109Not Implemented
4110
4111**Description:**
4112
4113Not Implemented
4114
4115.. COMMENT: @page
4116
4117No fsync() for Directories
4118~~~~~~~~~~~~~~~~~~~~~~~~~~
4119
4120**Corresponding Structure Element:**
4121
4122XXX
4123
4124**Arguments:**
4125
4126XXX
4127
4128**File:**
4129
4130XXX
4131
4132**Description:**
4133
4134XXX
4135
4136.. COMMENT: @page
4137
4138IMFS_fdatasync() for Directories
4139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4140
4141**Corresponding Structure Element:**
4142
4143XXX
4144
4145**Arguments:**
4146
4147XXX
4148
4149**File:**
4150
4151XXX
4152
4153**Description:**
4154
4155XXX
4156
4157.. COMMENT: @page
4158
4159Device Handler Table Functions
4160------------------------------
4161
4162Handler table functions are defined in a rtems_filesystem_file_handlers_r
4163structure. It defines functions that are specific to a node type in a given
4164filesystem. One table exists for each of the filesystem’s node types. The
4165structure definition appears below. It is followed by general developmental
4166information on each of the functions associated with devices contained in
4167this function management structure.
4168.. code:: c
4169
4170    typedef struct {
4171    rtems_filesystem_open_t           open;
4172    rtems_filesystem_close_t          close;
4173    rtems_filesystem_read_t           read;
4174    rtems_filesystem_write_t          write;
4175    rtems_filesystem_ioctl_t          ioctl;
4176    rtems_filesystem_lseek_t          lseek;
4177    rtems_filesystem_fstat_t          fstat;
4178    rtems_filesystem_fchmod_t         fchmod;
4179    rtems_filesystem_ftruncate_t      ftruncate;
4180    rtems_filesystem_fpathconf_t      fpathconf;
4181    rtems_filesystem_fsync_t          fsync;
4182    rtems_filesystem_fdatasync_t      fdatasync;
4183    } rtems_filesystem_file_handlers_r;
4184
4185.. COMMENT: @page
4186
4187device_open() for Devices
4188~~~~~~~~~~~~~~~~~~~~~~~~~
4189
4190**Corresponding Structure Element:**
4191
4192device_open()
4193
4194**Arguments:**
4195
4196.. code:: c
4197
4198    rtems_libio_t     \*iop,
4199    const char        \*pathname,
4200    unsigned32         flag,
4201    unsigned32         mode
4202
4203**File:**
4204
4205deviceio.c
4206
4207**Description:**
4208
4209This routine will use the file control block to locate the node structure for
4210the device.
4211
4212It will extract the major and minor device numbers from the ``jnode``.
4213
4214The major and minor device numbers will be used to make a rtems_io_open()
4215function call to open the device driver. An argument list is sent to the
4216driver that contains the file control block, flags and mode information.
4217
4218.. COMMENT: @page
4219
4220device_close() for Devices
4221~~~~~~~~~~~~~~~~~~~~~~~~~~
4222
4223**Corresponding Structure Element:**
4224
4225device_close()
4226
4227**Arguments:**
4228
4229.. code:: c
4230
4231    rtems_libio_t     \*iop
4232
4233**File:**
4234
4235deviceio.c
4236
4237**Description:**
4238
4239This routine extracts the major and minor device driver numbers from the
4240IMFS_jnode_t that is referenced in the file control block.
4241
4242It also forms an argument list that contains the file control block.
4243
4244A rtems_io_close() function call is made to close the device specified by the
4245major and minor device numbers.
4246
4247.. COMMENT: @page
4248
4249device_read() for Devices
4250~~~~~~~~~~~~~~~~~~~~~~~~~
4251
4252**Corresponding Structure Element:**
4253
4254device_read()
4255
4256**Arguments:**
4257
4258.. code:: c
4259
4260    rtems_libio_t     \*iop,
4261    void              \*buffer,
4262    unsigned32         count
4263
4264**File:**
4265
4266deviceio.c
4267
4268**Description:**
4269
4270This routine will extract the major and minor numbers for the device from the -
4271jnode- associated with the file descriptor.
4272
4273A rtems_io_read() call will be made to the device driver associated with the file
4274descriptor. The major and minor device number will be sent as arguments as well
4275as an argument list consisting of:
4276
4277- file control block
4278
4279- file position index
4280
4281- buffer pointer where the data read is to be placed
4282
4283- count indicating the number of bytes that the program wishes to read
4284  from the device
4285
4286- flags from the file control block
4287
4288On return from the rtems_io_read() the number of bytes that were actually
4289read will be returned to the calling program.
4290
4291.. COMMENT: @page
4292
4293device_write() for Devices
4294~~~~~~~~~~~~~~~~~~~~~~~~~~
4295
4296**Corresponding Structure Element:**
4297
4298XXX
4299
4300**Arguments:**
4301
4302XXX
4303
4304**File:**
4305
4306XXX
4307
4308**Description:**
4309
4310XXX
4311
4312.. COMMENT: @page
4313
4314device_ioctl() for Devices
4315~~~~~~~~~~~~~~~~~~~~~~~~~~
4316
4317**Corresponding Structure Element:**
4318
4319ioctl
4320
4321**Arguments:**
4322
4323.. code:: c
4324
4325    rtems_libio_t     \*iop,
4326    unsigned32         command,
4327    void              \*buffer
4328
4329**File:**
4330
4331deviceio.c
4332
4333**Description:**
4334
4335This handler will obtain status information about a device.
4336
4337The form of status is device dependent.
4338
4339The rtems_io_control() function uses the major and minor number of the device
4340to obtain the status information.
4341
4342rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
4343contains the file control block, device specific command and a buffer pointer
4344to return the device status information.
4345
4346The device specific command should indicate the nature of the information
4347that is desired from the device.
4348
4349After the rtems_io_control() is processed, the buffer should contain the
4350requested device information.
4351
4352If the device information is not obtained properly a -1 will be returned to
4353the calling program, otherwise the ioctl_return value is returned.
4354
4355.. COMMENT: @page
4356
4357device_lseek() for Devices
4358~~~~~~~~~~~~~~~~~~~~~~~~~~
4359
4360**Corresponding Structure Element:**
4361
4362device_lseek()
4363
4364**Arguments:**
4365
4366.. code:: c
4367
4368    rtems_libio_t     \*iop,
4369    off_t              offset,
4370    int                whence
4371
4372**File:**
4373
4374deviceio.c
4375
4376**Description:**
4377
4378At the present time this is a placeholder function. It always returns a
4379successful status.
4380
4381.. COMMENT: @page
4382
4383IMFS_stat() for Devices
4384~~~~~~~~~~~~~~~~~~~~~~~
4385
4386**Corresponding Structure Element:**
4387
4388IMFS_stat()
4389
4390**Arguments:**
4391
4392.. code:: c
4393
4394    rtems_filesystem_location_info_t   \*loc,
4395    struct stat                        \*buf
4396
4397**File:**
4398
4399imfs_stat.c
4400
4401**Description:**
4402
4403This routine actually performs status processing for both devices and regular files.
4404
4405The IMFS_jnode_t structure is referenced to determine the type of node under the
4406filesystem.
4407
4408If the node is associated with a device, node information is extracted and
4409transformed to set the st_dev element of the stat structure.
4410
4411If the node is a regular file, the size of the regular file is extracted from the node.
4412
4413This routine rejects other node types.
4414
4415The following information is extracted from the node and placed in the stat
4416structure:
4417
4418- st_mode
4419
4420- st_nlink
4421
4422- st_ino
4423
4424- st_uid
4425
4426- st_gid
4427
4428- st_atime
4429
4430- st_mtime
4431
4432- st_ctime
4433
4434.. COMMENT: @page
4435
4436IMFS_fchmod() for Devices
4437~~~~~~~~~~~~~~~~~~~~~~~~~
4438
4439**Corresponding Structure Element:**
4440
4441IMFS_fchmod()
4442
4443**Arguments:**
4444
4445.. code:: c
4446
4447    rtems_libio_t     \*iop
4448    mode_t             mode
4449
4450**File:**
4451
4452imfs_fchmod.c
4453
4454**Description:**
4455
4456This routine will obtain the pointer to the IMFS_jnode_t structure from the
4457information currently in the file control block.
4458
4459Based on configuration the routine will acquire the user ID from a call to
4460getuid()  or from the IMFS_jnode_t structure.
4461
4462It then checks to see if we have the ownership rights to alter the mode of
4463the file.  If the caller does not, an error code is returned.
4464
4465An additional test is performed to verify that the caller is not trying to
4466alter the nature of the node. If the caller is attempting to alter more than
4467the permissions associated with user group and other, an error is returned.
4468
4469If all the preconditions are met, the user, group and other fields are set
4470based on the mode calling parameter.
4471
4472.. COMMENT: @page
4473
4474No ftruncate() for Devices
4475~~~~~~~~~~~~~~~~~~~~~~~~~~
4476
4477**Corresponding Structure Element:**
4478
4479XXX
4480
4481**Arguments:**
4482
4483XXX
4484
4485**File:**
4486
4487XXX
4488
4489**Description:**
4490
4491XXX
4492
4493.. COMMENT: @page
4494
4495No fpathconf() for Devices
4496~~~~~~~~~~~~~~~~~~~~~~~~~~
4497
4498**Corresponding Structure Element:**
4499
4500fpathconf
4501
4502**Arguments:**
4503
4504Not Implemented
4505
4506**File:**
4507
4508Not Implemented
4509
4510**Description:**
4511
4512Not Implemented
4513
4514.. COMMENT: @page
4515
4516No fsync() for Devices
4517~~~~~~~~~~~~~~~~~~~~~~
4518
4519**Corresponding Structure Element:**
4520
4521XXX
4522
4523**Arguments:**
4524
4525XXX
4526
4527**File:**
4528
4529XXX
4530
4531**Description:**
4532
4533XXX
4534
4535.. COMMENT: @page
4536
4537No fdatasync() for Devices
4538~~~~~~~~~~~~~~~~~~~~~~~~~~
4539
4540Not Implemented
4541
4542**Corresponding Structure Element:**
4543
4544XXX
4545
4546**Arguments:**
4547
4548XXX
4549
4550**File:**
4551
4552XXX
4553
4554**Description:**
4555
4556XXX
4557
4558.. COMMENT: COPYRIGHT (c) 1988-2002.
4559
4560.. COMMENT: On-Line Applications Research Corporation (OAR).
4561
4562.. COMMENT: All rights reserved.
4563
4564Miniature In-Memory Filesystem
4565##############################
4566
4567This chapter describes the Miniature In-Memory FileSystem (miniIMFS).
4568The miniIMFS is a reduced feature version of the IMFS designed to
4569provide minimal functionality and have a low memory footprint.
4570
4571This chapter should be written after the IMFS chapter is completed
4572and describe the implementation of the mini-IMFS.
4573
4574.. COMMENT: COPYRIGHT (c) 1988-2002.
4575
4576.. COMMENT: On-Line Applications Research Corporation (OAR).
4577
4578.. COMMENT: All rights reserved.
4579
4580Trivial FTP Client Filesystem
4581#############################
4582
4583This chapter describes the Trivial FTP (TFTP) Client Filesystem.
4584
4585This chapter should be written after the IMFS chapter is completed
4586and describe the implementation of the TFTP.
4587
4588Command and Variable Index
4589##########################
4590
4591There are currently no Command and Variable Index entries.
4592
4593.. COMMENT: @printindex fn
4594
4595Concept Index
4596#############
4597
4598There are currently no Concept Index entries.
4599
4600.. COMMENT: @printindex cp
Note: See TracBrowser for help on using the repository browser.