dosfslib.c

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

Directories may also be allocated a contiguous disk area.  A file descriptor
to the directory is used to call FIOCONTIG, just as for a regular file.
A directory should be empty (except for the "." and ".." entries) before it
has contiguous space allocated to it.  The root directory allocation may not
be changed.  Space allocated to a directory is not reclaimed until the
directory is deleted; directories may not be truncated using the FIOTRUNC
function.

When any file is opened, it is checked for contiguity.  If a file is
recognized as contiguous, more efficient techniques for locating specific
sections of the file are used, rather than following cluster chains in the
FAT as must be done for fragmented files.  This enhanced handling
of contiguous files takes place regardless of whether the space was actually
allocated using \%FIOCONTIG.

CHANGING, UNMOUNTING, AND SYNCHRONIZING DISKS
Copies of directory entries and the FAT for each volume are kept in
memory.  This greatly speeds up access to files, but it requires that
dosFsLib be notified when disks are changed (i.e., floppies are swapped).
Two different notification mechanisms are provided.
.SS "Unmounting Volumes"
The first, and preferred, method of announcing a disk change is for
dosFsVolUnmount() to be called prior to removal of the disk.  This call
flushes all modified data structures to disk, if possible (see the
description of disk synchronization below), and also marks any open file
descriptors as obsolete.  During the next I/O operation, the disk is
remounted.  The ioctl() call may also be used to initiate
dosFsVolUnmount(), by specifying the FIOUNMOUNT function code.  (Any open
file descriptor to the device may be used in the ioctl() call.)

There may be open files or directories on a dosFs volume when it is
unmounted.  If this is the case, those file descriptors will be marked
as obsolete.  Any attempts to use them for further I/O operations will
return an S_dosFsLib_FD_OBSOLETE error.  To free such file descriptors,
use the close() call, as usual.  This will successfully free the descriptor,
but will still return S_dosFsLib_FD_OBSOLETE.  File descriptors acquired
when opening the entire volume (raw mode) will not be marked as obsolete
during dosFsVolUnmount() and may still be used.

Interrupt handlers must not call dosFsVolUnmount() directly, because it is
possible for the dosFsVolUnmount() call to block while the device becomes
available.  The interrupt handler may instead give a semaphore which
readies a task to unmount the volume.  (Note that dosFsReadyChange() may
be called directly from interrupt handlers.)

When dosFsVolUnmount() is called, it attempts to write buffered data out
to the disk.  It is therefore inappropriate for situations where the disk
change notification does not occur until a new disk has been inserted.
(The old buffered data would be written to the new disk.)  In these
circumstances, dosFsReadyChange() should be used.

If dosFsVolUnmount() is called after the disk is physically removed (i.e.,
there is no disk in the drive), the data-flushing portion of its operation
will fail.  However, the file descriptors will still be marked as obsolete,
and the disk will be marked as requiring remounting.  An error will not
be returned by dosFsVolUnmount() in this situation.  To avoid lost data in
such a situation, the disk should be explicitly synchronized before it
is removed.

Do not attempt to use dosFsVolUnmount() with volumes mounted using usrFdConfig().
This routine does not return the DOS_VOL_CONFIG structure required by 
dosFsVolUnmount(). Instead use ioctl() with FIOUNMOUNT, which accesses the volume
information via the file descriptor.
.SS "Announcing Disk Changes with Ready-Change"
The second method of informing dosFsLib that a disk change is taking place
is via the "ready-change" mechanism.  A change in the disk's ready status
is interpreted by dosFsLib to indicate that the disk should be remounted
during the next I/O operation.

There are three ways to announce a ready-change.  First, the
dosFsReadyChange() routine may be called directly.  Second, the ioctl()
call may be used, with the FIODISKCHANGE function code.  Finally, the
device driver may set the "bd_readyChanged" field in the BLK_DEV structure
to TRUE.  This has the same effect as notifying dosFsLib directly.

The ready-change mechanism does not provide the ability to flush data
structures to the disk.  It merely marks the volume as needing
remounting.  As a result, buffered data (data written to files, directory
entries, or FAT changes) may be lost.  This may be avoided by
synchronizing the disk before asserting ready-change.  (The combination of
synchronizing and asserting ready-change provides all the functionality of
dosFsVolUnmount(), except for marking file descriptors as obsolete.)

