Installable File Systems For OS/2 Version 3.0 OS/2 File Systems Department PSPC Boca Raton, Florida February 13, 1998 This document includes a DRAFT description of the Installable File System Driver Interface for IBM OS/2 Standard Edition Version 3.0. PLEASE DO NOT DISTRIBUTE THIS VERSION. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS DOCUMENNT "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL IBM BE LIABLE FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO ANY LOST PROFITS, LOST SAVINGS OR ANY INCIDENTAL OR CONSEQUENTAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY YOU BASED ON A THIRD PARTY CLAIM. Some or all of the interfaces described in this document are unpublished. IBM reserves the right to change or delete them in future versions of OS/2, at IBM's sole discretion, without notice to you. IBM does not guarantee that compatability of your applications can or will be maintained with future versions of OS/2. This document could include technical inaccuracies or typographical errors. It is possible that this document may contain reference to, or information about, IBM products, programming or services that are not announced in your country. Such references or infor- mation must not be construed to mean that IBM intends to announce such IBM products, programming or services in your country. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Armonk NY 10504. Copyright International Business Machines Corporation 1991. All rights reserved. Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Contents Chapter 1. Installable File System Mechanism ................. 1-1 Installable File System Overview ........................... 1-1 System Relationships . 1-1 File I/O API ...................................... 1-2 Buffer Management . 1-5 Volume Management . 1-5 Connectivity . 1-5 IPL Mechanism . 1-6 OS/2 Partition Access ............................... 1-6 Permissions . 1-7 File Naming Conventions .............................. 1-7 Meta Character Processing ............................ 1-7 FSD Pseudo-character Device Support ..................... 1-7 Family API Issues .................................. 1-7 FSD Utilities . 1-7 FSD Utility Support ............................... 1-7 FSD Utility Guidelines .............................. 1-8 FSD Utility Interfaces .............................. 1-8 Extended Attributes . 1-8 FEAs . 1-9 GEAs . 1-10 FSD File Image .................................... 1-12 FSD Attribute . 1-12 FSD Initialization . 1-13 OS/2 and DOS Extended Boot Structure and BIOS Parameter Block ... 1-14 IFS Commands . 1-16 IFS = (CONFIG.SYS Command) ........................ 1-16 File System Function Calls ............................. 1-16 Application File I/O Notes ............................ 1-16 Date/Time Stamps . 1-17 I/O Error Codes ................................ 1-17 FSD System Interfaces ............................... 1-18 Overview . 1-18 Data Structures . 1-19 Time Stamping . 1-22 FSD Calling Conventions and Requirements ................. 1-22 Error Codes . 1-23 Chapter 2. FS Service Routines .......................... 2-1 FS_ALLOCATEPAGESPACE Adjust the size of paging file .......... 2-3 FS_ATTACH Attach to an FSD .......................... 2-4 FS_CANCELLOCKREQUEST Cancel file record lock request ........ 2-6 FS_CHDIR Change/Verify Directory Path .................... 2-7 FS_CHGFILEPTR Move a file's position pointer ............... 2-10 FS_CLOSE Close a file. ............................. 2-12 FS_COMMIT Commit a file's buffers to Disk .................. 2-13 FS_COPY Copy a file ............................... 2-15 FS_DELETE Delete a file ............................ 2-17 FS_DOPAGEIO Perform paging I/O operations ................ 2-18 FS_EXIT End of process ............................. 2-20 Copyright IBM Corp. 1991 iii FS_FILEATTRIBUTE Query/Set File Attribute ................. 2-21 FS_FILEINFO Query/Set a File's Information ................. 2-23 FS_FILEIO Multi-function file I/O ........................ 2-26 FS_FILELOCKS Request a file record lock/unlock .............. 2-29 FS_FINDCLOSE Directory Read (Search) Close ............... 2-32 FS_FINDFIRST Find First Matching File Name(s) .............. 2-33 FS_FINDFROMNAME Find matching file name(s) starting from name ... 2-37 FS_FINDNEXT Find next matching file name. ................. 2-39 FS_FINDNOTIFYCLOSE Close Find-Notify Handle ............. 2-41 FS_FINDNOTIFYFIRST Monitor a directory for changes. .......... 2-42 FS_FINDNOTIFYNEXT Resume reporting directory changes ........ 2-44 FS_FLUSHBUF Commit file buffers ....................... 2-46 FS_FSCTL File System Control ......................... 2-47 FS_FSINFO File System Information ...................... 2-50 FS_INIT File system driver initialization .................... 2-51 FS_IOCTL I/O Control for Devices ....................... 2-52 FS_MKDIR Make Subdirectory ......................... 2-54 FS_MOUNT Mount/unmount volumes ..................... 2-56 FS_MOVE Move a file or subdirectory ..................... 2-58 FS_NEWSIZE Change File's Logical Size ................... 2-60 FS_NMPIPE Do a remote named pipe operation. .............. 2-61 FS_OPENCREATE Open a file ......................... 2-65 FS_OPENPAGEFILE Create paging file and handle ............. 2-68 FS_PATHINFO Query/Set a File's Information ................ 2-70 FS_PROCESSNAME Allow FSD to modify name after OS/2 canonicalization . 2-72 FS_READ Read from a File ........................... 2-73 FS_RMDIR Remove Subdirectory ........................ 2-75 FS_SETSWAP Notification of swap-file ownership .............. 2-76 FS_SHUTDOWN Shutdown file system .................... 2-77 FS_VERIFYUNCNAME Verify UNC server ownership ............ 2-79 FS_WRITE Write to a file ............................. 2-80 Chapter 3. FS Helper Functions .......................... 3-1 FSH_ADDSHARE Add a name to the share set ................ 3-3 FSH_CALLDRIVER Call Device Driver's Extended Strategy entry point ... 3-5 FSH_CANONICALIZE Convert a path name to a canonical form ....... 3-7 FSH_CHECKEANAME Check for valid EA name ................ 3-9 FSH_CRITERROR Signal hard error to daemon ............... 3-10 FSH_DEVIOCTL Send IOCTL request to device driver ........... 3-12 FSH_DOVOLIO Transfer volume-based sector-oriented I/O ......... 3-14 FSH_DOVOLIO2 Send volume-based IOCTL request to device driver .. 3-17 FSH_EXTENDTIMESLICE Notify kernel that temporarily increasing this thread's time slice is advisable. ........................ 3-19 FSH_FINDCHAR Find first occurrence of character in string ........ 3-20 FSH_FINDDUPHVPB Locate equivalent hVPB ................ 3-21 FSH_FORCENOSWAP Force segments permanently into memory .... 3-22 FSH_GETPRIORITY Get current thread's I/O priority ............ 3-24 FSH_GETVOLPARM Get VPB data from VPB handle ............ 3-25 FSH_INTERR Signal an internal error ..................... 3-26 FSH_IOBOOST Gives the current thread an I/O priority boost ....... 3-27 FSH_IOSEMCLEAR Clear an I/O event semaphore ............. 3-28 FSH_ISCURDIRPREFIX Test for a prefix of a current directory ...... 3-29 FSH_LOADCHAR Load a character from a string .............. 3-30 iv DRAFT: OS/2 Installable File Systems FSH_NAMEFROMSFN Get the full path name from an SFN. ........ 3-31 FSH_PREVCHAR Decrement a character pointer .............. 3-32 FSH_PROBEBUF Check user address validity ................ 3-33 FSH_QSYSINFO Query system information .................. 3-35 | FSH_QUERYOPLOCK Query if the running thread has an oplock ..... 3-37 | FSH_QUERYSERVERTHREAD Query if the current thread is a server | thread . 3-38 FSH_REGISTERPERFCTRS Register a FSD with PERFVIEW ....... 3-39 FSH_REMOVESHARE Remove a shared entry ................ 3-40 FSH_SEGALLOC Allocate a GDT or LDT segment ............. 3-41 FSH_SEGFREE Release a GDT or LDT segment .............. 3-43 FSH_SEGREALLOC Change segment size .................. 3-44 FSH_SEMCLEAR Clear a semaphore ..................... 3-45 FSH_SEMREQUEST Request a semaphore ................. 3-46 FSH_SEMSET Set a semaphore ........................ 3-48 FSH_SEMSETWAIT Set a semaphore and wait for clear .......... 3-49 FSH_SEMWAIT Wait for clear .......................... 3-50 FSH_SETVOLUME Force a volume to be mounted on the drive ...... 3-51 FSH_STACKSPACE Determin stack space .................. 3-52 FSH_STORECHAR Store a character in a string ............... 3-53 FSH_UPPERCASE Uppercase asciiz string .................. 3-54 FSH_WILDMATCH Match using OS/2 wildcards ............... 3-55 FSH_YIELD Yield processor to higher-priority thread ............. 3-56 Chapter 4. Remote IPL / Bootable IFS ...................... 4-1 Operational Description . 4-2 FAT Boot Procedure ................................ 4-2 BIFS Boot Procedure ................................ 4-3 Interfaces . 4-4 BlackBox/OS2LDR interface . 4-4 miniFSD/OS2KRNL interface . 4-5 Stage 1 Interfaces ................................ 4-6 Stage 2 Interfaces ................................ 4-7 Stage 3 Interfaces ...............................