Purpose

Perform multiple lock, unlock, seek, read, and write I/O.

Calling Sequence

int far pascal FS_FILEIO (psffsi, psffsd, pCmdList, cbCmdList, poError,
                          IOflag)
 
struct sffsi far * psffsi;
struct sffsd far * psffsd;
char far * pCmdList;
unsigned short cbCmdList;
unsigned short far * poError;
unsigned short IOflag;

Where

psffsi is a pointer to the file-system-independent portion of an open file instance.

psffsd is a pointer to the file-system-dependent portion of an open file instance.

pCmdList is a pointer to a command list that contains entries indicating what commands will be performed.

Each individual operation (CmdLock, CmdUnlock, CmdSeek, CmdIO) is performed as atomic operations until all are complete or until one fails. CmdLock executes a multiple range lock as an atomic operation. CmdUnlock executes a multiple range unlock as an atomic operation. Unlike CmdLock, CmdUnlock cannot fail as long as the parameters to it are correct, and the calling application had done a Lock earlier, so it can be viewed as atomic.

The validity of the user address is not verified (see FSH_PROBEBUF).

For CmdLock, the command format is:

struct CmdLock {
    unsigned short Cmd = 0;   /* 0 for lock operations         */
    unsigned short LockCnt;   /* number of locks that follow   */
    unsigned long  TimeOut;   /* ms time-out for lock success  */
}

which is followed by a series of records of the following format:

struct Lock {
    unsigned short Share = 0;   /* 0 for exclusive, 1 for read-only  */
    long           Start;       /* start of lock region              */
    long           Length;      /* length of lock region             */
}

If a lock within a CmdLock causes a time-out, none of the other locks within the scope of CmdLock are in force, because the lock operation is viewed as atomic.

CmdLock. TimeOut is the count in milliseconds, until the requesting process is to resume execution if the requested locks are not available. If CmdLock. TimeOut == 0, there will be no wait. If CmdLock. TimeOut < 0xFFFFFFFF it is the number of milliseconds to wait until the requested locks become available. If CmdLock. TimeOut == 0xFFFFFFFF then the thread will wait indefinitely until the requested locks become available.

Lock.Share defines the type of access other processes may have to the file-range being locked. If its value == 0, other processes have No-Access to the locked range. If its value == 1, other process have Read-Only access to the locked range.

For CmdUnlock, the command format is:

struct CmdUnlock {
    unsigned short Cmd = 1;     /* 1 for unlock operations        */
    unsigned short UnlockCnt;   /* Number of unlocks that follow  */
}

which is followed by a series of records of the following format:

struct UnLock {
    long Start;                 /* start of locked region         */
    long Length;                /* length of locked region        */
}

For CmdSeek, the command format is:

struct CmdSeek {
    unsigned short Cmd = 2;   /* 2 for seek operation         */
    unsigned short Method;    /* 0 for absolute               */
                              /* 1 for relative to current    */
                              /* 2 for relative to EOF        */
    long           Position;  /* file seek position or delta  */
    long           Actual;    /* actual position seeked to    */
}

For CmdIO, the command format is:

struct CmdIO {
    unsigned short Cmd;        /* 3 for read, 4 for write      */
    void far * Buffer;         /* pointer to the data buffer   */
    unsigned short BufferLen;  /* number of bytes requested    */
    unsigned short Actual;     /* number of bytes transferred  */
}

cbCmdList is the length in bytes of the command list.

poError is the offset within the command list of the command that caused the error.

This field has a value only when an error occurs.

The validity of the user address has not been verified (see FSH_PROBEBUF).

Remarks

This function provides a simple mechanism for combining the file I/O operations into a single request and providing improved performance, particularly in a networking environment.

File systems that do not have the FileIO bit in their attribute field do not see this call: The command list is parsed by the IFS router. The FSD sees only FS_CHGFILEPTR, FS_READ, FS_WRITE calls.

File systems that have the FileIO bit in their attribute field see this call in its entirety. The atomicity guarantee applies only to the commands themselves and not to the list as a whole.

Of the information passed in IOflag, the write-through bit is a mandatory bit in that any data written to the block device must be put out on the medium before the device driver returns. The no-cache bit, on the other hand, is an advisory bit that says whether the data being transferred is worth caching or not.