dosfslib.c

FAT文件系统原代码

/* dosFsLib.c - MS-DOS media-compatible file system library */ 

/* Copyright 1984-2002 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
02q,02may02,jkf  Corrects SPR#76501, 72603. Avoids 65085 and 33221.
                 and a performance improvement for FIOSYNC.
02p,30apr02,jkf  SPR#62786, rename should preserve time and date fields
02o,30apr02,jkf  SPR#76510, dosFsVolDescGet() should return NULL instead of
                 the default device when the underlying iosDevFind() does. 
02n,15Jan02,chn  SPR#29751, removed path case sensitivity during creat phase 
                 of rename. Possible NFS interaction, see comments at change.
02m,18dec01,chn  SPR#71105, correct file size in dosFsContigAlloc & comment
02l,12dec01,jkf  SPR#72133, add FIOMOVE and fixing diab build warnings.
02k,10dec01,jkf  SPR#24332, dont delete existing files or dirs in dosFsRename
02j,10dec01,jkf  SPR#72039, various fixes from Mr. T. Johnson.
02i,09dec01,jkf  SPR#71637, fix for SPR#68387 caused ready changed bugs.
02h,30nov01,jkf  SPR#68203, updating last access date on open-read-close
                 operation causes unwanted writes, increasing flash wear.
02g,30nov01,jkf  SPR#33343, media unformatted or missing err better reported.
                 SPR#69074, statfs to invalid media caused continuous errors.
02f,15nov01,jkf  SPR#71720, avoid unaligned pointer access.
                 clean up multiple errno's when mounting unformatted volume.
02e,13nov01,jkf  correct typo in checkin comment.
02d,13nov01,jkf  improve dosFsBootSecGet() error message, add a comment about 
                 nBlocks reporting total blocks, not last addressable block.
02c,10nov01,jkf  SPR#67890, chkdsk writes to RDONLY device
02b,09nov01,jkf  SPR#71633, dont set errno when DevCreate is called w/BLK_DEV
                 SPR#32178, made dosFsVolDescGet public, cleaned up man page. 
                 SPR#33684, dosFsShow reporting incorrect verbosity setting.
02a,23oct01,rip  SPR#65085: tasks in FIOSYNC interlocking (dup of #33221 cf 01v)
                 SPR#30464: FIONCONTIG64 not shifting using 64bit math
                 SPR#30540: FillGap assumes step over sector on FIOSEEK > EOF
01z,21aug01,jkf  SPR#69031, common code for both AE & 5.x.
01y,26jul01,jkf  T2 SPR#65009, T3 SPR#65271.  dosFsLibInit returns OK or ERROR.
01x,14mar01,jkf  SPR#34704,FAT12/FAT16 determination, SPR#62415 sig location.
01w,19sep00,csh  Manual Merge From Alameda Branch To Sunnyvale Branch
01v,08sep00,nrj  fixed SPR#33221, to avoid dead-lock because of multiple tasks
		 doing FIOSYNC on opened files
		 fixed SPR#33702, 33684, The autocheck verbosity is now 
		 initialized properly in volume descriptor.
01u,29feb00,jkf  cleaning warning.

01t,29feb00,jkf  T3 changes.
01s,28sep99,jkf  fixed SPR#28554, now return error on write to full disk.
01r,31aug99,jkf  changes for new CBIO API.  Changed FIOTIMESET to allow
                 utime to follow Solaris 2.6 behavior.  If arg is NULL, 
                 the current time is used, added docs. SPR#28924
01q,06aug99,jkf  delete existing file when dosFsOpen uses O_CREAT/O_TRUNC
                 do not overflow read buffer on truncated files, SPR#28309
01p,31jul99,jkf  Dont allow larger than 4GB file on anything but
                 VXLONGNAMES directory entry files. SPR#27532.
01o,31jul99,jkf  Added support for FSTYPE (0x36) in bootsec, SPR#28273
01n,31jul99,jkf  T2 merge, tidiness & spelling.
01m,03dec98,vld  fixed SPR #23692: added FIOTRUNC64 ioctl code;
                 rd/wr time measurement excluded
01l,22nov98,vld  included  features required by NFS protocol:
		 - added support for FIOFSTATFSGET ioctl code;
		 - added support for creating files "with holes";
		 - added dosFsSeekDir() routine and controlling
		   of dd_cookie field within FIOREADDIR
01k,28sep98,vld  gnu extensions dropped from DBG_MSG/ERR_MSG macros
01j,24sep98,vld  added support for FIOTIMESET ioctl code
01i,16sep98,vld  created separate routine dosFsChkDsk() to solve
hen-and-egg problem during volume mounting and
                 external call for disk check operation.
01h,16sep98,vld  added support for read only devices
01j,11sep98,vld  added support for non CBIO ptr argument in dosFsDevCreate().
01i,26aug98,vld  ignore mode = S_IFDIR except with O_CREAT (SPR#22227)
01h,30jul98,wlf  partial doc cleanup
01g,27jul98,vld  fixed FIOWHERE64  return
01f,08jul98,vld  print64Lib.h moved to h/private directory. 
01e,08jul98,vld  dosFsContigAlloc() (FIOCONTIG effected) changed
                 not to zero allocated data and leave file size as 0
01d,08jul98,vld  fixed bug in dosFsContigAlloc() 
                 added counting sectors per file count for CONTIG_MAX case.
01c,30jun98,lrn  renamed dosFsInit to dosFsLibInit
01b,28jun98,vld  tested, checked in, ready for EAR
01a,18jan98,vld  written, preliminary
*/

