dosfslib.html

来自「vxworks相关论文」· HTML 代码 · 共 1,270 行 · 第 1/5 页

PC-based client, you may also need to specify the <b>DOS_OPT_LOWERCASE</b>
option.  This option causes filenames to be mapped to lowercase
(when not using the <b>DOS_OPT_LONGNAMES</b> option).  This lowercase mapping
is expected by many PC-based NFS implementations.
<p>
When the <b>DOS_OPT_EXPORT</b> 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.
<p>
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.
<p>
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.
<p>
Set <b>dosFsUserId</b> to specify the numeric user ID.  The default is 65534.
<p>
Set <b>dosFsGroupId</b> to specify the numeric group ID.  The default is 65534.
<p>
Set <b>dosFsFileMode</b> to specify the numeric file access mode.  The default is 777.
<p>
</blockquote><h4>READING DIRECTORY ENTRIES</h4><blockquote><p>
Directories on VxWorks dosFs volumes may be searched using the <b><i><a href="./dirLib.html#opendir">opendir</a></i>(&nbsp;)</b>,
<b><i><a href="./dirLib.html#readdir">readdir</a></i>(&nbsp;)</b>, <b><i><a href="./dirLib.html#rewinddir">rewinddir</a></i>(&nbsp;)</b>, and <b><i><a href="./dirLib.html#closedir">closedir</a></i>(&nbsp;)</b> routines.  These calls allow the
names of files and subdirectories to be determined.
<p>
To obtain more detailed information about a specific file, use the <b><i><a href="./dirLib.html#fstat">fstat</a></i>(&nbsp;)</b>
or <b><i><a href="./dirLib.html#stat">stat</a></i>(&nbsp;)</b> routine.  Along with standard file information, the structure
used by these routines also returns the file attribute byte from a dosFs
directory entry.
<p>
For more information, see the manual entry for dirLib.
<p>
</blockquote><h4>FILE DATE AND TIME</h4><blockquote><p>
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.
<p>
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.
<p>
The first method involves using two routines, <b><i><a href="./dosFsLib.html#dosFsDateSet">dosFsDateSet</a></i>(&nbsp;)</b> and
<b><i><a href="./dosFsLib.html#dosFsTimeSet">dosFsTimeSet</a></i>(&nbsp;)</b>, which are provided to set the current date and time.
<p>
Examples of setting the date and time would be:
<pre>    dosFsDateSet (1990, 12, 25);  /* set date to Dec-25-1990 */
    dosFsTimeSet (14, 30, 22);    /* set time to 14:30:22    */
</pre>

The second method requires a user-provided hook routine.  If a time and
date hook routine is installed using <b><i><a href="./dosFsLib.html#dosFsDateTimeInstall">dosFsDateTimeInstall</a></i>(&nbsp;)</b>, the routine
will be called whenever <b><a href="./dosFsLib.html#top">dosFsLib</a></b> 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.
<p>
The date/time hook routine should be defined as follows:
<pre>    void dateTimeHook
        (
        DOS_DATE_TIME   *pDateTime   /* ptr to dosFs date/time struct */
        )
</pre>
On entry to the hook routine, the <b>DOS_DATE_TIME</b> 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.
<p>
The MS-DOS specification only provides for 2-second granularity for file
time stamps.  If the number of seconds in the time specified during
<b><i><a href="./dosFsLib.html#dosFsTimeSet">dosFsTimeSet</a></i>(&nbsp;)</b> or the date/time hook routine is odd, it will be rounded down
to the next even number.
<p>
The date and time used by <b><a href="./dosFsLib.html#top">dosFsLib</a></b> is initially Jan-01-1980, 00:00:00.
<p>
</blockquote><h4>FILE ATTRIBUTES</h4><blockquote><p>
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:
<p>
&nbsp;&nbsp;&nbsp;&nbsp;<b>DOS_ATTR_RDONLY</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>DOS_ATTR_HIDDEN</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>DOS_ATTR_SYSTEM</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>DOS_ATTR_VOL_LABEL</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>DOS_ATTR_DIRECTORY</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>DOS_ATTR_ARCHIVE</b>
<p>
All the flags in the attribute byte, except the directory and volume label
flags, may be set or cleared using the <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> 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 <b><i><a href="./dirLib.html#fstat">fstat</a></i>(&nbsp;)</b>, 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:
<pre>    struct stat fileStat;

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

    ioctl (fd, FIOATTRIBSET, (fileStat.st_attrib | DOS_ATTR_RDONLY));
                                         /* set read-only flag */
    close (fd);                          /* close file         */
</pre>

