dosfslib.c

vxworks源码源码解读是学习vxworks的最佳途径

Once dosFsDevInit() has been called, when dosFsLib receives a request
from the I/O system, it calls the device driver routines (whose addresses
were passed in the BLK_DEV structure) to access the device.

The dosFsMkfs() routine is an alternative to using dosFsDevInit().  The
dosFsMkfs() routine always initializes a new dosFs file system on the
disk; thus, it is unsuitable for disks containing data that should be
preserved.  Default configuration parameters are supplied by dosFsMkfs(),
since no DOS_VOL_CONFIG structure is used.

See "Network File System (NFS) Support", below, for additional NFS-related
parameters you can set before calling dosFsDevInit().

MULTIPLE LOGICAL DEVICES
The sector number passed to the driver's sector read and write routines is
an absolute number, starting from sector 0 at the beginning of the device.
If desired, the driver may add an offset from the beginning of the physical
device before the start of the logical device.  This can be done by
keeping an offset parameter in the driver device structure, and adding
the offset to the sector number passed by the file system's read and write
routines.

ACCESSING THE RAW DISK
As a special case in open() and creat() calls, the dosFs file system
recognizes a null filename as indicating access to the entire "raw" disk
rather than to an individual file on the disk.  (To open a device
in raw mode, specify only the device name -- no filename -- during the open()
or creat() call.)

Raw mode is the only means of accessing a disk that has no file system.
For example, to initialize a new file system on the disk,
first the raw disk is opened and the returned file descriptor is used
for an ioctl() call with FIODISKINIT.
Opening the disk in raw mode is also a common operation when doing other
ioctl() functions which do not involve a particular file
(e.g., FIONFREE, FIOLABELGET).

To read the root directory of a disk on which no file names are known,
specify the device name when calling opendir().  Subsequent readdir()
calls will return the names of files and subdirectories in the
root directory.

Data written to the disk in raw mode uses the same area on the disk as
normal dosFs files and subdirectories.  Raw I/O does not use the disk
sectors used for the boot sector, root directory, or File Allocation
Table (FAT).  For more information about raw disk I/O using the entire
disk, see the manual entry for rawFsLib.

DEVICE AND PATH NAMES
On true MS-DOS machines, disk device names are typically of the form "A:",
that is, a single letter designator followed by a colon.  Such names may be
used with the VxWorks dosFs file system.  However, it is possible (and
desirable) to use longer, more mnemonic device names, such as "DOS1:",
or "/floppy0/".  The name is specified during the dosFsDevInit() or dosFsMkfs()
call.

The pathnames used to specify dosFs files and directories may use either
forward slashes ("/") or backslashes ("\e") as separators.  These may be
freely mixed.  The choice of forward slashes or backslashes has absolutely
no effect on the directory data written to the disk.  (Note, however, that
forward slashes are not allowed within VxWorks dosFs filenames, although
they are normally legal for pure MS-DOS implementations.)

When using the VxWorks shell to make calls specifying dosFs pathnames,
you must allow for the C-style interpretation which is performed.  In
cases where the file name is enclosed in quote marks, any backslashes
must be "escaped" by a second, preceding backslash.  For example:
.CS
    -> copy ("DOS1:\e\esubdir\e\efile1", "file2")
.CE
However, shell commands which use pathnames without enclosing quotes do
not require the second backslash.  For example:
.CS
    -> copy < DOS1:\esubdir\efile1
.CE
Forward slashes do not present these inconsistencies, and may therefore be
preferable for use within the shell.

The leading slash of a dosFs pathname following the device name is
optional.  For example, both "DOS1:newfile.new" and "DOS1:/newfile.new"
refer to the same file.

USING EXTENDED FILE NAMES
The MS-DOS standard only allows for file names which fit the restrictions
of eight upper-case characters optionally followed by a three-character
extension.  This may not be convenient if you are transferring files to or
from a remote system, or if your application requires particular file
naming conventions.

To provide additional flexibility, the dosFs file system provides an
option to use longer, less restricted file names.  When this option is
enabled, file names may consist of any sequence of up to 40 ASCII
characters.  No case conversion is performed and no characters have any
special significance.

