Locks or unlocks bytes of a file.
#include <sys\locking.h>
| #include <io.h> | Required only for function declarations |
int _locking( int handle, int mode, long nbytes);
| handle | File handle | |
| mode | File-locking mode | |
| nbytes | Number of bytes to lock |
The _locking function locks or unlocks nbytes bytes of the file specified by handle. Locking bytes in a file prevents access to those bytes by other processes. All locking or unlocking begins at the current position of the file pointer and proceeds for the next nbytes bytes. It is possible to lock bytes past the end of the file.
The mode argument specifies the locking action to be performed. It must be one of the following manifest constants:
| Constant | Action |
| _LK_LOCK | Locks the specified bytes. If the bytes cannot be locked, immediately tries again after 1 second. If, after 10 attempts, the bytes cannot be locked, returns an error. |
| _LK_NBLCK | Locks the specified bytes. If bytes cannot be locked, returns an error. |
| _LK_NBRLCK | Same as _LK_NBLCK. |
| _LK_RLCK | Same as _LK_LOCK. |
| _LK_UNLCK | Unlocks the specified bytes. (The bytes must have been previously locked.) |
More than one region of a file can be locked, but no overlapping regions are allowed.
When a region of a file is being unlocked, it must correspond to a region that was previously locked. The _locking function does not merge adjacent regions; if two locked regions are adjacent, each region must be unlocked separately.
Regions should be locked only briefly and should be unlocked before closing a file or exiting the program.
The _locking function should be used only with DOS versions 3.0 and later; it has no effect under earlier versions of DOS. Also, file sharing must be loaded to use the _locking function. Note that with DOS versions 3.0 and 3.1, the files locked by parent processes may become unlocked when child processes exit.
The _locking function returns 0 if successful. A return value of –1 indicates failure, and errno is set to one of the following values:
| Value | Meaning |
| EACCES | Locking violation (file already locked or unlocked). |
| EBADF | Invalid file handle. |
| EDEADLOCK | Locking violation. This is returned when the _LK_LOCK or _LK_RLCK flag is specified and the file cannot be locked after 10 attempts. |
| EINVAL | An invalid argument was given to the function. |
Standards:UNIX
16-Bit:DOS, QWIN, WIN, WIN DLL
32-Bit:DOS32X
Use _locking for compatibility with ANSI naming conventions of non-ANSI functions. Use locking and link with OLDNAMES.LIB for UNIX compatibility.
/* LOCKING.C: This program opens a file with sharing. It locks some
* bytes before reading them, then unlocks them. Note that the program
* works correctly only if the following conditions are met:
* - The file exists
* - The program is run with DOS version 3.0 or later
* with file sharing installed (SHARE.COM or SHARE.EXE), or
* if a Microsoft Networks compatible network is running
*/
#include <io.h>
#include <sys\types.h>
#include <sys\stat.h>
#include <sys\locking.h>
#include <share.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
void main( void )
{
int fh, numread;
long pos, result;
char buffer[40];
/* Quit if can't open file or DOS version doesn't support sharing. */
fh = _sopen( "locking.c", _O_RDWR, _SH_DENYNO, _S_IREAD | _S_IWRITE );
if( (fh == -1) || (_osmajor < 3) )
exit( 1 );
/* Lock some bytes and read them. Then unlock. */
if( _locking( fh, LK_NBLCK, 30L ) != -1 )
{
printf( "No one can change these bytes while I'm reading them\n" );
numread = _read( fh, buffer, 30 );
printf( "%d bytes read: %.30s\n", numread, buffer );
_locking( fh, LK_UNLCK, 30L );
printf( "Now I'm done. Do what you will with them\n" );
}
else
perror( "Locking failed\n" );
_close( fh );
}
No one can change these bytes while I'm reading them
30 bytes read: /* LOCKING.C: This program open
Now I'm done. Do what you will with them