Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosFileLocks(hf, pfUnlock, pfLock)
HFILE hf;              /* file handle                     */
PFILELOCK pfUnLock;    /* pointer to range to be unlocked */
PFILELOCK pfLock;      /* pointer to range to be locked   */
 
The DosFileLocks function unlocks and/or locks a region in an open file.
Locking a region prevents other processes from accessing the locked region.
 
The DosFileLocks function is a family API function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hf         Identifies the file handle. This handle must have been created
           previously by using the DosOpen function.
 
pfUnLock   Points to the FILELOCK structure that specifies the starting
           position in the file and the number of bytes of the file to
           unlock. This parameter is ignored if NULL is specified instead of
           a structure address.
 
pfLock     Points to the FILELOCK structure that specifies the starting
           position in the file and the number of bytes of the file to lock.
           This parameter is ignored if NULL is specified instead of a
           structure address.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_INVALID_HANDLE
     ERROR_LOCK_VIOLATION
 
Comments
 
The DosFileLocks function can both lock and unlock regions. The system
unlocks any specified region before locking any other region. Locked regions
can overlap, but if one region would entirely encompass another, the smaller
region should be unlocked first. The DosFileLocks function can lock any part
of a file. Attempting to lock bytes beyond the end of a file does not result
in an error.
 
Example
 
This example opens the file abc and calls the DosFileLocks function to lock
100 bytes of the file, starting with byte number three. No other file may
read or write to this range in the file until DosFileLocks is called to
unlock the range or the file is closed. The same structure is used to lock
the file and to unlock the file.
 
FILELOCK flock;
HFILE hf;
USHORT usAction;
 
/* open the file */
 
DosOpen("abc",                            /* filename to open       */
    &hf,                                  /* address of file handle */
    &usAction,                            /* action taken           */
    100L,                                 /* size of new file       */
    FILE_NORMAL,                          /* file attribute         */
    FILE_OPEN,                            /* open if file exists    */
    OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE   /* open mode      */
    0L);                                          /* reserved       */
 
flock.lOffset = 3L;               /* offset to begin lock           */
flock.lRange = 100L;              /* range to lock                  */
DosFileLocks(hf,                  /* handle of file to lock         */
    (PFILELOCK) NULL,             /* unlock range (NULL to disable) */
    &flock);                      /* address of lock range          */
    .
    . /* other file processing occurs here */
    .
DosFileLocks(hf,                  /* handle of file to unlock       */
    &flock,                       /* address of unlock range        */
    (PFILELOCK) NULL);            /* lock range (NULL to disable)   */
 
See Also
 
DosDupHandle, DosExecPgm, DosOpen, FILELOCK
 
                                      ♦