Name
locking - Sets read and write permissions for a portion of a
file.
Syntax
#include <sys/locking.h>
#include <io.h>
int locking(handle, mode, nbyte)
int handle;
int mode;
long nbyte;
Description
The locking function locks or unlocks nbyte bytes of the
file specified by handle. Locking bytes in a file prevents
subsequent reading and writing of those bytes by other
processes. Unlocking a file permits other processes to read
or write to previously locked bytes. All locking or
unlocking begins at the current position of the file pointer
and proceeds for the next nbyte bytes, or to the end of the
file.
Note that under DOS Versions 3.0 and 3.1, the files locked
by a parent process may become unlocked when one of its
children exits.
Notes
The locking function should be used only under OS/2 or 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.
The argument mode 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, tries again
after 1 second. If, after 10
attempts, the bytes cannot be
locked, returns an error.
LK_RLCK Same as LK_LOCK.
LK_NBLCK Locks the specified bytes. If bytes
cannot be locked, returns an error.
LK_NBRLCK Same as LK_NBLCK.
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 unlocking a file, the region of the file being unlocked
must correspond to a region that was previously locked. The
locking function does not merge adjacent regions, so if two
locked regions are adjacent, each region must be unlocked
separately.
Regions should be unlocked before closing a file or exiting
the program.
Return Value
The locking function returns 0 if it is 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.
See Also
creat(DOS), open(DOS)
Example
#include <io.h> #include <sys/types.h> #include <sys/stat.h>
#include <fcntl.h> #include <stdio.h> #include
<sys/locking.h> #include <stdlib.h>
extern unsigned char _osmajor; int fh; long pos; char
buffer[ BUFSIZ ];
main()
{
int result;
/* save the current file pointer position,
** then lock a region from the beginning of
** the file to the saved file pointer
** position
*/
/* Open file; read 10 bytes: */
fh = open("data", O_RDONLY);
result = read(fh, buffer, 10) ;
/* Check for DOS version >= 3.0 */
if (_osmajor >= 3)
{
/* Get current pointer position*/
pos = tell(fh);
/* Reset pointer to beginning of file: */
result = lseek(fh, 0L, SEEK_SET);
/* Lock first portion of the file: */
if ((locking(fh, LK_NBLCK, pos)) != -1)
{
printf("Successfully locked %d
bytes\n", pos);
lseek(fh, 0L, 0 );
locking(fh, LK_UNLCK, pos);
}
else
perror("Locking failed");
}
else
printf( "DOS version must be 3, or later.\n"
);
}
This program opens a file named data and reads the first
10 bytes from the file. It then moves the file pointer back
to the beginning of the file and uses locking to lock the
first 10 bytes of the file.
Note that this program works correctly only if the following
conditions are met:
+ The file named data exists.
+ SHARE.COM or SHARE.EXE is installed.
+ The program is run under DOS Versions 3.0 and later.
(printed 6/18/89)