235 lines
6.3 KiB
Plaintext
235 lines
6.3 KiB
Plaintext
'\"! tbl | mmdoc
|
|
'\"macro stdmacro
|
|
.if n .pH g3c.lockf @(#)lockf 30.8 of 3/25/86
|
|
.nr X
|
|
.Op c p a
|
|
.if \nX=0 .ds x} LOCKF 3C "C Programming Language Utilities" "\&"
|
|
.if \nX=1 .ds x} LOCKF 3C "C Programming Language Utilities"
|
|
.if \nX=2 .ds x} LOCKF 3C "" "\&"
|
|
.if \nX=3 .ds x} LOCKF "" "" "\&"
|
|
.Op
|
|
.Op f
|
|
.if \nX=0 .ds x} LOCKF 3F "Fortran Programming Language Utilities" "\&"
|
|
.if \nX=1 .ds x} LOCKF 3F "Fortran Programming Language Utilities"
|
|
.if \nX=2 .ds x} LOCKF 3F "" "\&"
|
|
.if \nX=3 .ds x} LOCKF "" "" "\&"
|
|
.Op
|
|
.TH \*(x}
|
|
.SH NAME
|
|
lockf \- record locking on files
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.PP
|
|
.B "int lockf (int fildes, int function, off_t size);"
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.PP
|
|
.B "integer size"
|
|
.br
|
|
.B "external function"
|
|
.br
|
|
.B "integer function"
|
|
.br
|
|
.B "lockf (lun, function, size)"
|
|
.Op
|
|
.SH DESCRIPTION
|
|
The \f2lockf\f1 command will allow sections of a file
|
|
to be locked; advisory or mandatory write locks depending
|
|
on the mode bits of the file [see \f2chmod\f1(2)].
|
|
Locking calls from other processes which attempt
|
|
to lock the locked file section will
|
|
either return an error value or be put to sleep until the resource
|
|
becomes unlocked.
|
|
All the locks for a process are removed when the process terminates.
|
|
[See \f2fcntl\f1(2) for more information about record locking.]
|
|
.PP
|
|
.Op c p a
|
|
\f2Fildes\f1 is an open file descriptor.
|
|
The file descriptor must have
|
|
.SM O_WRONLY
|
|
or
|
|
.SM O_RDWR
|
|
permission in order to establish lock with this function call.
|
|
.Op
|
|
.Op f
|
|
\f2lun\f1 is an open logical unit.
|
|
The logical unit must not have been opened \f2READONLY\f1
|
|
in order to establish lock with this function call.
|
|
.Op
|
|
.PP
|
|
\f2Function\f1 is a control value which specifies the action to be taken.
|
|
The permissible values for \f2function\f1 are defined in \f3<unistd.h>\f1
|
|
as follows:
|
|
.br
|
|
.sp
|
|
.TS
|
|
l l l l.
|
|
#define F_ULOCK 0 /\(** Unlock a previously locked section \(**/
|
|
#define F_LOCK 1 /\(** Lock a section for exclusive use \(**/
|
|
#define F_TLOCK 2 /\(** Test and lock a section for exclusive use \(**/
|
|
#define F_TEST 3 /\(** Test section for other processes locks \(**/
|
|
.TE
|
|
.sp
|
|
.PP
|
|
All other values of \f2function\f1 are reserved for future extensions and will
|
|
result in an error return if not implemented.
|
|
.PP
|
|
.SM F_TEST
|
|
is used to detect if a lock by another process is
|
|
present on the specified section.
|
|
.SM F_LOCK
|
|
and
|
|
.SM F_TLOCK
|
|
both lock a section of a file if the section is available.
|
|
.SM F_ULOCK
|
|
removes locks from a section of the file.
|
|
.PP
|
|
\f2Size\f1 is the number of contiguous bytes to be locked or unlocked.
|
|
The resource to be locked starts at the current offset in the file and extends forward
|
|
for a positive size and backward for a negative size (the preceding bytes up to but
|
|
not including the current offset).
|
|
If \f2size\f1 is zero, the section from the current offset through the largest file
|
|
offset is locked (i.e., from the current offset through the
|
|
present or any future end-of-file).
|
|
An area need not be allocated to the file in order to be locked as such locks
|
|
may exist past the end-of-file.
|
|
.PP
|
|
The sections locked with
|
|
.SM F_LOCK
|
|
or
|
|
.SM F_TLOCK
|
|
may, in whole or in part,
|
|
contain or be contained by a previously locked section for the same process.
|
|
When this occurs,
|
|
or if adjacent sections occur,
|
|
the sections are combined into a single section.
|
|
If the request requires that a new element be added to the table of active
|
|
locks and this table is already full,
|
|
an error is returned,
|
|
and the new section is not locked.
|
|
.PP
|
|
.SM F_LOCK
|
|
and
|
|
.SM F_TLOCK
|
|
requests differ only by the action taken if the resource
|
|
is not available.
|
|
.SM F_LOCK
|
|
will cause the calling process to sleep until the resource is available.
|
|
.SM F_TLOCK
|
|
will cause the function to return
|
|
.Op c p a
|
|
a \-1
|
|
.Op
|
|
.Op f
|
|
an error
|
|
.Op
|
|
and set
|
|
\f2errno\f1 to
|
|
.SM [EACCES]
|
|
error if the section is already locked by another process.
|
|
.PP
|
|
.SM F_ULOCK
|
|
requests may, in whole or in part,
|
|
release one or more locked sections controlled by the process.
|
|
When sections are not fully released,
|
|
the remaining sections are still locked by the process.
|
|
Releasing the center section of a locked section requires an additional element in the table
|
|
of active locks.
|
|
If this table is full,
|
|
an
|
|
.SM [EDEADLK]
|
|
error is returned and the requested section is not released.
|
|
.PP
|
|
A potential for deadlock occurs if a process controlling a locked
|
|
resource is put to sleep by accessing another process's locked resource.
|
|
Thus calls to \f2lockf\f1 or \f2fcntl\f1 scan
|
|
for a deadlock prior to sleeping on a locked resource.
|
|
An error return is made if sleeping on the locked resource would cause a deadlock.
|
|
.PP
|
|
Sleeping on a resource is interrupted with any signal.
|
|
The \f2alarm\f1(2) command may be used to provide a timeout facility
|
|
in applications which require this facility.
|
|
.PP
|
|
The \f2lockf\f1 utility will fail if one or more of the following are true:
|
|
.br
|
|
.sp
|
|
.TP
|
|
.SM [EBADF]
|
|
.Op c p a
|
|
\f2Fildes\f1
|
|
.Op
|
|
.Op f
|
|
\f2lun\f1
|
|
.Op
|
|
is not a valid open file.
|
|
.TP
|
|
.SM [EACCES]
|
|
\f2Cmd\f1 is
|
|
.SM F_TLOCK
|
|
or
|
|
.SM F_TEST
|
|
and the section is already locked by another process.
|
|
.TP
|
|
.SM [EDEADLK]
|
|
\f2Cmd\f1 is
|
|
.SM F_LOCK
|
|
and a deadlock would occur.
|
|
Also the \f2cmd\f1 is either
|
|
.SM F_LOCK,
|
|
.SM F_TLOCK,
|
|
or
|
|
.SM F_ULOCK
|
|
and the number of entries in the lock table
|
|
would exceed the number allocated on the system.
|
|
.SH NOTES
|
|
Locks are on files, not file descriptors. That is, file descriptors
|
|
duplicated through
|
|
.IR dup (3C)
|
|
do not result in multiple instances of locks, but rather multiple
|
|
references to the same locks.
|
|
Thus if any of the descriptors associated with the same file are closed,
|
|
the locks associated with the file are lost.
|
|
.SH SEE ALSO
|
|
chmod(2),
|
|
close(2),
|
|
creat(2),
|
|
fcntl(2),
|
|
intro(2),
|
|
open(2),
|
|
.Op f
|
|
perror(3F),
|
|
.Op
|
|
read(2),
|
|
write(2).
|
|
.SH DIAGNOSTICS
|
|
Upon successful completion,
|
|
a value of 0 is returned.
|
|
Otherwise, a
|
|
.Op c p a
|
|
value of \-1
|
|
.Op
|
|
.Op f
|
|
nonzero value
|
|
.Op
|
|
is returned and \f2errno\f1 is set to
|
|
indicate the error.
|
|
.SH WARNINGS
|
|
Unexpected results may occur in processes that do buffering
|
|
in the user address space.
|
|
The process may later read/write data which is/was locked.
|
|
The standard I/O package is the most common source of
|
|
unexpected buffering.
|
|
.sp
|
|
Because in the future the variable \f2errno\f1 will be
|
|
set to
|
|
.SM EAGAIN
|
|
rather than
|
|
.SM EACCES
|
|
when a section of a file is already locked by another process,
|
|
portable application programs should expect and test for either value.
|
|
'\".so /pubs/tools/origin.att
|
|
.Ee
|