Since it does not attempt to flush data or to perform other operations that
could cause a delay, ready-change may be used in interrupt handlers.
.SS "Disks with No Change Notification"
If it is not possible for dosFsVolUnmount() or dosFsReadyChange() to be
called each time the disk is changed, the device must be specially
identified when it is initialized with the file system.  One of the
parameters of dosFsDevInit() is the address of a DOS_VOL_CONFIG
structure, which specifies various configuration parameters.  
DOS_OPT_CHANGENOWARN must be set in the `dosvc_options' field of the
DOS_VOL_CONFIG structure, if the driver and/or
application is unable to issue a dosFsVolUnmount() call or assert a
ready-change when a disk is changed.

This configuration option results in a significant performance disadvantage,
because the disk configuration data must be regularly read in from the
physical disk, in case the disk has been changed.  In addition, setting
DOS_OPT_CHANGENOWARN also enables auto-sync mode (see below).

Note that for disk change notification, all that is required is that
dosFsVolUnmount() or dosFsReadyChange() be called each time the disk is
changed.  It is not necessary that either routine be called from the
device driver or an interrupt handler.  For example, if your application
provided a user interface through which an operator could enter a command
which would result in a dosFsVolUnmount() call before removing the disk,
that would be sufficient, and DOS_OPT_CHANGENOWARN should not be set.
It is important, however, that such a procedure be followed strictly.
.SS "Synchronizing Volumes"
A disk should be "synchronized" before is is unmounted.  To synchronize a
disk means to write out all buffered data (files, directories, and the FAT
table) that have been modified, so that the disk is "up-to-date."  It may
or may not be necessary to explicitly synchronize a disk, depending on
when (or if) the dosFsVolUnmount() call is issued.

When dosFsVolUnmount() is called, an attempt will be made to synchronize the
device before unmounting.  If the disk is still present and writable at the
time dosFsVolUnmount() is called, the synchronization will take place; there
is no need to independently synchronize the disk.

However, if dosFsVolUnmount() is called after a disk has been removed,
it is obviously too late to synchronize.  (In this situation, dosFsVolUnmount()
discards the buffered data.)  Therefore, a separate ioctl() call with
the FIOFLUSH or FIOSYNC function should be made before the disk is removed.  
(This could be done in response to an operator command.)
.SS "Auto-Sync Mode"
The dosFs file system provides a modified mode of behavior called "auto-sync."
This mode is enabled by setting DOS_OPT_AUTOSYNC in the `dosvc_options' field of
the DOS_VOL_CONFIG structure when calling dosFsDevInit().  When this
option is enabled, modified directory and FAT data is written to
the physical device as soon as these structures are altered.  (Normally,
such changes may not be written out until the involved file is closed.)
This results in a performance penalty, but it provides the highest level
of data security, since it minimizes the amount of time when directory
and FAT data on the disk are not up-to-date.

