source:
trunk /src /doc /addenda
| Last change on this file was 97, checked in by Valery V. Sedletski, 12 years ago | |
|---|---|
|
Initial branch 0.10 commit. Now added the FORMAT routine (adopted Fat32format from Win32). It is 32-bit. Also, CHKDSK routine made 32-bit, plus small 16-bit wrappers for calling from usual frontends, like chkdsk.exe/format.exe. Added fixes to the IFS needed to support (re-)formatting to/from FAT32. Also, from now, all parts can be compiled by OpenWatcom wcc[386] and wasm. |
|
| File size: 10.1 KB | |
| Line | |
|---|---|
| 1 | We are currently updating the IFS document, but the updates are not |
| 2 | complete at this time. However, the following change is the most |
| 3 | requested clarification/revision that we have received. |
| 4 | |
| 5 | Mary Monahan |
| 6 | |
| 7 | |
| 8 | FS_FINDFIRST |
| 9 | FIND FIRST MATCHING FILE NAME(S) |
| 10 | |
| 11 | |
| 12 | | Purpose |
| 13 | |
| 14 | | Find first occurrence(s) of matching file name(s) in a directory. |
| 15 | |
| 16 | |
| 17 | Calling Sequence |
| 18 | |
| 19 | int far pascal FS_FINDFIRST (pcdfsi, pcdfsd, pName, iCurDirEnd, |
| 20 | attr, pfsfsi, pfsfsd, |
| 21 | pData, cbData, pcMatch, level, flags) |
| 22 | struct cdfsi far * pcdfsi; |
| 23 | struct cdfsd far * pcdfsd; |
| 24 | char far * pName; |
| 25 | unsigned short iCurDirEnd; |
| 26 | unsigned short attr; |
| 27 | struct fsfsi far * pfsfsi; |
| 28 | struct fsfsd far * pfsfsd; |
| 29 | char far * pData; |
| 30 | unsigned short cbData; |
| 31 | unsigned short far * pcMatch; |
| 32 | unsigned short level; |
| 33 | unsigned short flags; |
| 34 | |
| 35 | |
| 36 | |
| 37 | Where |
| 38 | |
| 39 | PCDFSI |
| 40 | ______ |
| 41 | is a pointer to the file-system-independent working directory structure. |
| 42 | |
| 43 | PCDFSD |
| 44 | ______ |
| 45 | is a pointer to the file-system-dependent working directory structure. |
| 46 | |
| 47 | PNAME |
| 48 | _____ |
| 49 | is a pointer to the ASCIIZ name of the file or directory. |
| 50 | |
| 51 | Wildcard characters are allowed only in the last component. The FSD does |
| 52 | not need to validate this pointer. |
| 53 | |
| 54 | ICURDIREND |
| 55 | __________ |
| 56 | is the index of the end of the current directory in pName. |
| 57 | |
| 58 | | This is provided to allow optimization of FSD path processing. If |
| 59 | iCurDirEnd == -1 there is no current directory relevant to the name text, |
| 60 | that is, a device. |
| 61 | |
| 62 | ATTR |
| 63 | ____ |
| 64 | is a bit field that governs the match. |
| 65 | |
| 66 | | Any directory entry whose attribute bit mask is a subset of attr and whose |
| 67 | | name matches that in pName should be returned. The attr field is two byte |
| 68 | | sized attribute bit masks. The least significant byte contains the "may |
| 69 | | have" bits. For example, a "may have" attribute of system and hidden is |
| 70 | | passed in. A file with the same name and an attribute of system is found. |
| 71 | | This file is returned. A file with the same name and no attributes (a |
| 72 | | regular file) is also returned. The "may have" attributes read-only and |
| 73 | | file-archive will not be passed in and should be ignored when comparing |
| 74 | | directory attributes. The most significant byte contains the "must have" |
| 75 | | bits. A file with a matching name must also have the attributes in the |
| 76 | | "must have" bits to be returned. See the OS/2 Version 3.0 Control Program |
| 77 | ________________________________ |
| 78 | | Programming Reference for more information about the attribute field under |
| 79 | _____________________ |
| 80 | | DosFindFirst. |
| 81 | |
| 82 | | The value of attr passed to the FSD will be valid. The bit 0x0040 indi- |
| 83 | | cates a non-8.3 filename format. It should be treated the same way as |
| 84 | | system and hidden attributes are. You should not return a file name that |
| 85 | | does not conform to 8.3 filename format if this bit is not set in the "may |
| 86 | | have" bits. |
| 87 | |
| 88 | PFSFSI |
| 89 | ______ |
| 90 | is a pointer to the file-system-independent file-search structure. |
| 91 | |
| 92 | The FSD should not update this structure. |
| 93 | |
| 94 | PFSFSD |
| 95 | ______ |
| 96 | is a pointer to the file-system-dependent file-search structure. |
| 97 | |
| 98 | The FSD may use this to store information about continuation of the |
| 99 | search. |
| 100 | |
| 101 | PDATA |
| 102 | _____ |
| 103 | is the address of the application data area. |
| 104 | |
| 105 | Addressing of this data area is not validated by the kernel (see |
| 106 | FSH_PROBEBUF). The FSD will fill in this area with a set of packed, |
| 107 | variable-length structures that contain the requested data and matching |
| 108 | file name. |
| 109 | |
| 110 | CBDATA |
| 111 | ______ |
| 112 | is the length of the application data area in bytes. |
| 113 | |
| 114 | PCMATCH |
| 115 | _______ |
| 116 | is a pointer to the number of matching entries. |
| 117 | |
| 118 | The FSD returns, at most, this number of entries; the FSD returns in this |
| 119 | parameter the number of entries actually placed in the data area. |
| 120 | |
| 121 | The FSD does not need to validate this pointer. |
| 122 | |
| 123 | LEVEL |
| 124 | _____ |
| 125 | is the information level to be returned. |
| 126 | |
| 127 | | Level selects among a series of data structures to be returned (see |
| 128 | | below). The level passed to the FSD is valid. |
| 129 | |
| 130 | FLAGS |
| 131 | _____ |
| 132 | indicates whether to return file-position information. |
| 133 | |
| 134 | | flags == FF_NOPOS (0x00) indicates that file-position information should |
| 135 | | not be returned (see below). |
| 136 | | flags == FF_GETPOS (0x01) indicates that file-position information should |
| 137 | be returned and the information format described below should be |
| 138 | used. |
| 139 | |
| 140 | The flag passed to the FSD has a valid value. |
| 141 | |
| 142 | |
| 143 | Remarks |
| 144 | |
| 145 | NOTE: |
| 146 | |
| 147 | | The find structure passed back to the user is the structure defined for the |
| 148 | | 16 bit DosFindFirst API with some modification if the flags parameter is set. |
| 149 | | The basic, level one FILEFINDBUF structure is |
| 150 | |
| 151 | | struct FileFindBuf { |
| 152 | | unsigned short dateCreate; |
| 153 | | unsigned short timeCreate; |
| 154 | | unsigned short dateAccess; |
| 155 | | unsigned short timeAccess; |
| 156 | | unsigned short dateWrite; |
| 157 | | unsigned short timeWrite; |
| 158 | | long cbEOF; |
| 159 | | long cbAlloc; |
| 160 | | unsigned short attr; |
| 161 | | unsigned char cbName; |
| 162 | | unsigned char szNameY"; |
| 163 | | } |
| 164 | |
| 165 | | For flags == 1, the FSD must store in the first DWORD of the per-file attri- |
| 166 | | butes structure adequate information that in addition with the file name will |
| 167 | | allow the search to be resumed from the file by calling FS_FINDFROMNAME. For |
| 168 | | example, an ordinal representing the file's position in the directory could |
| 169 | | be stored. If the filename must be used to restart the search, the DWORD may |
| 170 | | be left blank. |
| 171 | |
| 172 | | For level 0x0001 and flags == 1, directory information for FS_FINDFIRST is |
| 173 | | returned in the following format: |
| 174 | | struct FileFromFindBuf { |
| 175 | | long position; /* position given to FSD on following */ |
| 176 | | /* FS_FINDFROMNAME call */ |
| 177 | | unsigned short dateCreate; |
| 178 | | unsigned short timeCreate; |
| 179 | | unsigned short dateAccess; |
| 180 | | unsigned short timeAccess; |
| 181 | | unsigned short dateWrite; |
| 182 | | unsigned short timeWrite; |
| 183 | | long cbEOF; |
| 184 | | long cbAlloc; |
| 185 | | unsigned short attr; |
| 186 | | unsigned char cbName; |
| 187 | | unsigned char szNameY"; |
| 188 | | } |
| 189 | |
| 190 | | The other information levels have similar format, with the position the first |
| 191 | | field in the structure for flags == 1. For level 0x0002 and flags == 1, |
| 192 | | directory information for FS_FINDFIRST is returned in the following format: |
| 193 | |
| 194 | | struct FileFromFindBuf { |
| 195 | | long position; /* this field is not present if flags */ |
| 196 | | /* is 0 */ |
| 197 | | unsigned short dateCreate; |
| 198 | | unsigned short timeCreate; |
| 199 | | unsigned short dateAccess; |
| 200 | | unsigned short timeAccess; |
| 201 | | unsigned short dateWrite; |
| 202 | | unsigned short timeWrite; |
| 203 | | long cbEOF; |
| 204 | | long cbAlloc; |
| 205 | | unsigned short attr; |
| 206 | | unsigned long cbList; /* size of EAs for the file */ |
| 207 | | unsigned char cbName; |
| 208 | | unsigned char szNameY"; |
| 209 | | } |
| 210 | |
| 211 | | For level 0x0003 and flags == 1, the directory information for FS_FINDFIRST |
| 212 | | is a bit more complicated. An EAOP struction will be located at the begin- |
| 213 | | ning of pData. You should start filling in the data after the EAOP struc- |
| 214 | | ture. The data format is: |
| 215 | |
| 216 | | struct FileFromFindBuf { |
| 217 | | long position; /* this field is not present if flags */ |
| 218 | | /* is 0. */ |
| 219 | | unsigned short dateCreate; |
| 220 | | unsigned short timeCreate; |
| 221 | | unsigned short dateAccess; |
| 222 | | unsigned short timeAccess; |
| 223 | | unsigned short dateWrite; |
| 224 | | unsigned short timeWrite; |
| 225 | | long cbEOF; |
| 226 | | long cbAlloc; |
| 227 | | unsigned short attr; |
| 228 | | FEALIST fealist; /* this is a variable length field */ |
| 229 | | unsigned char cbName; |
| 230 | | unsigned char szNameY"; |
| 231 | | } |
| 232 | |
| 233 | | For a description of the FEALIST structure, see "FEAs" on page 1-10. |
| 234 | |
| 235 | If the non-8.3 filename format bit is set in the attributes of a file found |
| 236 | by FS_FINDFIRST/NEXT/FROMNAME, it must be turned off in the copy of the |
| 237 | attributes returned in pData. |
| 238 | |
| 239 | If FS_FINDFIRST for a particular search returns an error, an FS_FINDCLOSE for |
| 240 | that search will not be issued. |
| 241 | |
| 242 | Sufficient information to find the next matching directory entry must be |
| 243 | saved in the fsfsd data structure. |
| 244 | |
| 245 | In the case where directory entry information overflows the pData area, the |
| 246 | FSD should be able to continue the search from the entry which caused the |
| 247 | overflow on the next FS_FINDNEXT or FS_FINDFROMNAME. |
| 248 | |
| 249 | In the case of a global search in a directory, the first two entries in that |
| 250 | directory as reported by the FSD should be '.' and '..' (current and the |
| 251 | parent directories). |
| 252 | |
| 253 | NOTE: The FSD will be called with the FINDFIRST/FINDFROMNAME interface when |
| 254 | the 32-bit DosFindFirst/DosFindNext APIs are called. THIS IS A CHANGE FROM |
| 255 | 1.X IFS interface for redirector FSDs. The kernel will also be massaging the |
| 256 | find records so that they appear the way the caller expects. Redirectors who |
| 257 | have to resume searches should take this information into account. (i.e. You |
| 258 | might want to reduce the size of the buffer sent to the server, so that the |
| 259 | position fields can be added to the beginning of all the find records). |
| 260 | |
| 261 | | APPLICATION NOTE: Some applications have been coded to expect behavior |
| 262 | | beyond the architectural requirements. For example, there are applications |
| 263 | | that require DosFindFirst to return an entry for a file that has been open- |
| 264 | | created, but which has never been closed. You can debate whether a file |
| 265 | | truly exists until it has been closed, but unless the applications are |
| 266 | | changed they will still not work. Consequently, it is recommended that FSDs |
| 267 | | exhibit this behavior. |
| 268 |
Note:
See TracBrowser
for help on using the repository browser.