dosfslib.c

vxworks操作系统的文件系统部分原代码

capable of.

However dosFs provides mechanism to allocate truly 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
and optimized access to such a file when it is used.
Usually this will somewhat improve performance when compared to
Nearly Contiguous allocation, at the price of disk space fragmentation.

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 or FIOCONTIG64 function.
The last parameter to the FIOCONTIG function is the size of the requested
contiguous area in bytes, If the FIOCONTIG64 is used, the last parameter
is pointer to 64-bit integer variable, which contains the required file size.
It is also possible to request that the largest contiguous free area on
the disk be obtained.  In this case, the size value CONTIG_MAX (-1) 
is used instead of an actual size.  These ioctl() 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 <errno> set to  S_dosFsLib_NO_CONTIG_SPACE.

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 read() or write(), 
but it can not be guaranteed that appended data will be contiguous
to the initially written data segment.

For example, the following will create a file and allocate 85 Mbytes of 
contiguous space:
.CS
    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            @/
.CE

In contrast, the following example will create a file and allocate the
largest contiguous area on the disk to it:

.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

.IP NOTE
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.
.LP
To determine the actual amount of contiguous space obtained when CONTIG_MAX
is specified as the size, use fstat() to examine the number of blocks
and block size for the file.

When any file is opened, it may be checked for contiguity.
Use the extended flag DOS_O_CONTIG_CHK when calling open() 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, open() will take
an amount of time which is linearly proportional of the file size.

CHANGING, UNMOUNTING, AND SYNCHRONIZING DISKS
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.

If a disk is physically removed, the disk cache will cause dosFsLib to
.I unmount
the volume, which will mark all currently open file descriptors as
.I obsolete.

If a new disk is inserted, it will be automatically
.I mounted
on the next call to open() or creat().

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.
There are some ioctl() 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 ioctl() functions have been added
to support 64-bit integer results.
They have the same name as basic functions, but with suffix 
.I 64,
namely: FIONFREE64, FIOWHERE64 and so on. These commands
expect a pointer to a 64-bit integer, i.e.:
.CS
long long *arg ;
.CE
as the 3rd argument to the ioctl() function.
If a value which is requested with a 32-bit ioctl() command is
too large to be represented in the 32-bit variable, ioctl() will return
ERROR, and <errno> will be set to S_dosFsLib_32BIT_OVERFLOW.

.iP "FIODISKINIT"
Reinitializes a DOS file system on the disk volume.
This function calls dosFsVolFormat() to format the volume,
so dosFsFmtLib must be installed for this to work.
Third argument of ioctl() is passed as argument <opt> to
dosFsVolFormat() 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 dosFsVolFormat() can be used.
.CS
    fd = open ("DEV1:", O_WRONLY);
    status = ioctl (fd, FIODISKINIT, DOS_OPT_BLANK);
.CE

.iP "FIODISKCHANGE"
Announces a media change. No buffers flushing is performed.
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>.
Note that <nameBuf> must be large enough to contain the largest possible
path name, which requires at least 256 bytes.
.CS
    status = ioctl (fd, FIOGETNAME, &nameBuf );
.CE

.iP "FIORENAME"
Renames the file or directory to the string <newname>:
.CS
    fd = open( "oldname", O_RDONLY, 0 );
    status = ioctl (fd, FIORENAME, "newname");
.CE

.iP "FIOMOVE"
Moves the file or directory to the string <newname>:
.CS
    fd = open( "oldname", O_RDONLY, 0 );
    status = ioctl (fd, FIOMOVE, "newname");
.CE

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

