_locking
Locks or unlocks bytes of a file.
int _locking(
int fd,
int mode,
long nbytes
);
fd
File descriptor.
mode
Locking action to perform.
nbytes
Number of bytes to lock.
_locking
returns 0 if successful. A return value of -1 indicates failure, in which case errno
is set to one of the following values.
errno value |
Condition |
---|---|
EACCES |
Locking violation (file already locked or unlocked). |
EBADF |
Invalid file descriptor. |
EDEADLOCK |
Locking violation. Returned when the _LK_LOCK or _LK_RLCK flag is specified and the file can't be locked after 10 attempts. |
EINVAL |
An invalid argument was given to _locking . |
If the failure is due to a bad parameter, such as an invalid file descriptor, the invalid parameter handler is invoked, as described in Parameter validation.
The _locking
function locks or unlocks nbytes
bytes of the file specified by fd
. 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's possible to lock bytes past end of file.
mode
must be one of the following manifest constants, which are defined in Locking.h.
mode value |
Effect |
---|---|
_LK_LOCK |
Locks the specified bytes. If the bytes can't be locked, the program immediately tries again after 1 second. If the bytes can't be locked after 10 attempts, the constant returns an error. |
_LK_NBLCK |
Locks the specified bytes. If the bytes can't be locked, the constant returns an error. |
_LK_NBRLCK |
Same as _LK_NBLCK . |
_LK_RLCK |
Same as _LK_LOCK . |
_LK_UNLCK |
Unlocks the specified bytes, which must have been previously locked. |
Multiple regions of a file that don't overlap can be locked. A region being unlocked must have been previously locked. _locking
doesn't 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.
By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.
Routine | Required header | Optional header |
---|---|---|
_locking |
<io.h> and <sys/locking.h> | <errno.h> |
For more compatibility information, see Compatibility.
All versions of the C run-time libraries.
// crt_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 file exists.
*/
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/locking.h>
#include <share.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <io.h>
int main( void )
{
int fh, numread;
char buffer[40];
/* Quit if can't open file or system doesn't
* support sharing.
*/
errno_t err = _sopen_s( &fh, "crt_locking.txt", _O_RDONLY, _SH_DENYNO,
_S_IREAD | _S_IWRITE );
printf( "%d %d\n", err, fh );
if( err != 0 )
exit( 1 );
/* Lock some bytes and read them. Then unlock. */
if( _locking( fh, LK_NBLCK, 30L ) != -1 )
{
long lseek_ret;
printf( "No one can change these bytes while I'm reading them\n" );
numread = _read( fh, buffer, 30 );
buffer[30] = '\0';
printf( "%d bytes read: %.30s\n", numread, buffer );
lseek_ret = _lseek( fh, 0L, SEEK_SET );
_locking( fh, LK_UNLCK, 30L );
printf( "Now I'm done. Do what you will with them\n" );
}
else
perror( "Locking failed\n" );
_close( fh );
}
The first thirty bytes of this file will be locked.
No one can change these bytes while I'm reading them
30 bytes read: The first thirty bytes of this
Now I'm done. Do what you will with them