FS_OpenFile( PIOREQ pir )
All file open and create operations are handled through FS_OpenFile. This routine handles the Win32 functions: OpenFile(), and CreateFile(); and INT 21h functions: 0Fh, 16h, 3Ch, 3Dh, 5Ah, 5Bh, 6Ch and 716Ch.
ir_ppath
Supplies a pointer to the canonicalized unicode pathname to the file that is to be opened. Wildcards are not allowed on the pathname.
If ir_ppath is NULL, it indicates that this is a special kind of open where there is no path available, only cluster and directory information is available. This special kind of open is issued by the IFS manager when it is taking over a file handle left open by a TSR before booting into Windows. For such files, the IFS manager extracts the information from DOS about the cluster number and the directory position for the open file. The FSD needs to locate the file given this information. A pointer to a structure containing this information is passed in ir_uFName. Note that this kind of open can be issued only on FAT filesystems because the only native system supported by MS-DOS is the FAT filesystem.
ir_rh
Supplies handle to disk volume or network resource where the file is to be opened.
ir_sfn
Supplies system file number.
ir_flags
Supplies desired access & sharing mode info.
Desired Access Values: One of the following values may be specified. | |
Value | Meaning |
ACCESS_READONLY | Open for read-only access. |
ACCESS_WRITEONLY | Open for write-only access. |
ACCESS_READWRITE | Open for read and write access. |
ACCESS_EXECUTE | Open for execute access. |
Sharing Mode Values: This defines the file access granted to other processes. One of the following modes may be specified. | |
SHARE_COMPATIBILITY | Open in compatibility mode. |
SHARE_DENYREADWRITE | Open for exclusive access. |
SHARE_DENYWRITE | Open allowing read-only access. |
SHARE_DENYREAD | Open allowing write-only access. |
SHARE_DENYNONE | Open allowing other processes access. |
SHARE_FCB | Open in the special FCB mode. |
ir_options
Supplies the open action to take if file exists or not. Also supplies some special options that are independent of the open action.
Open Action Values: One of the following actions or a combination of actions may be specified. Specifies the action to take if the file exists or not exists. | |
Value | Meaning |
ACTION_CREATENEW | Create a new file. Fail if the file already exists. |
ACTION_CREATEALWAYS | Create a new file. If the file already exists open it and set its new length and attributes. |
ACTION_OPENEXISTING | Open an existing file. Fail if the file does not exist. |
ACTION_OPENALWAYS | Open an existing file. If the file does not exist, create a new file. |
ACTION_REPLACEEXISTING | Open an existing file and set its new length. Fail if the file does not exists. |
Special Options: The following special options can also be passed in on this api. | |
Value | Meaning |
OPEN_FLAGS_COMMIT | The file should be opened in writethrough mode i.e all data should be written synchronously to the disk. The data can be cached, but no dirty data should remain in the cache across calls to write to the file. |
OPEN_FLAGS_NO_CACHE | Read/write operations to this file should not be cached. There should be no data kept in the cache for this file. This also means that the filesystem should not do read-aheads and other optimizing techniques on this file. |
OPEN_FLAGS_NO_COMPRESS | The file should not be compressed when it is created or changed. |
OPEN_FLAGS_ALIAS_HINT | This is valid only on a create operation. The caller can pass in a number from 0 to 65535 to be used as a hint by the FSD for the numeric tail if it is auto-generating names. If the FSD does not auto-generate names, this flag should be ignored. This is purely an advisory option. |
R0_SWAPPER_CALL | This operation is on the swap file. The swap file needs special handling as has already been discussed in section 8.3.4. |
ir_attr
Supplies new file attribute for create operations. These attributes should be ignored when an existing file is opened or truncated. It also supplies advisory path parsing flags.
Attribute Values: Any combination of the following attributes may be specified or returned. | |
Value | Meaning |
FILE_ATTRIBUTE_READONLY | Read-Only file. |
FILE_ATTRIBUTE_HIDDEN | Hidden file. |
FILE_ATTRIBUTE_SYSTEM | System file. |
FILE_ATTRIBUTE_DIRECTORY | Subdirectory. The following attribute will only be specified by itself. It will not be combined with any of the other attributes. |
FILE_ATTRIBUTE_VOLUMELABEL | Volume label. |
Path Parsing Flags: The following path parsing flags are passed in. | |
FILE_FLAG_LONG_PATH | Path has a longname component. |
FILE_FLAG_KEEP_CASE | Preserve the case of the filename passed in when storing on disk. This also implies that this call should use longname semantics for its processing. |
FILE_FLAG_HAS_DOT | Filename component has a dot in its name. |
FILE_FLAG_IS_LFN | Filename component is a longname. |
ir_uFName
Pointer to the case-preserved filename component in unicode if ir_ppath is a valid pointer. If ir_ppath is NULL, then this field contains a pointer to an open information structure SFTOpenInfo as described below.
SFTOpenInfo Structure: | |
Value | Meaning |
soi_dirclus | Supplies the logical cluster number of the directory cluster for the open file. |
soi_dirind | Supplies the index of the directory entry of the open file in the directory cluster pointed at by soi_dirclus. |
soi_dirname
Supplies the 11-character name of the open file in FCB format.
ir_upath
Pointer to the unparsed user pathname in unicode.
ir_hfunc
Supplies a pointer to a function pointer structure.
ir_ptuninfo
Supplies a pointer to a tunnelling structure. A NULL pointer is passed in this field if there is no tunnelling information. The tunnelling structure is described below.
Tunnelling Structure: | |
Value | Meaning |
tuni_bfContents | Specifies flags for the tunnelling information passed in. |
Tunnelling Info Flag Values: | |
Value | Meaning |
TUNI_CONTAINS_ALTNAME | Alternate unicode name is available in structure. |
TUNI_CONTAINS_CREATIONT | Creation time for file available. |
TUNI_CONTAINS_LASTACCESST | Last access time for file available. |
TUNI_CONTAINS_LASTWRITET | Last modification time for file available. |
tuni_pAltName
Supplies the alternate name in unicode that should be used for this file.
tuni_ftCreationTime
Supplies the creation time in the Win32 FileTime structure format specified below.
Win32 FileTime Structure: | |
Value | Meaning |
dwLowDateTime | Supplies the low double word of the time in Win32 format. |
dwHighDateTime | Supplies the low double word of the time in Win32 format. |
tuni_ftLastAccessTime
Supplies the last access time in the Win32 FileTime structure format described above.
tuni_ftLastWriteTime
Supplies the last modification time in the Win32 FileTime structure format described above.
ir_pos
Supplies the pointer to the list of file record locks returned previously on FS_CloseFile when a volume lock is in progress. This parameter is NULL if there were no file record locks active on the file at the time it was closed. If the OPEN_FLAGS_ALIAS_HINT flag is set, this field supplies the hint value to be used for the numeric tail. FSDs should first check for the OPEN_FLAGS_ALIAS_HINT flag. If it is set, this field provides the hint value. If not set, this field supplies the pointer to the lock list.
ir_fh
Supplies the FSD file handle associated with this file before the file was closed. This parameter should be used only if there were file record locks active on the file i.e. ir_pos is non-NULL. This parameter is passed in to the FSD so that it can identify the lock corresponding to the handle that is being reopened and keep its data structures consistent. Volume locking is described in detail in the volume locking specification.
ir_user
Supplies user id for this request.
ir_pid
Supplies process id for this request.
ir_error | Returns status of the operation ( 0 if no error, errorcode otherwise ). |
ir_fh | Returns the FSD file handle identifying the opened file. |
ir_dostime | Returns the file modification date and time (in DOS format). |
ir_hfunc | Returns a filled in function pointer structure. The structure is filled in as follows: |
Function Pointer Structure: | |
Value | Meaning |
hf_read | Returns pointer to FS_ReadFile function. |
hf_write | Returns pointer to FS_WriteFile function. |
hf_misc | Returns a pointer to a function table structure, in the FSD, containing a list of the remaining FSD handle based file I/O entry points. |
Function Table Structure: | |
Value | Meaning |
hm_version | IFS version number. |
hm_revision | IFS interface revision number. |
hm_size | Number of function entry points in table. |
hm_func[NUM_HNDLMISC] | Returns an array of pointers to the handle-based functions as described below: |
hm_func[HM_SEEK] | Pointer to FS_SeekFile function. |
hm_func[HM_CLOSE] | Pointer to FS_CloseFile function. |
hm_func[HM_COMMIT] | Pointer to FS_CommitFile function. |
hm_func[HM_FILELOCKS] | Pointer to FS_LockFile function. |
hm_func[HM_FILETIMES] | Pointer to FS_FileTime function. |
hm_func[HM_PIPEREQUEST] | Pointer to FS_NamedPipeUNCRequest function. |
hm_func[HM_HANDLEINFO] | Pointer to FS_NamedPipeHandleInfo function. |
hm_func[HM_ENUMHANDLE] | Pointer to FS_EnumerateHandle function. |
ir_options | Returns the action performed by the FSD. |
Return Action Values: One of the following actions may be returned. | |
Value | Meaning |
ACTION_OPENED | An existing file has been opened. |
ACTION_CREATED | A new file has been created. |
ACTION_REPLACED | An existing file has been truncated. |
ir_size | Returns the file size when an existing file is opened. The size is currently placed in the SFT in the DOS data structures. |
ir_attr | Returns the file attribute (state for named pipes). |
Return Attribute Values: Any combination of the following attributes may be returned. | |
Value | Meaning |
FILE_ATTRIBUTE_READONLY | Read-Only file. |
FILE_ATTRIBUTE_HIDDEN | Hidden file. |
FILE_ATTRIBUTE_SYSTEM | System file. |
FILE_ATTRIBUTE_DIRECTORY | Subdirectory. |
FILE_ATTRIBUTE_ARCHIVE | Archive file. This attribute cannot be returned in combination with other attributes. |
FILE_ATTRIBUTE_VOLUMELABEL | Volume label. |
If an FS does not support long filenames on a volume and it gets a LFN api call on that volume, it should fail the call. Tunnelling is described separately in another section. Tunnelling is supported only on local drives, so network FSDs do not need to honour the tunnelling information.