</blockquote><h4>CONTIGUOUS FILE SUPPORT</h4><blockquote><p>
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.
<p>
To allocate a contiguous area to a file, the file is first created in the
normal fashion, using <b><i><a href="./ioLib.html#open">open</a></i>(&nbsp;)</b> or <b><i><a href="./ioLib.html#creat">creat</a></i>(&nbsp;)</b>.  The file descriptor returned
during the creation of the file is then used to make an <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> 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 <b>CONTIG_MAX</b> (-1) 
is used instead of an actual size.
<p>
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:
<pre>    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            */
</pre>

In contrast, the following example will create a file and allocate the
largest contiguous area on the disk to it:
<p>
<pre>    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            */
</pre>
It is important that the file descriptor used for the <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> 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.
<p>
To determine the actual amount of contiguous space obtained when <b>CONTIG_MAX</b>
is specified as the size, use <b><i><a href="./dirLib.html#fstat">fstat</a></i>(&nbsp;)</b> to examine the file
size.  For more information, see dirLib.
<p>
Space which has been allocated to a file may later be freed by using
<b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> with the FIOTRUNC function.
<p>
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.
<p>
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.
<p>
</blockquote><h4>CHANGING, UNMOUNTING, AND SYNCHRONIZING DISKS</h4><blockquote><p>
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
<b><a href="./dosFsLib.html#top">dosFsLib</a></b> be notified when disks are changed (i.e., floppies are swapped).
Two different notification mechanisms are provided.
</blockQuote><h4>Unmounting Volumes</h4><blockQuote>
The first, and preferred, method of announcing a disk change is for
<b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> 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 <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> call may also be used to initiate
<b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b>, by specifying the FIOUNMOUNT function code.  (Any open
file descriptor to the device may be used in the <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> call.)
<p>
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 <b><i><a href="./ioLib.html#close">close</a></i>(&nbsp;)</b> 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 <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> and may still be used.
<p>
Interrupt handlers must not call <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> directly, because it is
possible for the <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> 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 <b><i><a href="./dosFsLib.html#dosFsReadyChange">dosFsReadyChange</a></i>(&nbsp;)</b> may
be called directly from interrupt handlers.)
<p>
When <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> 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, <b><i><a href="./dosFsLib.html#dosFsReadyChange">dosFsReadyChange</a></i>(&nbsp;)</b> should be used.
<p>
If <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> 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 <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> in this situation.  To avoid lost data in
such a situation, the disk should be explicitly synchronized before it
is removed.
<p>
Do not attempt to use <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> with volumes mounted using <b><i><a href="./usrFd.html#usrFdConfig">usrFdConfig</a></i>(&nbsp;)</b>.
This routine does not return the <b>DOS_VOL_CONFIG</b> structure required by 
<b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b>. Instead use <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b> with FIOUNMOUNT, which accesses the volume
information via the file descriptor.
</blockQuote><h4>Announcing Disk Changes with Ready-Change</h4><blockQuote>
The second method of informing <b><a href="./dosFsLib.html#top">dosFsLib</a></b> that a disk change is taking place
is via the "ready-change" mechanism.  A change in the disk's ready status
is interpreted by <b><a href="./dosFsLib.html#top">dosFsLib</a></b> to indicate that the disk should be remounted
during the next I/O operation.
<p>
There are three ways to announce a ready-change.  First, the
<b><i><a href="./dosFsLib.html#dosFsReadyChange">dosFsReadyChange</a></i>(&nbsp;)</b> routine may be called directly.  Second, the <b><i><a href="./ioLib.html#ioctl">ioctl</a></i>(&nbsp;)</b>
call may be used, with the FIODISKCHANGE function code.  Finally, the
device driver may set the "bd_readyChanged" field in the <b>BLK_DEV</b> structure
to TRUE.  This has the same effect as notifying <b><a href="./dosFsLib.html#top">dosFsLib</a></b> directly.
<p>
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
<b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b>, except for marking file descriptors as obsolete.)
<p>
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.
</blockQuote><h4>Disks with No Change Notification</h4><blockQuote>
If it is not possible for <b><i><a href="./dosFsLib.html#dosFsVolUnmount">dosFsVolUnmount</a></i>(&nbsp;)</b> or <b><i><a href="./dosFsLib.html#dosFsReadyChange">dosFsReadyChange</a></i>(&nbsp;)</b> 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 <b><i><a href="./dosFsLib.html#dosFsDevInit">dosFsDevInit</a></i>(&nbsp;)</b> is the address of a <b>DOS_VOL_CONFIG</b>
structure, which specifies various configuration parameters.