.RS 4 4
\&NOTE:  Because special directory entries are used on the disk, disks 
which use the extended names are \f2not\fP compatible with true MS-DOS systems 
and cannot be read on MS-DOS machines.  Disks which use the extended name 
option must be initialized by the VxWorks dosFs file system (using 
FIODISKINIT); disks which have been initialized (software-formatted) on 
MS-DOS systems cannot be used.
.RE

To enable the extended file names, set the DOS_OPT_LONGNAMES bit in the 
`dosvc_options' field in the DOS_VOL_CONFIG structure when calling 
dosFsDevInit().  (The dosFsMkfs() routine may also be used to enable extended
file names; however, the DOS_OPT_LONGNAMES option must already have been 
specified in a previous call to dosFsMkfsOptionsSet().)

NETWORK FILE SYSTEM (NFS) SUPPORT
To enable the export of a file system, the DOS_OPT_EXPORT option must be
set when initializing the device via dosFsDevInit() or dosFsMkfs().
This option may also be made the default for use with disks when no
explicit configuration is given.  See the manual entry for 
dosFsDevInitOptionsSet().

If the remote client that will be mounting the dosFs volume is a
PC-based client, you may also need to specify the DOS_OPT_LOWERCASE
option.  This option causes filenames to be mapped to lowercase
(when not using the DOS_OPT_LONGNAMES option).  This lowercase mapping
is expected by many PC-based NFS implementations.

When the DOS_OPT_EXPORT option is enabled, the VxWorks NFS file system 
uses the reserved fields of a dosFs directory entry to store information 
needed to uniquely identify a dosFs file.

Every time a file is created in a directory, the directory timestamp
is incremented.  This is necessary to avoid cache inconsistencies in
clients, because some UNIX clients use the directory timestamp to
determine if their local cache needs to be updated.

You can also specify integers for a user ID, group ID, and file access
permissions byte when you initialize a dosFs file system for NFS
export.  The values you specify will apply to all files in the file
system.

Set `dosFsUserId' to specify the numeric user ID.  The default is 65534.

Set `dosFsGroupId' to specify the numeric group ID.  The default is 65534.

Set `dosFsFileMode' to specify the numeric file access mode.  The default is 777.

READING DIRECTORY ENTRIES
Directories on VxWorks dosFs volumes may be searched using the opendir(),
readdir(), rewinddir(), and closedir() routines.  These calls allow the
names of files and subdirectories to be determined.

To obtain more detailed information about a specific file, use the fstat()
or stat() routine.  Along with standard file information, the structure
used by these routines also returns the file attribute byte from a dosFs
directory entry.

For more information, see the manual entry for dirLib.

FILE DATE AND TIME
Directory entries on dosFs volumes contain a time and date for each file
or subdirectory.  This time is set when the file is created, and it is
updated when a file is closed, if it has been modified.  Directory time
and date fields are set only when the directory is created, not when it is
modified.

The dosFs file system library maintains the date and time in an internal
structure.  While there is currently no mechanism for automatically advancing
the date or time, two different methods for setting the date and time are
provided.

The first method involves using two routines, dosFsDateSet() and
dosFsTimeSet(), which are provided to set the current date and time.

Examples of setting the date and time would be:
.CS
    dosFsDateSet (1990, 12, 25);  /@ set date to Dec-25-1990 @/
    dosFsTimeSet (14, 30, 22);    /@ set time to 14:30:22    @/
.CE

The second method requires a user-provided hook routine.  If a time and
date hook routine is installed using dosFsDateTimeInstall(), the routine
will be called whenever dosFsLib requires the current date.  This facility
is provided to take advantage of hardware time-of-day clocks which may
be read to obtain the current time.

The date/time hook routine should be defined as follows:
.CS
    void dateTimeHook
	(
	DOS_DATE_TIME	*pDateTime   /@ ptr to dosFs date/time struct @/
	)
.CE
On entry to the hook routine, the DOS_DATE_TIME structure will contain
the last time and date which was set in dosFsLib.  The structure should
then be filled by the hook routine with the correct values for the current
time and date.  Unchanged fields in the structure will retain their previous
values.

