dosfslib.html

Vxworks API操作系统和驱动程序设计API。压缩的HTML文件

It is also possible to request that the largest contiguous free area on
the disk be obtained.  In this case, the size value <b>CONTIG_MAX</b> (-1) 
is used instead of an actual size.  These <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> codes
are not supported for directories.
The volume is searched for a contiguous area of free space, which 
is assigned to the file. If a segment of contiguous free space
large enough for the request was not found,
ERROR is returned, with <i>errno</i> set to  <b>S_dosFsLib_NO_CONTIG_SPACE</b>.
<p>
When contiguous space is allocated to a file, the file remains empty,
while the newly allocated space has not been initialized.
The data should be then written to the file, and eventually, when
all data has been written, the file is closed.
When file is closed, its space is truncated to reflect the amount
of data actually written to the file.
This file may then be again opened and used for further 
I/O operations <b><a href="./ioLib.html#read">read</a>(&nbsp;)</b> or <b><a href="./ioLib.html#write">write</a>(&nbsp;)</b>, 
but it can not be guaranteed that appended data will be contiguous
to the initially written data segment.
<p>
For example, the following will create a file and allocate 85 Mbytes of 
contiguous space:
<pre>    fd = creat ("file", O_RDWR, 0);             /* open file             */
    status = ioctl (fd, FIOCONTIG, 85*0x100000);/* 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>

<dl>
<dt>
NOTE
<dd>
the FIOCONTIG operation should take place right after the file has been
created, before any data is written to the file.
Directories may not be allocated a contiguous disk area.
</dl>
To determine the actual amount of contiguous space obtained when <b>CONTIG_MAX</b>
is specified as the size, use <b><a href="./dirLib.html#fstat">fstat</a>(&nbsp;)</b> to examine the number of blocks
and block size for the file.
<p>
When any file is opened, it may be checked for contiguity.
Use the extended flag <b>DOS_O_CONTIG_CHK</b> when calling <b><a href="./ioLib.html#open">open</a>(&nbsp;)</b> to access an
existing file which may have been allocated contiguous space.
If a file is detected as contiguous, all subsequent operations on the
file will not require access to the File Allocation Table, thus
eliminating any disk Seek operations.
The down side however is that if this option is used, <b><a href="./ioLib.html#open">open</a>(&nbsp;)</b> will take
an amount of time which is linearly proportional of the file size.
<p>
</blockquote><h4>CHANGING, UNMOUNTING, AND SYNCHRONIZING DISKS</h4><blockquote><p>
Buffering of disk data in RAM, synchronization of these
buffers with the disk and detection of removable disk replacement are
all handled by the disk cache. See reference manual on dcacheCbio
for more details.
<p>
If a disk is physically removed, the disk cache will cause <b><a href="./dosFsLib.html#top">dosFsLib</a></b> to
<i>unmount </i>
the volume, which will mark all currently open file descriptors as
<i>obsolete. </i>
<p>
If a new disk is inserted, it will be automatically
<i>mounted </i>
on the next call to <b><a href="./ioLib.html#open">open</a>(&nbsp;)</b> or <b><a href="./ioLib.html#creat">creat</a>(&nbsp;)</b>.
<p>
</blockquote><h4>IOCTL FUNCTIONS</h4><blockquote><p>
The dosFs file system supports the following <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> functions.  The
functions listed are defined in the header <b>ioLib.h</b>.  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.
There are some <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> commands, that expect a 32-bit integer result
(FIONFREE, FIOWHERE, etc.).
However, disks and files with are grater than 4GB are supported.
In order to solve this problem, new <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> functions have been added
to support 64-bit integer results.
They have the same name as basic functions, but with suffix 
<i>64, </i>
namely: FIONFREE64, FIOWHERE64 and so on. These commands
expect a pointer to a 64-bit integer, i.e.:
<pre>long long *arg ;
</pre>
as the 3rd argument to the <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> function.
If a value which is requested with a 32-bit <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> command is
too large to be represented in the 32-bit variable, <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> will return
ERROR, and <i>errno</i> will be set to <b>S_dosFsLib_32BIT_OVERFLOW</b>.
<p>
<dl>
<dt>
FIODISKINIT
<dd>
Reinitializes a DOS file system on the disk volume.
This function calls <b><a href="./dosFsFmtLib.html#dosFsVolFormat">dosFsVolFormat</a>(&nbsp;)</b> to format the volume,
so <b><a href="./dosFsFmtLib.html#top">dosFsFmtLib</a></b> must be installed for this to work.
Third argument of <b><a href="./ioLib.html#ioctl">ioctl</a>(&nbsp;)</b> is passed as argument <i>opt</i> to
<b><a href="./dosFsFmtLib.html#dosFsVolFormat">dosFsVolFormat</a>(&nbsp;)</b> routine.
This routine does not perform a low level format,
the physical media is expected to be already formatted.
If DOS file system device has not been created yet for a particular device,
only direct call to <b><a href="./dosFsFmtLib.html#dosFsVolFormat">dosFsVolFormat</a>(&nbsp;)</b> can be used.
<pre>    fd = open ("DEV1:", O_WRONLY);
    status = ioctl (fd, FIODISKINIT, DOS_OPT_BLANK);
</pre>

<dt>
FIODISKCHANGE
<dd>
Announces a media change. No buffers flushing is performed.
This function may be called from interrupt level:
<pre>    status = ioctl (fd, FIODISKCHANGE, 0);
</pre>

<dt>
FIOUNMOUNT
<dd>
Unmounts a disk volume.  It performs the same function as <b>dosFsVolUnmount(&nbsp;)</b>.
This function must not be called from interrupt level:
<pre>    status = ioctl (fd, FIOUNMOUNT, 0);
</pre>

<dt>
FIOGETNAME
<dd>
Gets the file name of the file descriptor and copies it to the buffer <i>nameBuf</i>.
Note that <i>nameBuf</i> must be large enough to contain the largest possible
path name, which requires at least 256 bytes.
<pre>    status = ioctl (fd, FIOGETNAME, &amp;nameBuf );
</pre>

<dt>
FIORENAME
<dd>
Renames the file or directory to the string <i>newname</i>:
<pre>    fd = open( "oldname", O_RDONLY, 0 );
    status = ioctl (fd, FIORENAME, "newname");
</pre>

<dt>
FIOMOVE
<dd>
Moves the file or directory to the string <i>newname</i>:
<pre>    fd = open( "oldname", O_RDONLY, 0 );
    status = ioctl (fd, FIOMOVE, "newname");
</pre>

<dt>
FIOSEEK
<dd>
Sets the current byte offset in the file to the position specified by
<i>newOffset</i>. This function supports offsets in 32-bit value range.
Use FIOSEEK64 for larger position values:
<pre>    status = ioctl (fd, FIOSEEK, newOffset);
</pre>

<dt>
FIOSEEK64
<dd>
Sets the current byte offset in the file to the position specified by
<i>newOffset</i>. This function supports offsets in 64-bit value range:
<pre>    long long   newOffset;
    status = ioctl (fd, FIOSEEK64, (int) &amp; newOffset);
</pre>

<dt>
FIOWHERE
<dd>
Returns the current byte position in the file.  This is the
byte offset of
the next byte to be read or written.  This function returns a 32-bit value.
It takes no additional argument:
<pre>    position = ioctl (fd, FIOWHERE, 0);
</pre>

<dt>
FIOWHERE64
<dd>
Returns the current byte position in the file.  This is the
byte offset of
the next byte to be read or written.  This function returns a 64-bit
value in <i>position</i>:
<pre>    long long   position;
    status = ioctl (fd, FIOWHERE64, (int) &amp; position);
</pre>

<dt>
FIOFLUSH
<dd>
Flushes disk cache buffers.  It guarantees that any output that has
been requested is actually written to the device:
<pre>    status = ioctl (fd, FIOFLUSH, 0);
</pre>

<dt>
FIOSYNC
<dd>
Updates the FAT copy for the passed file descriptor, then      
flushes and invalidates the CBIO cache buffers for the file    
descriptor's volume.  FIOSYNC ensures that any outstanding     
output requests for the passed file descriptor are written     
to the device and a subsequent I/O operation will fetch data   
directly from the physical medium.  To safely sync a volume    
for shutdown, all open file descriptor's should at the least   
be FIOSYNC'd by the application.  Better, all open FD's should 
be closed by the application and the volume should be unmounted
via FIOUNMOUNT.
<pre>    status = ioctl (fd, FIOSYNC, 0);
</pre>

<dt>
FIOTRUNC
<dd>
Truncates the specified file's length to <i>newLength</i> bytes.  Any disk
clusters which had been allocated to the file but are now unused are
deallocated, 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 will return an error.
FIOTRUNC may only be used to make files shorter; attempting to specify
a <i>newLength</i> larger than the current size of the file produces an
error (setting errno to <b>S_dosFsLib_INVALID_NUMBER_OF_BYTES</b>).
<pre>    status = ioctl (fd, FIOTRUNC, newLength);
</pre>

<dt>
FIOTRUNC64
<dd>
Similar to FIOTRUNC, but can be used for files lager, than 4GB.
<pre>    long long newLength = .....;
    status = ioctl (fd, FIOTRUNC, (int) &amp; newLength);
</pre>

<dt>
FIONREAD
<dd>
Copies to <i>unreadCount</i> the number of unread bytes in the file:
<pre>    unsigned long unreadCount;
    status = ioctl (fd, FIONREAD, &amp;unreadCount);
</pre>
<dt>
FIONREAD64
<dd>
Copies to <i>unreadCount</i> the number of unread bytes in the file.
This function returns a 64-bit integer value:
<pre>    long long unreadCount;
    status = ioctl (fd, FIONREAD64, &amp;unreadCount);
</pre>
<dt>
FIONFREE
<dd>
Copies to <i>freeCount</i> the amount of free space, in bytes, on the volume:
<pre>   unsigned long freeCount;
   status = ioctl (fd, FIONFREE, &amp;freeCount);
</pre>
<dt>
FIONFREE64
<dd>
Copies to <i>freeCount</i> the amount of free space, in bytes, on the volume.
This function can return value in 64-bit range:
<pre>   long long freeCount;
   status = ioctl (fd, FIONFREE64, &amp;freeCount);
</pre>
<dt>
FIOMKDIR
<dd>
Creates a new directory with the name specified as <i>dirName</i>:
<pre>    status = ioctl (fd, FIOMKDIR, "dirName");
</pre>
<dt>
FIORMDIR
<dd>
Removes the directory whose name is specified as <i>dirName</i>:
<pre>    status = ioctl (fd, FIORMDIR, "dirName");
</pre>
<dt>
FIOLABELGET
<dd>
Gets the volume label (located in root directory) and copies the string to
<i>labelBuffer</i>. If the label contains <b>DOS_VOL_LABEL_LEN</b> significant
characters, resulting string  is not NULL terminated:
<pre>    char        labelBuffer [DOS_VOL_LABEL_LEN];
    status = ioctl (fd, FIOLABELGET, (int)labelBuffer);
</pre>
<dt>
FIOLABELSET
<dd>
Sets the volume label to the string specified as <i>newLabel</i>.  The string may
consist of up to eleven ASCII characters:
<pre>    status = ioctl (fd, FIOLABELSET, (int)"newLabel");
</pre>
<dt>
FIOATTRIBSET
<dd>
Sets the file attribute byte in the DOS directory entry to the new value
<i>newAttrib</i>.  The file descriptor refers to the file whose entry is to be 
modified:
<pre>    status = ioctl (fd, FIOATTRIBSET, newAttrib);
</pre>
<dt>
FIOCONTIG
<dd>
Allocates contiguous disk space for a file or directory.  The number of
bytes of requested space is specified in <i>bytesRequested</i>.  In general,
contiguous space should be allocated immediately after the file is
created:
<pre>    status = ioctl (fd, FIOCONTIG, bytesRequested);
</pre>
<dt>
FIOCONTIG64
<dd>
Allocates contiguous disk space for a file or directory.  The number of
bytes of requested space is specified in <i>bytesRequested</i>.  In general,
contiguous space should be allocated immediately after the file is
created. This function accepts a 64-bit value:
<pre>    long long bytesRequested;
    status = ioctl (fd, FIOCONTIG64, &amp;bytesRequested);
</pre>
<dt>
FIONCONTIG
<dd>
Copies to <i>maxContigBytes</i> the size of the largest contiguous free space, 
in bytes, on the volume:
<pre>    status = ioctl (fd, FIONCONTIG, &amp;maxContigBytes);
</pre>
<dt>
FIONCONTIG64
<dd>
Copies to <i>maxContigBytes</i> the size of the largest contiguous free space,
in bytes, on the volume. This function returns a 64-bit value:
<pre>    long long maxContigBytes;
    status = ioctl (fd, FIONCONTIG64, &amp;maxContigBytes);
</pre>
<dt>
FIOREADDIR
<dd>
Reads the next directory entry.  The argument <i>dirStruct</i> is a DIR
directory descriptor.  Normally, the <b><a href="./dirLib.html#readdir">readdir</a>(&nbsp;)</b> routine is used to read a
directory, rather than using the FIOREADDIR function directly.  See <b><a href="./dirLib.html#top">dirLib</a></b>.
<pre>    DIR dirStruct;
    fd = open ("directory", O_RDONLY);