.iP "FIOSEEK64"
Sets the current byte offset in the file to the position specified by
<newOffset>. This function supports offsets in 64-bit value range:
.CS
    long long	newOffset;
    status = ioctl (fd, FIOSEEK64, (int) & 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.  This function returns a 32-bit value.
It takes no additional argument:
.CS
    position = ioctl (fd, FIOWHERE, 0);
.CE

.iP "FIOWHERE64"
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 <position>:
.CS
    long long	position;
    status = ioctl (fd, FIOWHERE64, (int) & position);
.CE

.iP "FIOFLUSH"
Flushes disk cache buffers.  It guarantees that any output that has
been requested is actually written to the device:
.CS
    status = ioctl (fd, FIOFLUSH, 0);
.CE

.iP "FIOSYNC"
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.
.CS
    status = ioctl (fd, FIOSYNC, 0);
.CE

.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
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 <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 "FIOTRUNC64"
Similar to FIOTRUNC, but can be used for files lager, than 4GB.
.CS
    long long newLength = .....;
    status = ioctl (fd, FIOTRUNC, (int) & newLength);
.CE  

.iP "FIONREAD"
Copies to <unreadCount> the number of unread bytes in the file:
.CS
    unsigned long unreadCount;
    status = ioctl (fd, FIONREAD, &unreadCount);
.CE
.iP "FIONREAD64"
Copies to <unreadCount> the number of unread bytes in the file.
This function returns a 64-bit integer value:
.CS
    long long unreadCount;
    status = ioctl (fd, FIONREAD64, &unreadCount);
.CE
.iP "FIONFREE"
Copies to <freeCount> the amount of free space, in bytes, on the volume:
.CS
   unsigned long freeCount;
   status = ioctl (fd, FIONFREE, &freeCount);
.CE
.iP "FIONFREE64"
Copies to <freeCount> the amount of free space, in bytes, on the volume.
This function can return value in 64-bit range:
.CS
   long long freeCount;
   status = ioctl (fd, FIONFREE64, &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>. If the label contains DOS_VOL_LABEL_LEN significant
characters, resulting string  is not NULL terminated:
.CS
    char	labelBuffer [DOS_VOL_LABEL_LEN];
    status = ioctl (fd, FIOLABELGET, (int)labelBuffer);
.CE
.iP "FIOLABELSET"
Sets the volume label to the string specified as <newLabel>.  The string may
consist of up to eleven ASCII characters:
.CS
    status = ioctl (fd, FIOLABELSET, (int)"newLabel");
.CE
.iP "FIOATTRIBSET"
Sets the file attribute byte in the DOS directory entry to the new value
<newAttrib>.  The file descriptor refers to the file whose entry is to be 
modified:
.CS
    status = ioctl (fd, FIOATTRIBSET, newAttrib);
.CE
.iP "FIOCONTIG"
Allocates contiguous disk space for a file or directory.  The number of
bytes of requested space is specified in <bytesRequested>.  In general,
contiguous space should be allocated immediately after the file is
created:
.CS
    status = ioctl (fd, FIOCONTIG, bytesRequested);
.CE
.iP "FIOCONTIG64"
Allocates contiguous disk space for a file or directory.  The number of
bytes of requested space is specified in <bytesRequested>.  In general,
contiguous space should be allocated immediately after the file is
created. This function accepts a 64-bit value:
.CS
    long long bytesRequested;
    status = ioctl (fd, FIOCONTIG64, &bytesRequested);
.CE
.iP "FIONCONTIG"
Copies to <maxContigBytes> the size of the largest contiguous free space, 
in bytes, on the volume:
.CS
    status = ioctl (fd, FIONCONTIG, &maxContigBytes);
.CE
.iP "FIONCONTIG64"
Copies to <maxContigBytes> the size of the largest contiguous free space,
in bytes, on the volume. This function returns a 64-bit value:
.CS
    long long maxContigBytes;
    status = ioctl (fd, FIONCONTIG64, &maxContigBytes);
.CE
.iP "FIOREADDIR"
Reads the next directory entry.  The argument <dirStruct> is a DIR
directory descriptor.  Normally, the readdir() routine is used to read a
directory, rather than using the FIOREADDIR function directly.  See dirLib.
.CS
    DIR dirStruct;
    fd = open ("directory", O_RDONLY);
    status = ioctl (fd, FIOREADDIR, &dirStruct);
.CE
.iP "FIOFSTATGET"
Gets file status information (directory entry data).  The argument
<statStruct> is a pointer to a stat structure that is filled with data
describing the specified file.  Normally, the stat() or fstat() routine is
used to obtain file information, rather than using the FIOFSTATGET
function directly.  See dirLib.
.CS
    struct stat statStruct;
    fd = open ("file", O_RDONLY);
    status = ioctl (fd, FIOFSTATGET, (int)&statStruct);
.CE
.iP "FIOTIMESET"
Update time on a file.   <arg> shall be a pointer to a utimbuf structure, 
see utime.h.  If <arg> is value NULL, the current system time is used for
both actime and modtime members.  If <arg> is not NULL then the utimbuf 
structure members actime and modtime are used as passed.  If actime is 
zero value, the file access time is not updated (the operation is ignored).  
If modtime is zero, the file modification time is not updated (the operation 
is ignored).   
See also utime()
..CS
    struct utimbuf newTimeBuf;;
    newTimeBuf.modtime = newTimeBuf.actime = fileNewTime;