Auto-sync mode is automatically enabled if the volume does not have disk
change notification, i.e., if DOS_OPT_CHANGENOWARN is set in the `dosvc_options'
field of the DOS_VOL_CONFIG structure when dosFsDevInit() is
called.  It may also be desirable for applications where data integrity--
in case of a system crash--is a larger concern than simple disk I/O 
performance.

CHANGES IN VOLUME CONFIGURATION
Various disk configuration parameters are specified
when the dosFs device is first initialized using dosFsDevInit().  This
data is kept in the volume descriptor (DOS_VOL_DESC) for the device.
However, it is possible for a disk with different parameters than those
defined to be placed in a drive after the device has already been
initialized.  For such a disk to be usable, the configuration data
in the volume descriptor must be modified when a new disk is present.

When a disk is mounted, the boot sector information is read from the disk.
This data is used to update the configuration data in the volume descriptor.
Note that this will happen the first time the disk is accessed after the
volume has been unmounted (using dosFsVolUnmount()).

This automatic re-initialization of the configuration data has two
important implications:
.IP (1) 4
Since the values in the volume descriptor are reset when a new
volume is mounted, it is possible to omit the dosFs configuration data (by
specifying a NULL pointer instead of the address of a DOS_VOL_CONFIG
structure during dosFsDevInit()).  The first use of the volume must be with
a properly formatted and initialized disk.  (Attempting to initialize a
disk, using FIODISKINIT, before a valid disk has been mounted is 
fruitless.)
.IP (2)
The volume descriptor data is used when initializing a disk
(with FIODISKINIT).  The FIODISKINIT function initializes a disk with
the configuration of the most recently mounted disk, regardless of the
original specification during dosFsDevInit().  Therefore, it is recommended
that FIODISKINIT be used immediately after dosFsDevInit(), before any disk
has been mounted.  (The device should be opened in raw mode; the \%FIODISKINIT
function is then performed; and the device is then closed.)
.LP

IOCTL FUNCTIONS
The dosFs file system supports the following ioctl() functions.  The
functions listed are defined in the header ioLib.h.  Unless stated
otherwise, the file descriptor used for these functions may be any file
descriptor which is opened to a file or directory on the volume or to 
the volume itself.

.iP "FIODISKFORMAT" 16 3
Formats the entire disk with appropriate hardware track and sector marks.
No file system is initialized on the disk by this request.
Note that this is a driver-provided function:
.CS
    fd = open ("DEV1:", O_WRONLY);
    status = ioctl (fd, FIODISKFORMAT, 0);
.CE
.iP "FIODISKINIT"
Initializes a DOS file system on the disk volume.
This routine does not format the disk; formatting must be done by the driver.
The file descriptor should be obtained by opening the entire volume in raw mode:
.CS
    fd = open ("DEV1:", O_WRONLY);
    status = ioctl (fd, FIODISKINIT, 0);
.CE
.iP "FIODISKCHANGE"
Announces a media change.  It performs the same function as dosFsReadyChange().
This function may be called from interrupt level:
.CS
    status = ioctl (fd, FIODISKCHANGE, 0);
.CE
.iP "FIOUNMOUNT"
Unmounts a disk volume.  It performs the same function as dosFsVolUnmount().
This function must not be called from interrupt level:
.CS
    status = ioctl (fd, FIOUNMOUNT, 0);
.CE
.iP "FIOGETNAME"
Gets the file name of the file descriptor and copies it to the buffer <nameBuf>:
.CS
    status = ioctl (fd, FIOGETNAME, &nameBuf );
.CE
.iP "FIORENAME"
Renames the file or directory to the string <newname>:
.CS
    status = ioctl (fd, FIORENAME, "newname");
.CE
.iP "FIOSEEK"
Sets the current byte offset in the file to the position specified by
<newOffset>:
.CS
    status = ioctl (fd, FIOSEEK, newOffset);
.CE
.iP "FIOWHERE"
Returns the current byte position in the file.  This is the byte offset of
the next byte to be read or written.  It takes no additional argument:
.CS
    position = ioctl (fd, FIOWHERE, 0);
.CE
.iP "FIOFLUSH"
Flushes the file output buffer.  It guarantees that any output that has
been requested is actually written to the device.  If the specified file
descriptor was obtained by opening the entire volume (raw mode), this 
function will flush all buffered file buffers, directories, and the FAT 
table to the physical device:
.CS
    status = ioctl (fd, FIOFLUSH, 0);
.CE
.iP "FIOSYNC"
Performs the same function as FIOFLUSH, and additionally re-reads buffered
file data from the disk.  This allows file changes made via a different file
descriptor to be seen.
.iP "FIOTRUNC"
Truncates the specified file's length to <newLength> bytes.  Any disk
clusters which had been allocated to the file but are now unused are
returned, and the directory entry for the file is updated to reflect
the new length.  Only regular files may be truncated; attempts to use
FIOTRUNC on directories or the entire volume will return an error.
FIOTRUNC may only be used to make files shorter; attempting to specify
a <newLength> larger than the current size of the file produces an
error (setting errno to S_dosFsLib_INVALID_NUMBER_OF_BYTES).
.CS
    status = ioctl (fd, FIOTRUNC, newLength);
.CE
.iP "FIONREAD"
Copies to <unreadCount> the number of unread bytes in the file:
.CS
    status = ioctl (fd, FIONREAD, &unreadCount);
.CE
.iP "FIONFREE"
Copies to <freeCount> the amount of free space, in bytes, on the volume:
.CS
   status = ioctl (fd, FIONFREE, &freeCount);
.CE
.iP "FIOMKDIR"
Creates a new directory with the name specified as <dirName>:
.CS
    status = ioctl (fd, FIOMKDIR, "dirName");
.CE
.iP "FIORMDIR"
Removes the directory whose name is specified as <dirName>:
.CS
    status = ioctl (fd, FIORMDIR, "dirName");
.CE
.iP "FIOLABELGET"
Gets the volume label (located in root directory) and copies the string to
<labelBuffer>:
.CS
    status = ioctl (fd, FIOLABELGET, &labelBuffer);
.CE