The MS-DOS specification only provides for 2-second granularity for file
time stamps.  If the number of seconds in the time specified during
dosFsTimeSet() or the date/time hook routine is odd, it will be rounded down
to the next even number.

The date and time used by dosFsLib is initially Jan-01-1980, 00:00:00.

FILE ATTRIBUTES
Directory entries on dosFs volumes contain an attribute byte consisting of
bit-flags which specify various characteristics of the entry.  The
attributes which are identified are:  read-only file, hidden file, system
file, volume label, directory, and archive.  The VxWorks symbols for these
attribute bit-flags are:

    DOS_ATTR_RDONLY
    DOS_ATTR_HIDDEN
    DOS_ATTR_SYSTEM
    DOS_ATTR_VOL_LABEL
    DOS_ATTR_DIRECTORY
    DOS_ATTR_ARCHIVE

All the flags in the attribute byte, except the directory and volume label
flags, may be set or cleared using the ioctl() FIOATTRIBSET function.  This
function is called after opening the specific file whose attributes are to
be changed.  The attribute byte value specified in the FIOATTRIBSET call is
copied directly.  To preserve existing flag settings, the current attributes
should first be determined via fstat(), and the appropriate
flag(s) changed using bitwise AND or OR operations.  For example, to make
a file read-only, while leaving other attributes intact:
.CS
    struct stat fileStat;

    fd = open ("file", O_RDONLY, 0);     /@ open file          @/
    fstat (fd, &fileStat);               /@ get file status    @/

    ioctl (fd, FIOATTRIBSET, (fileStat.st_attrib | DOS_ATTR_RDONLY));
                                         /@ set read-only flag @/
    close (fd);                          /@ close file         @/
.CE

CONTIGUOUS FILE SUPPORT
The VxWorks dosFs file system provides efficient handling of contiguous
files, meaning files which are made up of a consecutive series of disk sectors.
This support includes both the ability to allocate contiguous space to a file
(or directory) and optimized access to such a file when it is used.

To allocate a contiguous area to a file, the file is first created in the
normal fashion, using open() or creat().  The file descriptor returned
during the creation of the file is then used to make an ioctl() call,
specifying the FIOCONTIG function.  The other parameter to the FIOCONTIG
function is the size of the requested contiguous area in bytes.  It
is also possible to request that the largest contiguous free area on
the disk be obtained.  In this case, the special value CONTIG_MAX (-1) 
is used instead of an actual size.

The FAT is searched for a suitable section of the disk, and if found, 
it is assigned to the file.  (If there is no contiguous area on the volume 
large enough to satisfy the request, an S_dosFsLib_NO_CONTIG_SPACE error is 
returned.)  The file may then be closed or used for further I/O operations.  
For example, the following will create a file and allocate 0x10000 
contiguous bytes:
.CS
    fd = creat ("file", O_RDWR, 0);             /@ open file             @/
    status = ioctl (fd, FIOCONTIG, 0x10000);    /@ get contiguous area   @/
    if (status != OK)
       ...                                      /@ do error handling     @/
    close (fd);                                 /@ close file            @/
.CE

In contrast, the following example will create a file and allocate the
largest contiguous area on the disk to it:
.ne7
.CS
    fd = creat ("file", O_RDWR, 0);             /@ open file             @/
    status = ioctl (fd, FIOCONTIG, CONTIG_MAX); /@ get contiguous area   @/
    if (status != OK)
       ...                                      /@ do error handling     @/
    close (fd);                                 /@ close file            @/
.CE
It is important that the file descriptor used for the ioctl() call be the
only descriptor open to the file.  Furthermore, since a file may be assigned
a different area of the disk than was originally allocated, the 
FIOCONTIG operation should take place before any data is written to the file.

To determine the actual amount of contiguous space obtained when CONTIG_MAX
is specified as the size, use fstat() to examine the file
size.  For more information, see dirLib.

Space which has been allocated to a file may later be freed by using
ioctl() with the FIOTRUNC function.