/* 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 fields02o,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 & comment02l,12dec01,jkf  SPR#72133, add FIOMOVE and fixing diab build warnings.02k,10dec01,jkf  SPR#24332, dont delete existing files or dirs in dosFsRename02j,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 device02b,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 > EOF01z,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 Branch01v,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#2892401q,06aug99,jkf  delete existing file when dosFsOpen uses O_CREAT/O_TRUNC                 do not overflow read buffer on truncated files, SPR#2830901p,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#2827301n,31jul99,jkf  T2 merge, tidiness & spelling.01m,03dec98,vld  fixed SPR #23692: added FIOTRUNC64 ioctl code;                 rd/wr time measurement excluded01l,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 FIOREADDIR01k,28sep98,vld  gnu extensions dropped from DBG_MSG/ERR_MSG macros01j,24sep98,vld  added support for FIOTIMESET ioctl code01i,16sep98,vld  created separate routine dosFsChkDsk() to solvehen-and-egg problem during volume mounting and                 external call for disk check operation.01h,16sep98,vld  added support for read only devices01j,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 cleanup01g,27jul98,vld  fixed FIOWHERE64  return01f,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 001d,08jul98,vld  fixed bug in dosFsContigAlloc()                  added counting sectors per file count for CONTIG_MAX case.01c,30jun98,lrn  renamed dosFsInit to dosFsLibInit01b,28jun98,vld  tested, checked in, ready for EAR01a,18jan98,vld  written, preliminary*//*INTERNAL: MS-DOS is a registered trademark of Microsoft Corporation.DESCRIPTIONThis library implements the MS-DOS compatible file system.This is a multi-module library, which depends on sub-modules toperform certain parts of the file system functionality.A number of different file system format variations are supported.USING THIS LIBRARYThe various routines provided by the VxWorks DOS file system (dosFs) may beseparated into three broad groups: general initialization, deviceinitialization, and file system operation.The dosFsLibInit() routine is the principal initialization function; it shouldbe called once during system initialization, regardless of how many dosFsdevices are to be used.Another dosFs routine is used for device initialization. For each dosFs device, dosFsDevCreate() must be called to install thedevice in VxWorks device list.In the case where partitioned disks are used, dosFsDevCreate() must becalled for each partition that is anticipated, thereby it is associatedwith a logical device name, so it can be later accessed via the I/Osystem.In case of a removable disk, dosFsDevCreate() must be called duringsystem initialization time, even if a cartridge or diskette may beabsent from the drive at boot time. dosFsDevCreate() will onlyassociate the device with a logical device name. Device access will bedone only when the logical device is first accessed by the application.More detailed information on all of these routines is provided below.INITIALIZING DOSFSLIBTo enable this file system in a particular VxWorks configuration,a library initialization routine must be called for each sub-module ofthe file system, as well as for the underlying disk cache, partitionmanager and drivers.This is usually done at system initialization time, within the .I usrRoottask context.Following is the list of initialization routines that need to becalled:.IP dosFsLibInit(mandatory) initialize the principle dosFs module. Must be called first..IP dosFsFatInit(mandatory) initialize the File Allocation Table handler, which supports12-bit, 16-bit and 32-bit FATs..IP dosVDirLibInit(choice) install the variable size directory handlersupporting Windows-compatible Long File Names (VFAT) DirectoryHandler..IP dosDirOldLibInit(choice) install the fixed size  directory handlerwhich supports old-fashioned 8.3MS-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..LPThe two Directory handlers which are marked.I choiceare installed in accordance with the system requirements, either oneof these modules could be installed or both, in which case the VFAT willtake precedence for MS-DOS compatible volumes.Also, at least one.I CBIOmodule must be initialized on a per-device basis prior to callingdosFsDevCreate().See the related documentation for more details and examples.DEFINING A DOSFS DEVICEThe dosFsDevCreate() routine associates a device with the dosFsLibfunctions.  It expects three parameters:.IP "(1)" 4A pointer to a name string, to be used to identify the device - logicaldevice name.This will be part of the pathname for I/O operations which operate on thedevice.  This name will appear in the I/O system device table, which may bedisplayed using the iosDevShow() routine..IP "(2)"CBIO_DEV_ID - a pointer to the CBIO_DEV structure which provides interfaceto particular disk, via a disk cache, or a partition manager or acombination of a number of.I CBIOmodules which are stacked on top of each other to form one of manyconfigurations 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 automaticallyinvoked every time a device is mounted,this parameter indicates whether the consistency check needs to beperformed automatically on a given device, and on what level ofverbosity is required.In any event, the consistency check may be invoked at a later timee.g. by calling chkdsk().See description for FIOCHKDSK ioctl command for more information..LPFor 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 @/	).CEOnce dosFsDevCreate() has been called, the device can be accessedusing .I ioLibgeneric I/O routines: open(), read(), write(), close(),ioctl(), remove(). Also, the user-level utility functions may be used toaccess the device at a higher level (See usrFsLib reference page formore details).DEVICE AND PATH NAMESOn 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 beused with the VxWorks dosFs file system.  However, it is possible (anddesirable) 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 eitherforward slashes ("/") or backslashes ("\e") as separators.  These may befreely mixed.  The choice of forward slashes or backslashes has absolutelyno effect on the directory data written to the disk.  (Note, however, thatforward slashes are not allowed within VxWorks dosFs filenames, althoughthey are normally legal for pure MS-DOS implementations.)For the sake of consistency however use of forward slashes ("/") isrecommended at all times.The leading slash of a dosFs pathname following the device name isoptional.  For example, both "DOS1:newfile.new" and "DOS1:/newfile.new"refer to the same file.USING EXTENDED DIRECTORY STRUCTUREThis library supports DOS4.0 standard file names which fit the restrictionsof eight upper-case characters optionally followed by a three-characterextension,as well as Windows style VFAT standard long file namesthat are stored mixed cased on disk, but are case insensitive whensearched and matched (e.g. during open() call).The VFAT long file name is stored in a variable number of consecutivedirectory entries.Both standards restrict file size to 4 GB (32 bit value).To provide additional flexibility, this implementation of theDOS file system provides proprietary ling file name format (VXLONGNAMES),which uses a simpler directory structure: the directory entry isof fixed size.  When this option isused, file names may consist of any sequence of up to 40 ASCIIcharacters.  No case conversion is performed, and file name match is case-sensitive.With this directory format thefile maximum size is expanded to 1 Terabyte (40 bit value)..RS 4 4NOTE:  Because special directory entries are used on the disk, disks which use the extended names are .I notcompatible with other implementation of theMS-DOS systems, and cannot be read on MS-DOS or Windows machines..RETo enable the extended file names, set the DOS_OPT_VXLONGNAMES flag when calling dosFsVolFormat().READING DIRECTORY ENTRIESDirectories on VxWorks dosFs volumes may be searched using the opendir(),readdir(), rewinddir(), and closedir() routines.  These calls allow thenames 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 structureused by these routines also returns the file attribute byte from a dosFsdirectory entry.For more information, see the manual entry for dirLib.FILE DATE AND TIMEDirectory entries on dosFs volumes contain creation, last modificationtime 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 returnssystem clock value to obtain date and time.  It is recommended that thetarget system should set the system time during system initializationtime from a network server or from an embedded Calendar / Clockhardware component, so that all files on the file system would beassociated with a correct date and time.The file system consistency checker (see below) sets system clock tovalue following the latest date-time field stored on the disk, if itdiscovers, that function time() returns a date earlier then Jan 1,1998, meaning that the target system does not have a source of validdate and time to synchronize with.See also the reference manual entry for ansiTime.FILE ATTRIBUTESDirectory entries on dosFs volumes contain an attribute byte consistingof bit-flags which specify various characteristics of the entry.  Theattributes which are identified are:  read-only file, hidden file,system file, volume label, directory, and archive.  The VxWorks symbolsfor these attribute bit-flags are:.IP DOS_ATTR_RDONLYFile is write-protected, can not be modified or deleted..IP DOS_ATTR_HIDDENthis attribute is not used by VxWorks..IP DOS_ATTR_SYSTEMthis attribute is not used by VxWorks..IP DOS_ATTR_VOL_LABELdirectory entry describes a volume label,this attribute can not be set or used directly, see ioctl() commandFIOLABELGET and FIOLABELSET below for volume label manipulation..IP DOS_ATTR_DIRECTORYdirectory entry is a subdirectory,this attribute can not be set directly..IP DOS_ATTR_ARCHIVEthis attribute is not used by VxWorks..LPAll the flags in the attribute byte, except the directory and volume labelflags, may be set or cleared using the ioctl() FIOATTRIBSET function.  Thisfunction is called after opening the specific file whose attributes are tobe changed.  The attribute byte value specified in the FIOATTRIBSET call iscopied directly.  To preserve existing flag settings, the current attributesshould first be determined via fstat(), and the appropriateflag(s) changed using bitwise AND or OR operations.  For example, to makea 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.LPSee also the reference manual entry for attrib() and xattrib() foruser-level utility routines which control the attributes of files orfile hierarchy.CONTIGOUS FILE SUPPORTThe 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 toeffectively eliminate the effects of disk space fragmentation,keeping throughput very close to the maximum of which the hardware is