/*
INTERNAL: MS-DOS is a registered trademark of Microsoft Corporation.

DESCRIPTION
This library implements the MS-DOS compatible file system.
This is a multi-module library, which depends on sub-modules to
perform certain parts of the file system functionality.
A number of different file system format variations are supported.

USING THIS LIBRARY
The various routines provided by the VxWorks DOS file system (dosFs) may be
separated into three broad groups: general initialization, device
initialization, and file system operation.

The dosFsLibInit() routine is the principal initialization function; it should
be called once during system initialization, regardless of how many dosFs
devices are to be used.

Another dosFs routine is used for device initialization. 
For each dosFs device, dosFsDevCreate() must be called to install the
device in VxWorks device list.
In the case where partitioned disks are used, dosFsDevCreate() must be
called for each partition that is anticipated, thereby it is associated
with a logical device name, so it can be later accessed via the I/O
system.

In case of a removable disk, dosFsDevCreate() must be called during
system initialization time, even if a cartridge or diskette may be
absent from the drive at boot time. dosFsDevCreate() will only
associate the device with a logical device name. Device access will be
done only when the logical device is first accessed by the application.

More detailed information on all of these routines is provided below.

INITIALIZING DOSFSLIB
To enable this file system in a particular VxWorks configuration,
a library initialization routine must be called for each sub-module of
the file system, as well as for the underlying disk cache, partition
manager and drivers.
This is usually done at system initialization time, within the 
.I usrRoot
task context.

Following is the list of initialization routines that need to be
called:
.IP dosFsLibInit
(mandatory) initialize the principle dosFs module. Must be called first.
.IP dosFsFatInit
(mandatory) initialize the File Allocation Table handler, which supports
12-bit, 16-bit and 32-bit FATs.
.IP dosVDirLibInit
(choice) install the variable size directory handler
supporting Windows-compatible Long File Names (VFAT) Directory
Handler.
.IP dosDirOldLibInit
(choice) install the fixed size  directory handler
which supports old-fashioned 8.3
MS-DOS file names, and Wind River Systems proprietary long file names
(VXLONG).
.IP dosFsFmtLibInit
(optional) install the volume formatting module.
.IP dosChkLibInit
(optional) install the file system consistency checking module.
.LP
The two Directory handlers which are marked
.I choice
are installed in accordance with the system requirements, either one
of these modules could be installed or both, in which case the VFAT will
take precedence for MS-DOS compatible volumes.

Also, at least one
.I CBIO
module must be initialized on a per-device basis prior to calling
dosFsDevCreate().
See the related documentation for more details and examples.

DEFINING A DOSFS DEVICE
The dosFsDevCreate() routine associates a device with the dosFsLib
functions.  It expects three parameters:
.IP "(1)" 4
A pointer to a name string, to be used to identify the device - logical
device name.
This will be part of the pathname for I/O operations which operate on the
device.  This name will appear in the I/O system device table, which may be
displayed using the iosDevShow() routine.
.IP "(2)"
CBIO_DEV_ID - a pointer to the CBIO_DEV structure which provides interface
to particular disk, via a disk cache, or a partition manager or a
combination of a number of
.I CBIO
modules which are stacked on top of each other to form one of many
configurations possible.
.IP "(3)"
A maximum number of files can be simultaneously opened on a particular device.
.IP "(4)"
Because volume integrity check utility can be automatically
invoked every time a device is mounted,
this parameter indicates whether the consistency check needs to be
performed automatically on a given device, and on what level of
verbosity is required.
In any event, the consistency check may be invoked at a later time
e.g. by calling chkdsk().
See description for FIOCHKDSK ioctl command for more information.
.LP
For example:
.CS
    dosFsDevCreate
	(
	"/sd0",		/@ name to be used for volume   @/
	pCbio,		/@ pointer to device descriptor @/
	10,		/@ max no. of simultaneously open files @/
	DOS_CHK_REPAIR | DOS_CHK_VERB_1
			/@ check volume during mounting and repair @/
			/@ errors, and display volume statistics @/
	)
.CE

Once dosFsDevCreate() has been called, the device can be accessed
using 
.I ioLib
generic I/O routines: open(), read(), write(), close(),
ioctl(), remove(). Also, the user-level utility functions may be used to
access the device at a higher level (See usrFsLib reference page for
more details).

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 dosFsDevCreate() 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.)

For the sake of consistency however use of forward slashes ("/") is
recommended at all times.

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 DIRECTORY STRUCTURE
This library supports DOS4.0 standard file names which fit the restrictions
of eight upper-case characters optionally followed by a three-character
extension,
as well as Windows style VFAT standard long file names
that are stored mixed cased on disk, but are case insensitive when
searched and matched (e.g. during open() call).
The VFAT long file name is stored in a variable number of consecutive
directory entries.
Both standards restrict file size to 4 GB (32 bit value).

To provide additional flexibility, this implementation of the
DOS file system provides proprietary ling file name format (VXLONGNAMES),
which uses a simpler directory structure: the directory entry is
of fixed size.  When this option is
used, file names may consist of any sequence of up to 40 ASCII
characters.  No case conversion is performed, 
and file name match is case-sensitive.
With this directory format the
file maximum size is expanded to 1 Terabyte (40 bit value).

.RS 4 4
NOTE:  Because special directory entries are used on the disk, disks 
which use the extended names are 
.I not
compatible with other implementation of the
MS-DOS systems, and cannot be read on MS-DOS or Windows machines.
.RE

To enable the extended file names, set the DOS_OPT_VXLONGNAMES flag 
when calling dosFsVolFormat().

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 creation, last modification
time and date, and the last access date for each file or subdirectory.
Directory last modification time and date fields are set only when 
a new entry is created, but not when any directory entries are deleted.
The last access date field indicates the date of the last read or write.  
The last access date field is an optional field, per Microsoft.  By 
default, file open-read-close operations do not update the last access 
date field.  This default avoids media writes (writing out the date field)
during read only operations.   In order to enable the updating of the 
optional last access date field for open-read-close operations, you must 
call dosFsLastAccessDateEnable(), passing it the volumes DOS_VOLUME_DESC_ID 
and TRUE.

The dosFs file system uses the ANSI time() function, that returns
system clock value to obtain date and time.  It is recommended that the
target system should set the system time during system initialization
time from a network server or from an embedded Calendar / Clock
hardware component, so that all files on the file system would be
associated with a correct date and time.

The file system consistency checker (see below) sets system clock to
value following the latest date-time field stored on the disk, if it
discovers, that function time() returns a date earlier then Jan 1,
1998, meaning that the target system does not have a source of valid
date and time to synchronize with.

See also the reference manual entry for ansiTime.

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:

.IP DOS_ATTR_RDONLY
File is write-protected, can not be modified or deleted.
.IP DOS_ATTR_HIDDEN
this attribute is not used by VxWorks.
.IP DOS_ATTR_SYSTEM
this attribute is not used by VxWorks.
.IP DOS_ATTR_VOL_LABEL
directory entry describes a volume label,
this attribute can not be set or used directly, see ioctl() command
FIOLABELGET and FIOLABELSET below for volume label manipulation.
.IP DOS_ATTR_DIRECTORY
directory entry is a subdirectory,
this attribute can not be set directly.
.IP DOS_ATTR_ARCHIVE
this attribute is not used by VxWorks.

.LP
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
.LP
See also the reference manual entry for attrib() and xattrib() for
user-level utility routines which control the attributes of files or
file hierarchy.

CONTIGOUS FILE SUPPORT
The VxWorks dosFs file system provides efficient files storage:
space will be allocated in groups of clusters (also termed 
.I extents
) so that a file will be composed of relatively large contiguous units.
This  nearly contiguous allocation technique is designed to
effectively eliminate the effects of disk space fragmentation,
keeping throughput very close to the maximum of which the hardware is