997 lines
28 KiB
Groff
997 lines
28 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.fcntl @(#)fcntl 30.11 of 3/31/86
|
|
.TH FCNTL 2
|
|
.SH NAME
|
|
fcntl \- file and descriptor control
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.br
|
|
.B #include <fcntl.h>
|
|
.sp .5
|
|
.br
|
|
.B "int fcntl (int fildes, int cmd, ... /\(** arg \(**/);"
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
.B "integer *4 function fcntl (fildes, cmd [, arg ])"
|
|
.br
|
|
.B "integer *4 fildes, cmd, arg"
|
|
.br
|
|
.B "TYPE arg"
|
|
.br
|
|
.in +.5i
|
|
Note: the type of \fBarg\fP varies by cmd.
|
|
.in -0.5i
|
|
.Op
|
|
.SH DESCRIPTION
|
|
.I fcntl\^
|
|
provides for control over open descriptors.
|
|
.I fildes\^
|
|
is an open
|
|
descriptor
|
|
obtained from a
|
|
.IR creat ,
|
|
.IR open ,
|
|
.IR dup ,
|
|
.IR fcntl ,
|
|
.IR pipe ,
|
|
.IR socket ,
|
|
or
|
|
.IR socketpair\^
|
|
system call.
|
|
.PP
|
|
The commands available are:
|
|
.TP 1.0i
|
|
.SM \f3F_DUPFD\f1
|
|
Return a new
|
|
descriptor
|
|
as follows:
|
|
.IP
|
|
Lowest numbered available
|
|
descriptor
|
|
greater than or equal to the third argument,
|
|
.IR arg ,
|
|
taken as an object of type
|
|
.Op c p a
|
|
int.
|
|
.Op
|
|
.Op f
|
|
integer *4.
|
|
.Op
|
|
.IP
|
|
Refers to the same object as the original descriptor.
|
|
.IP
|
|
Same file pointer as the original file
|
|
(i.e., both file descriptors share one
|
|
file pointer).
|
|
.IP
|
|
Same access mode (read, write or read/write).
|
|
.IP
|
|
Same descriptor status flags (i.e., both descriptors share the same
|
|
status flags).
|
|
.IP
|
|
Shares any locks associated with the original file descriptor.
|
|
.IP
|
|
The close-on-exec flag,
|
|
.SM
|
|
.B FD_CLOEXEC
|
|
associated with the new descriptor is cleared to keep the file open across
|
|
calls to the
|
|
.IR exec (2)
|
|
family of functions.
|
|
.TP
|
|
.SM \f3F_GETFD\f1
|
|
Get the file descriptor flags associated with the descriptor
|
|
.IR fildes .
|
|
If the
|
|
.SM
|
|
.B FD_CLOEXEC
|
|
flag is
|
|
.B 0
|
|
the descriptor will remain open across
|
|
.IR exec ,
|
|
otherwise
|
|
the descriptor will be closed upon execution of
|
|
.IR exec .
|
|
.TP
|
|
.SM \f3F_SETFD\f1
|
|
Set the file descriptor flags for
|
|
.IR fildes .
|
|
Currently the only flag implemented is
|
|
.SM
|
|
.BR FD_CLOEXEC .
|
|
Note: this flag is a per-process and per-descriptor
|
|
flag; setting or clearing it for a particular
|
|
descriptor will not affect the flag on descriptors
|
|
copied from it by a
|
|
.IR dup (2)
|
|
or
|
|
.SM
|
|
.B F_DUPFD
|
|
operation, nor will it affect the flag on other processes
|
|
instances of that descriptor.
|
|
.TP
|
|
.SM \f3F_GETFL\f1
|
|
Get
|
|
.I file\^
|
|
status flags and file access modes.
|
|
The file access modes may be extracted from the return value using the
|
|
mask
|
|
.SM
|
|
.BR O_ACCMODE .
|
|
.TP
|
|
.SM \f3F_SETFL\f1
|
|
Set
|
|
.I file\^
|
|
status flags to the third argument,
|
|
.IR arg ,
|
|
taken as an object of type
|
|
.Op c p a
|
|
int.
|
|
.Op
|
|
.Op f
|
|
integer *4.
|
|
.Op
|
|
Only the following flags can be set
|
|
[see
|
|
.IR fcntl (5)]:
|
|
.SM
|
|
.BR FAPPEND ,
|
|
.SM
|
|
.BR FSYNC ,
|
|
.SM
|
|
.BR DSYNC ,
|
|
.SM
|
|
.BR RSYNC ,
|
|
.SM
|
|
.BR FNDELAY ,
|
|
.SM
|
|
.BR FNONBLK ,
|
|
.SM
|
|
.BR FLCFLUSH ,
|
|
.SM
|
|
.BR FLCINVAL ,
|
|
.SM
|
|
.BR FDIRECT ,
|
|
and
|
|
.SM
|
|
.BR FASYNC .
|
|
.SM
|
|
Since
|
|
.IR arg
|
|
is used as a bit vector to set the flags,
|
|
values for all the flags must be specified in
|
|
.IR arg.
|
|
(Typically,
|
|
.IR arg
|
|
may be constructed by obtaining existing values by
|
|
.SM \f3F_GETFL\f1
|
|
and then changing the particular flags.)
|
|
.B FAPPEND
|
|
is equivalent to
|
|
.SM
|
|
.BR O_APPEND ;\^
|
|
.SM
|
|
.B FSYNC
|
|
is equivalent to
|
|
.SM
|
|
.BR O_SYNC ;\^
|
|
.SM
|
|
.B FDSYNC
|
|
is equivalent to
|
|
.SM
|
|
.BR O_DSYNC ;\^
|
|
.SM
|
|
.B FRSYNC
|
|
is equivalent to
|
|
.SM
|
|
.BR O_RSYNC ;\^
|
|
.SM
|
|
.B FNDELAY
|
|
is equivalent to
|
|
.SM
|
|
.BR O_NDELAY ;\^
|
|
.SM
|
|
.B FNONBLK
|
|
is equivalent to
|
|
.SM
|
|
.BR O_NONBLOCK ;\^
|
|
.SM
|
|
.B FLCFLUSH
|
|
is equivalent to
|
|
.SM
|
|
.BR O_LCFLUSH ;\^
|
|
.SM
|
|
.B FLCINVAL
|
|
is equivalent to
|
|
.BR O_LCINVAL ;\^
|
|
.SM
|
|
and
|
|
.SM
|
|
.B FDIRECT
|
|
is equivalent to
|
|
.SM
|
|
.BR O_DIRECT .
|
|
.SM
|
|
.B FASYNC
|
|
is equivalent to calling
|
|
.I ioctl
|
|
with the
|
|
.SM
|
|
.B FIOASYNC
|
|
command (except that with
|
|
.I ioctl
|
|
all flags need not be specified).
|
|
This enables the
|
|
.SM
|
|
.B SIGIO
|
|
facilities
|
|
and is currently supported only on sockets.
|
|
.sp
|
|
Since the descriptor status flags are shared with descriptors
|
|
copied from a given descriptor by a
|
|
.IR dup (2)
|
|
or
|
|
.SM
|
|
.B F_DUPFD
|
|
operation, and by other processes instances of that descriptor
|
|
a
|
|
.SM
|
|
.B F_SETFL
|
|
operation will affect those other descriptors and other instances of the
|
|
given descriptors as well.
|
|
For example, setting or clearing the
|
|
.SM
|
|
.B FNDELAY
|
|
flag will logically cause an
|
|
.SM
|
|
.B FIONBIO
|
|
.IR ioctl (2)
|
|
to be performed on the object referred to by that descriptor.
|
|
Thus all descriptors referring to that object will be affected.
|
|
.sp
|
|
Flags not understood for a particular descriptor are silently ignored
|
|
except for \f3FDIRECT\fP. \f3FDIRECT\fP will return \f2EINVAL\fP if used
|
|
on other than an EFS, XFS or BDS file system file.
|
|
.TP
|
|
.SM \f3F_FREESP\f1
|
|
Alter storage space associated with a section of the
|
|
ordinary file \f2fildes\fP.
|
|
The section is specified by a variable of data type
|
|
\f2struct flock\fP pointed to by the third argument \f2arg\fP.
|
|
.Op f
|
|
In Fortran, pass a variable of type RECORD.
|
|
.Op
|
|
The data type \f2struct flock\fP is defined in the
|
|
\f2<fcntl.h>\fP header file [see \f2fcntl\fP(5)] and contains the following members:
|
|
\f2l_whence\fP is 0, 1, or 2 to indicate that the
|
|
relative offset \f2l_start\fP will be measured from the
|
|
start of the file, the current position, or the end of the file,
|
|
respectively.
|
|
\f2l_start\fP is the offset from the position specified in \f2l_whence\fP.
|
|
\f2l_len\fP is the size of the section.
|
|
An \f2l_len\fP of 0 frees up to the
|
|
end of the file; in this case, the end of file (i.e., file size)
|
|
is set to the beginning of the section freed.
|
|
Any data previously written into this section is no longer accessible.
|
|
If the section specified is beyond the current end of file,
|
|
the file is grown and filled with zeroes.
|
|
The \f2l_len\fP field is currently ignored, and should be set to 0.
|
|
.TP
|
|
.SM \f3F_ALLOCSP\f1
|
|
This command is identical to
|
|
.SM \f3F_FREESP\f1.
|
|
.TP
|
|
.SM \f3F_FREESP64\f1
|
|
This command is identical to
|
|
.SM \f3F_FREESP\f1
|
|
except that the type of
|
|
the data referred to by the third argument \f2arg\fP is
|
|
a \f2struct flock64\fP. In this version of the structure,
|
|
\f2l_start\fP and \f2l_len\fP are of type \f3off64_t\fP instead of
|
|
\f3off_t\fP (64 bits instead of 32 bits).
|
|
.TP
|
|
.SM \f3F_ALLOCSP64\f1
|
|
This command is identical to
|
|
.SM \f3F_FREESP64\f1.
|
|
.TP
|
|
.SM \f3F_FSSETDM\f1
|
|
Set the \f2di_dmevmask\fP and \f2di_dmstate\fP fields
|
|
in an XFS on-disk inode.
|
|
The only legitmate values for these fields
|
|
are those previously returned in the
|
|
\f2bs_dmevmask\fP and \f2bs_dmstate\fP fields
|
|
of the \f2bulkstat\fP structure.
|
|
The data referred to by the third argument \f2arg\fP is
|
|
a \f2struct fsdmidata\fP.
|
|
This structure's members are \f2fsd_dmevmask\fP and \f2fsd_dmstate\fP.
|
|
The \f2di_dmevmask\fP field is set to the value in \f2fsd_dmevmask\fP.
|
|
The \f2di_dmstate\fP field is set to the value in \f2fsd_dmstate\fP.
|
|
This command is restricted to root
|
|
or to processes with device management capabilities.
|
|
Its sole purpose is to allow backup and restore programs
|
|
to restore the aforementioned critical on-disk inode fields.
|
|
.TP
|
|
.SM \f3F_DIOINFO\f1
|
|
Get information required to perform direct I/O on the specified \f2fildes\fP.
|
|
Direct I/O is performed directly to and from a user's data buffer. Since
|
|
the kernels buffer cache is no longer between the two, the user's data
|
|
buffer must conform to the same type of constraints as required for accessing
|
|
a raw disk partition.
|
|
The third argument, \f2arg\fP, points to a data type \f2struct dioattr\fP
|
|
.Op f
|
|
(In Fortran, pass a variable of type RECORD)
|
|
.Op
|
|
which is defined in the \f2<fcntl.h>\fP header file and contains the
|
|
following members: \f2d_mem\fP is the memory alignment requirement of
|
|
the user's data buffer.
|
|
\f2d_miniosz\fP specifies block size, minimum I/O request size, and
|
|
I/O alignment.
|
|
Ths size of all I/O requests must be a multiple of this amount and the
|
|
value of the seek pointer at the time of the I/O request
|
|
must also be an integer multiple of this amount.
|
|
\f2d_maxiosz\fP is the
|
|
maximum I/O request size which can be performed on the \f2fildes\fP.
|
|
If an I/O request does not meet these constraints, the \f2read\fP(2) or
|
|
\f2write\fP(2) will return with \f2EINVAL\fP. All I/O requests are kept
|
|
consistent with any data brought into the cache with an access through a
|
|
non-direct I/O file descriptor.
|
|
See also \f3F_SETFL\fP above and \f2open\fP (2).
|
|
.TP
|
|
.SM \f3F_GETOWN\f1
|
|
Used by sockets: get the process
|
|
.SM ID
|
|
or process group currently receiving
|
|
.SM
|
|
.B SIGIO
|
|
and
|
|
.SM
|
|
.B SIGURG
|
|
signals; process groups are returned as negative
|
|
values.
|
|
.TP
|
|
.SM \f3F_SETOWN\f1
|
|
Used by sockets: set the process or process group to receive SIGIO and
|
|
SIGURG signals; process groups are specified by supplying
|
|
.I arg
|
|
as negative, otherwise
|
|
.I arg
|
|
is interpreted as a process
|
|
.SM ID.
|
|
.TP
|
|
.SM \f3F_FSGETXATTR\f1
|
|
Get extended attributes associated with files in XFS file systems.
|
|
The \f2arg\fP points to a variable of type \f2struct fsxattr\fP.
|
|
The structure fields include:
|
|
\f2fsx_xflags\fP (extended flag bits),
|
|
\f2fsx_extsize\fP (nominal extent size in file system blocks),
|
|
\f2fsx_nextents\fP (number of data extents in the file),
|
|
\f2fsx_uuid\fP (file unique id).
|
|
Currently the only meaningful bits for the \f2fsx_xflags\fP field
|
|
are bit 0 (value 1), which if set means the file is a realtime file,
|
|
and bit 1 (value 2), which if set means the file has preallocated space.
|
|
A \f2fsx_extsize\fP value returned indicates that a preferred extent size
|
|
was previously set on the file, a \f2fsx_extsize\fP of 0 indicates that
|
|
the defaults for that filesystem will be used.
|
|
.TP
|
|
.SM \f3F_FSGETXATTRA\f1
|
|
Identical to
|
|
.SM \f3F_FSGETXATTR\f1
|
|
except that the \f2fsx_nextents\fP field contains the number
|
|
of attribute extents in the file.
|
|
.TP
|
|
.SM \f3F_FSSETXATTR\f1
|
|
Set extended attributes associated with files in XFS file systems.
|
|
The \f2arg\fP points to a variable of type \f2struct fsxattr\fP,
|
|
but only the following fields are used in this call:
|
|
\f2fsx_xflags\fP and
|
|
\f2fsx_extsize\fP.
|
|
The \f2fsx_xflags\fP realtime file bit, and the file's extent size,
|
|
may be changed only when the file is empty.
|
|
.TP
|
|
.SM \f3F_GETBMAP\f1
|
|
Get the block map for a segment of a file in an XFS file system.
|
|
The \f2arg\fP points to an arry of variables of type \f2struct getbmap\fP.
|
|
All sizes and offsets in the structure are in units of 512 bytes.
|
|
The structure fields include:
|
|
\f2bmv_offset\fP (file offset of segment),
|
|
\f2bmv_block\fP (starting block of segment),
|
|
\f2bmv_length\fP (length of segment),
|
|
\f2bmv_count\fP (number of array entries, including the first), and
|
|
\f2bmv_entries\fP (number of entries filled in).
|
|
The first structure in the array is a header, and the remaining
|
|
structures in the array contain block map information on return.
|
|
The header controls iterative calls to the
|
|
.SM \f3F_GETBMAP\f1 command.
|
|
The caller fills in the \f2bmv_offset\fP and \f2bmv_length\fP
|
|
fields of the header to indicate the area of interest in the
|
|
file, and fills in the \f2bmv_count\fP field to indicate the
|
|
length of the array.
|
|
If the \f2bmv_length\fP value is set to -1
|
|
then the length of the interesting area is the rest of the file.
|
|
On return from a call, the header is updated so that the command
|
|
can be used again to obtain more information, without re-initializing
|
|
the structures.
|
|
Also on return, the \f2bmv_entries\fP field of the header
|
|
is set to the number of array entries actually filled in.
|
|
The non-header structures will be filled in with \f2bmv_offset\fP,
|
|
\f2bmv_block\fP, and \f2bmv_length\fP.
|
|
If a region of the file has no blocks (is a hole in the file) then
|
|
the \f2bmv_block\fP field is set to -1.
|
|
.TP
|
|
.SM \f3F_GETBMAPA\f1
|
|
Identical to
|
|
.SM \f3F_GETBMAP\f1
|
|
except that information about the attribute fork of the file is returned.
|
|
.TP
|
|
.SM \f3F_RESVSP\f1
|
|
This command is used to allocate space to a file.
|
|
A range of bytes is specified with the \f2struct flock\fP.
|
|
The blocks are allocated, but not zeroed, and the file size
|
|
does not change.
|
|
It is only supported on XFS and BDS filesystems.
|
|
If the XFS filesystem is configured to flag unwritten file extents,
|
|
performance will be negatively affected when writing to preallocated
|
|
space, since extra filesystem transactions are required to convert
|
|
extent flags on the range of the file written.
|
|
If \f2xfs_growfs\f1(1M) with the -n option
|
|
reports unwritten=1, then the filesystem was made to flag unwritten extents.
|
|
Only the root user is permitted to execute \f2xfs_growfs\f1(1M).
|
|
.TP
|
|
.SM \f3F_RESVSP64\f1
|
|
This command is identical to
|
|
.SM \f3F_RESVSP\f1
|
|
except that the type of
|
|
the data referred to by the third argument \f2arg\fP is
|
|
a \f2struct flock64\fP. In this version of the structure,
|
|
\f2l_start\fP and \f2l_len\fP are of type \f3off64_t\fP instead of
|
|
\f3off_t\fP (64 bits instead of 32 bits).
|
|
.TP
|
|
.SM \f3F_UNRESVSP\f1
|
|
This command is used to free space from a file.
|
|
A range of bytes is specified with the \f2struct flock\fP.
|
|
Partial filesystem blocks are zeroed, and whole filesystem blocks
|
|
are removed from the file.
|
|
The file size does not change.
|
|
It is only supported on XFS and BDS filesystems.
|
|
.TP
|
|
.SM \f3F_UNRESVSP64\f1
|
|
This command is identical to
|
|
.SM \f3F_UNRESVSP\f1
|
|
except that the type of
|
|
the data referred to by the third argument \f2arg\fP is
|
|
a \f2struct flock64\fP. In this version of the structure,
|
|
\f2l_start\fP and \f2l_len\fP are of type \f3off64_t\fP instead of
|
|
\f3off_t\fP (64 bits instead of 32 bits).
|
|
.TP
|
|
.SM \f3F_FSYNC\f1
|
|
fsync data in a range of an ordinary file \f2fildes\fP.
|
|
The section is specified by a variable of data type
|
|
\f2struct flock\fP pointed to by the third argument \f2arg\fP.
|
|
.Op f
|
|
In Fortran, pass a variable of type RECORD.
|
|
.Op
|
|
The data type \f2struct flock\fP is defined in the
|
|
\f2<fcntl.h>\fP header file [see \f2fcntl\fP(5)].
|
|
If field \f2l_type\fP is set to 1, the call behaves like fdatasync(2).
|
|
If field \f2l_type\fP is set to 0, the call behaves like fsync(2).
|
|
fdatasync(2) syncs only the inode state required to ensure
|
|
that the data is permanently on the disk.
|
|
fsync(2) syncs everything that fdatasync(2) flushes but
|
|
also syncs out the other state associated with the file such as the
|
|
current timestamps, permissions, owner, etc.
|
|
\f2l_start\fP specifies the start of the range in the file to be sync'ed.
|
|
\f2l_len\fP specifies the size of the range.
|
|
A \f2l_len\fP of 0 flushes everything up to the end of the file.
|
|
The remaining fields are ignored and should be set to 0.
|
|
.TP
|
|
.SM \f3F_FSYNC64\f1
|
|
This command is identical to
|
|
.SM \f3F_FSYNC\f1
|
|
except that the type of
|
|
the data referred to by the third argument \f2arg\fP is
|
|
a \f2struct flock64\fP. In this version of the structure,
|
|
\f2l_start\fP and \f2l_len\fP are of type \f3off64_t\fP instead of
|
|
\f3off_t\fP (64 bits instead of 32 bits).
|
|
.TP
|
|
.SM \f3F_GETBIOSIZE\f1
|
|
This command gets information about the preferred buffered
|
|
I/O size used by the system when performing buffered I/O
|
|
(e.g. standard Unix non-direct I/O) to and from the file.
|
|
The information is passed back in a structure of type
|
|
\f2struct biosize\fP pointed to by the third argument
|
|
\f2arg\fP.
|
|
The data type \f2struct biosize\fP is defined in the
|
|
\f2<fcntl.h>\fP header file [see \f2fcntl\fP(5)].
|
|
biosize lengths are expressed in log base 2.
|
|
That is if the value is 14, then the true size is 2^14
|
|
(2 raised to the 14th power).
|
|
The biosz_read field will contain the current value used
|
|
by the system when reading from the file.
|
|
Except at the end-of-file,
|
|
the system will read from the file in multiples of this
|
|
length.
|
|
The biosz_write field will contain the current value used
|
|
by the system when writing to the file.
|
|
Except at the end-of-file,
|
|
the system will write to the file in multiples of this
|
|
length.
|
|
The dfl_biosz_read and dfl_biosz_write will be set to the
|
|
system default values for the opened file.
|
|
The biosz_flags field will be set to 1 if the
|
|
current read or write value has been explicitly set.
|
|
Th \f3F_GETBIOSIZE\fP fcntl is supported only on XFS filesystems.
|
|
.TP
|
|
.SM \f3F_SETBIOSIZE\f1
|
|
This command the preferred buffered
|
|
I/O size used by the system when performing buffered I/O
|
|
(e.g. standard Unix non-direct I/O) to and from the file.
|
|
The information is passed in a structure of type
|
|
\f2struct biosize\fP pointed to by the third argument
|
|
\f2arg\fP.
|
|
Using smaller preferred I/O sizes can result in
|
|
performance improvements if the file is typically
|
|
accessed using small synchronous I/Os or if only
|
|
a small amount of the file is accessed using small
|
|
random I/Os, resulting in little or no use of the
|
|
additional data read in near the random I/Os.
|
|
.sp
|
|
To explictly set the the preferred I/O sizes,
|
|
the biosz_flags field should be set to 0 and the
|
|
biosz_read and biosz_write fields should be set
|
|
to the log base 2 of the desired read and write
|
|
lengths, respectively (e.g. 13 for 8K bytes, 14 for 16K bytes,
|
|
15 for 32K bytes, etc.).
|
|
Valid values are 13-16 inclusive for machines with a 4K byte
|
|
pagesize and 14-16 for machines with a 16K byte pagesize.
|
|
The specified read and write values must also result
|
|
in lengths that are greater than or equal to the filesystem
|
|
block size.
|
|
The dfl_biosz_read and dfl_biosz_write fields are ignored.
|
|
.sp
|
|
If biosizes have already been explicitly set
|
|
due to a prior use of \f3F_SETBIOSIZE\fP,
|
|
and the requested sizes are larger then the
|
|
existing sizes, the fcntl call will return successfully
|
|
and the system will use the smaller of the two sizes.
|
|
However, if biosz_flags is set to 1, the system will
|
|
use the new values regardless of whether
|
|
the new sizes are larger or smaller than the old.
|
|
.sp
|
|
To reset the biosize values to the defaults for the
|
|
filesystem that the file resides in, the biosz_flags
|
|
filed should be set to 2.
|
|
The remainder of the fields will be ignored in that case.
|
|
.sp
|
|
Changes made by \f3F_SETBIOSIZE\fP are transient.
|
|
The sizes are reset to the default values once
|
|
the reference count on the file drops to zero
|
|
(e.g. all open file descriptors to that file have
|
|
been closed).
|
|
See \f2fstab\fP(4) for details on how to set the
|
|
default biosize values for a filesystem.
|
|
The \f3F_SETBIOSIZE\fP fcntl is supported only on XFS filesystems.
|
|
.P
|
|
The following commands are used for record-locking.
|
|
Locks may be placed on an entire file or on segments of a file.
|
|
.TP 1.0i
|
|
.SM \f3F_GETLK\f1
|
|
Get the first lock which blocks the lock description given by
|
|
the variable of type \f2struct flock\f1 pointed to by \f2arg\f1.
|
|
.Op f
|
|
In Fortran, pass a variable of type RECORD.
|
|
.Op
|
|
The information retrieved overwrites the information passed to
|
|
\f2fcntl\f1 in the \f2flock\f1 structure.
|
|
If no lock is found that would prevent this lock from being created,
|
|
then the structure is passed back unchanged except that the lock type
|
|
will be set to
|
|
.SM \f3F_UNLCK\f1
|
|
and the \f2l_whence\fP field will be set to
|
|
.SM \f3SEEK_SET\f1.
|
|
If a lock is found that would prevent this lock from being created,
|
|
then the structure is overwritten with a description of the first
|
|
lock that is preventing such a lock from being created.
|
|
The returned structure will
|
|
also contain the process ID and the system ID of the process holding the lock.
|
|
This command never creates a lock; it tests whether a particular lock could
|
|
be created.
|
|
.TP
|
|
.SM \f3F_SETLK\f1
|
|
Set or clear a file segment lock according to the variable of type \f2struct flock\f1
|
|
pointed to by \f2arg\f1 [see \f2fcntl\f1(5)].
|
|
.Op f
|
|
In Fortran pass a variable of type RECORD.
|
|
.Op
|
|
The \f2cmd\f1
|
|
.SM \f3F_SETLK\f1
|
|
is used to establish read (\s-1F_RDLCK\s+1) and write (\s-1F_WRLCK\s+1) locks,
|
|
as well as remove either type of lock (\s-1F_UNLCK\s+1).
|
|
If a read or write lock cannot be set \f2fcntl\f1 will return immediately with an
|
|
error value of \-1.
|
|
.TP
|
|
.SM \f3F_SETLKW\f1
|
|
This \f2cmd\f1 is the same as
|
|
.SM \f3F_SETLK\f1
|
|
except that if a read or write lock is blocked by other locks,
|
|
the process will sleep until the segment is free to be locked.
|
|
.TP
|
|
.SM \f3F_GETLK64\f1
|
|
This \f2cmd\f1 is identical to
|
|
.SM \f3F_GETLK\f1
|
|
but uses a \f2struct flock64\fP instead of a \f2struct flock\fP
|
|
(see \f3F_FREESP64\f1 above).
|
|
.TP
|
|
.SM \f3F_SETLK64\f1
|
|
This \f2cmd\f1 is identical to
|
|
.SM \f3F_SETLK\f1
|
|
but uses a \f2struct flock64\fP instead of a \f2struct flock\fP.
|
|
.TP
|
|
.SM \f3F_SETLKW64\f1
|
|
This \f2cmd\f1 is identical to
|
|
.SM \f3F_SETLKW\f1
|
|
but uses a \f2struct flock64\fP instead of a \f2struct flock\fP.
|
|
.TP
|
|
.SM \f3F_RSETLK\f1
|
|
Used by the network lock daemon, \f2lockd\fP(3N), to
|
|
communicate with the NFS server kernel to handle locks on NFS files.
|
|
.TP
|
|
.SM \f3F_RSETLKW\f1
|
|
Used by the network lock daemon, \f2lockd\fP(3N), to
|
|
communicate with the NFS server kernel to handle locks on NFS files.
|
|
.TP
|
|
.SM \f3F_RGETLK\f1
|
|
Used by the network lock daemon, \f2lockd\fP(3N), to
|
|
communicate with the NFS server kernel to handle locks on NFS files.
|
|
.TP
|
|
.SM \f3F_CHKFL\f1
|
|
This flag is used internally by
|
|
.SM \f3F_SETFL\f1
|
|
to check the legality of
|
|
file flag changes.
|
|
.PP
|
|
A read lock prevents any process from write locking the protected area.
|
|
More than one read lock may exist for a given segment of a file at a given time.
|
|
The file descriptor on which a read lock is being placed must have been opened with read access.
|
|
.PP
|
|
A write lock
|
|
prevents any process from read locking or write locking the protected area.
|
|
Only one write lock and no read locks may exist for a given segment of a file at a given time.
|
|
The file descriptor on which a write lock is being placed must have been opened
|
|
with write access.
|
|
.PP
|
|
The structure \f2flock\f1 describes the type
|
|
(\f2l_type\f1),
|
|
starting offset (\f2l_whence\f1), relative offset (\f2l_start\f1),
|
|
size (\f2l_len\f1), process id (\f2l_pid\f1), and system id (\f2l_sysid\f1)
|
|
of the segment of the file to be affected.
|
|
The process id and system id fields are used only with the
|
|
.SM \f3F_GETLK\f1
|
|
\f2cmd\f1 to return the values for a blocking lock.
|
|
Locks may start and extend beyond the current end of a file,
|
|
but may not be negative relative to the beginning of the file.
|
|
A lock may be set to always extend to the end of file by
|
|
setting \f2l_len\f1 to zero (0).
|
|
If such a lock also has \f2l_whence\f1 and \f2l_start\f1 set to zero (0),
|
|
the whole file will be locked.
|
|
Changing or unlocking a segment from the middle of a larger locked segment
|
|
leaves two smaller segments for either end.
|
|
Locking a segment that is already locked by the calling process
|
|
causes the old lock type to be removed
|
|
and the new lock type to take effect.
|
|
All locks associated with a file for a given process are removed when a file descriptor for
|
|
that file is closed by that process or the process holding that file descriptor
|
|
terminates.
|
|
Locks are not inherited by a child process in a \f2fork\f1(2) system call.
|
|
.PP
|
|
When file locking is used in conjunction with memory-mapped files over NFS,
|
|
the smallest locking granularity which will work properly with multiple
|
|
clients is the page size of the system. All clients must use the same
|
|
granularity.
|
|
.PP
|
|
When mandatory file and record locking is active on a file, [see
|
|
.IR chmod (2)],
|
|
.I read(2),
|
|
.I creat(2),
|
|
.I open(2),
|
|
and
|
|
.I write(2)
|
|
system calls issued on the file
|
|
will be affected by the record locks in effect.
|
|
.PP
|
|
\f2fcntl\f1 will fail if one or more of the following are true:
|
|
.sp
|
|
.TP 15
|
|
.SM [EACCES]
|
|
.I cmd\^
|
|
is
|
|
.SM F_SETLK,
|
|
the type of lock (\f2l_type\fP) is a read lock (
|
|
.SM F_RDLCK,
|
|
) and the segment of a file to be lock is already write locked by
|
|
another process, or the type is a write lock (
|
|
.SM F_WRLOCK,
|
|
) and the segment of a file to be locked in already read or write locked
|
|
by another process.
|
|
.TP
|
|
\s-1\%[EBADF]\s+1
|
|
.I Fildes\^
|
|
is not a valid open
|
|
file descriptor.
|
|
.TP 15
|
|
\s-1\%[EBADF]\s+1
|
|
\f2cmd\f1 is
|
|
.SM F_SETLK,
|
|
or
|
|
.SM SETLKW,
|
|
the type of lock (\f2l_type\f1) is a read lock
|
|
.SM (F_RDLCK),
|
|
and
|
|
.I fildes\^
|
|
is not a valid file descriptor open for reading.
|
|
.TP
|
|
\s-1\%[EBADF]\s+1
|
|
\f2cmd\f1 is
|
|
.SM F_SETLK,
|
|
or
|
|
.SM SETLKW,
|
|
the type of lock (\f2l_type\f1) is a write lock
|
|
.SM (F_WRLCK),
|
|
and
|
|
.I fildes\^
|
|
is not a valid file descriptor open for writing.
|
|
.TP
|
|
\s-1\%[EBADF]\s+1
|
|
\f2cmd\f1 is
|
|
.SM F_FREESP
|
|
and
|
|
.I fildes\^
|
|
is not a valid file descriptor open for writing.
|
|
.TP
|
|
.SM [EMFILE]
|
|
.I cmd\^
|
|
is
|
|
.SM F_DUPFD
|
|
and
|
|
.SM
|
|
.I {OPEN_MAX}
|
|
file descriptors are currently in use by this process,
|
|
or no file descriptors greater than or equal to
|
|
.I arg\^
|
|
are available.
|
|
.TP
|
|
\s-1\%[EINVAL]\s+1
|
|
.I cmd\^
|
|
is
|
|
.SM F_DUPFD.
|
|
.I arg\^
|
|
is either negative, or greater than or equal to the maximum
|
|
number of open file descriptors allowed each user [see
|
|
.IR getdtablesize (2)].
|
|
.TP
|
|
.SM [EINVAL]
|
|
\f2cmd\f1 is
|
|
.SM F_GETLK,
|
|
.SM F_SETLK,
|
|
or
|
|
.SM F_SETLKW
|
|
and \f2arg\f1 or the data it points to is not valid.
|
|
.TP
|
|
.SM [EINVAL]
|
|
\f2cmd\f1 is
|
|
.SM F_SETFL,
|
|
\f2arg\f1 includes \f2FDIRECT\f1
|
|
and is being performed on other than an EFS, XFS or BDS file system file.
|
|
.TP
|
|
.SM [EINVAL]
|
|
\f2cmd\f1 is
|
|
.SM F_SETBIOSIZE
|
|
and \f2arg\f1 is invalid.
|
|
.TP
|
|
.SM [EAGAIN]
|
|
\f2cmd\f1 is
|
|
.SM F_FREESP ,
|
|
the file exists, mandatory file/record locking is set, and there are
|
|
outstanding record locks on the file.
|
|
.\" SGI - we don't do this in 5.0
|
|
This restriction is not currently enforced.
|
|
.TP
|
|
.SM [EAGAIN]
|
|
\f2cmd\f1 is
|
|
.SM F_SETLK
|
|
or
|
|
.SM F_SETLKW
|
|
, mandatory file locking bit is set for the file,
|
|
and the file is currently being mapped to virtual memory via
|
|
\f2mmap\f1 [see
|
|
.IR mmap (2)].
|
|
.\" SGI - we don't do this in 5.3
|
|
This restriction is not currently enforced.
|
|
.TP
|
|
.SM [ENOLCK]
|
|
\f2cmd\f1 is
|
|
.SM F_SETLK
|
|
or
|
|
.SM F_SETLKW,
|
|
the type of lock is a read or write lock, and there are no more record locks
|
|
available (too many file segments locked) because the system maximum
|
|
.SM
|
|
.I {FLOCK_MAX}
|
|
[see
|
|
.IR intro (2)],
|
|
has been exceeded.
|
|
This can also occur if the object of the lock resides on a remote system
|
|
and the requisite locking daemons are not configured in both the local
|
|
and the remote systems. In particular, if \f4lockd\fP(1M) is running but
|
|
\f4statd\fP(1M) is not, this error will be returned. An additional source
|
|
for this error is when \f4statd\fP(1M) is running but cannot be contacted.
|
|
This can occur when the address for the local host cannot be determined.
|
|
[See \f4lockd\fP(1M) and \f4statd\fP(1M).]
|
|
.TP
|
|
.SM [EINTR]
|
|
.I cmd
|
|
is
|
|
.SM F_SETLKW
|
|
and a signal interrupted the process while it was waiting for the lock
|
|
to be granted.
|
|
.TP
|
|
.SM [EDEADLK]
|
|
.I cmd
|
|
is
|
|
.SM F_SETLKW,
|
|
the lock is blocked by some lock from another process, and putting
|
|
the calling-process to sleep, waiting for that lock to become
|
|
free, would cause a deadlock.
|
|
.TP
|
|
.SM [EDEADLK]
|
|
.I cmd
|
|
is
|
|
.SM F_FREESP,
|
|
mandatory record locking is enabled,
|
|
.SM O_NDELAY
|
|
and
|
|
.SM O_NONBLOCK
|
|
are being clear and a deadlock condition was detected.
|
|
.TP
|
|
.SM [EFAULT]
|
|
.I cmd
|
|
is
|
|
.SM F_FREESP,
|
|
and the value pointed to by the third argument \f2arg\fP
|
|
resulted in an address outside the process's allocated address space.
|
|
.TP
|
|
.SM [EFAULT]
|
|
.I cmd
|
|
is
|
|
.SM F_GETLK,
|
|
.SM F_SETLK
|
|
or
|
|
.SM F_SETLKW,
|
|
and \f2arg\f1 points outside the program address space.
|
|
.TP
|
|
.SM
|
|
\%[ESRCH]
|
|
.I cmd
|
|
is
|
|
.SM F_SETOWN
|
|
and
|
|
no process can be found corresponding to that specified by
|
|
.IR arg .
|
|
.TP
|
|
.SM
|
|
\%[EIO]
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.TP
|
|
.SM
|
|
\%[EOVERFLOW]
|
|
.I cmd
|
|
is
|
|
.SM F_GETLK
|
|
and the process ID of the process holding the requested lock is too large to
|
|
be stored in the \f2l_pid\fP field.
|
|
.\".TP
|
|
.\".SM [ENOLINK]
|
|
.\"\f2Fildes\f1 is on a remote machine and the link
|
|
.\"to that machine is no longer active.
|
|
.TP
|
|
.SM
|
|
\%[ETIMEDOUT]
|
|
The object of the fcntl is located on a remote system which is not available [see \f4intro\fP(2)].
|
|
.SH "SEE ALSO"
|
|
lockd(1M),
|
|
close(2), creat(2), dup(2), exec(2), fork(2), getdtablesize(2), intro(2), open(2), pipe(2), fcntl(5).
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion,
|
|
the value returned depends on
|
|
.I cmd\^
|
|
as follows:
|
|
.PD 0
|
|
.RS
|
|
.TP 1.0i
|
|
.SM F_DUPFD
|
|
A new file descriptor.
|
|
.TP
|
|
.SM F_GETFD
|
|
Value of flag (only the low-order
|
|
bit is defined).
|
|
.TP
|
|
.SM F_SETFD
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_GETFL
|
|
Value of file flags.
|
|
.TP
|
|
.SM F_SETFL
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_FREESP
|
|
Value of 0.
|
|
.TP
|
|
.SM F_ALLOCSP
|
|
Value of 0.
|
|
.TP
|
|
.SM F_FREESP64
|
|
Value of 0.
|
|
.TP
|
|
.SM F_ALLOCSP64
|
|
Value of 0.
|
|
.TP
|
|
.SM F_DIOINFO
|
|
Value of 0.
|
|
.TP
|
|
.SM F_GETOWN
|
|
.I pid
|
|
of socket owner.
|
|
.TP
|
|
.SM F_SETOWN
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_FSGETXATTR
|
|
Value of 0.
|
|
.TP
|
|
.SM F_FSSETXATTR
|
|
Value of 0.
|
|
.TP
|
|
.SM F_GETBMAP
|
|
Value of 0.
|
|
.TP
|
|
.SM F_RESVSP
|
|
Value of 0.
|
|
.TP
|
|
.SM F_RESVSP64
|
|
Value of 0.
|
|
.TP
|
|
.SM F_UNRESVSP
|
|
Value of 0.
|
|
.TP
|
|
.SM F_UNRESVSP64
|
|
Value of 0.
|
|
.TP
|
|
.SM F_GETLK
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_SETLK
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_SETLKW
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_GETLK64
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_SETLK64
|
|
Value other than \-1.
|
|
.TP
|
|
.SM F_SETLKW64
|
|
Value other than \-1.
|
|
.RE
|
|
.PP
|
|
.PD
|
|
Otherwise, a value of \-1 is returned and
|
|
.I errno\^
|
|
is set to indicate the error.
|
|
.\" @(#)fcntl.2 6.2 of 9/6/83
|
|
.Ee
|
|
'\".so /pubs/tools/origin.att
|