svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
fcntl(2)
fcntl(2) System Calls fcntl(2)
NAME
fcntl - file control
SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
int fcntl(int fildes, int cmd, /* arg */ ...);
DESCRIPTION
The fcntl() function provides for control over open files. The fildes
argument is an open file descriptor. File descriptors are process wide
resources, and are not unique to individual threads. A given file de‐
scriptor can therefore be changed by any thread in a multi-threaded
process.
The cmd argument specifies the operation to be performed by fcntl().
The fcntl() function can take additional arguments, whose data type,
value, and use depend upon the value of cmd. In the following descrip‐
tions, arg refers to a third argument.
The values for cmd are defined in fcntl.h(3HEAD) and include:
F_ALLOCSP
Allocate space for a section of the ordinary file fildes. The sec‐
tion is specified by a variable of data type struct flock pointed
to by arg. The data type struct flock is described below.
F_ALLOCSP64
Equivalent to F_ALLOCSP, but takes a struct flock64 argument rather
than a struct flock argument.
F_DUPFD
Return a new file descriptor which is the lowest numbered available
(that is, not already open) file descriptor greater than or equal
to the third argument, arg, taken as an integer of type int. The
new file descriptor refers to the same open file description as the
original file descriptor, and shares any locks. The FD_CLOEXEC and
FD_CLOFORK flags associated with the new file descriptor are not
set.
F_DUPFD_CLOEXEC
Similar to F_DUPFD, except that the FD_CLOEXEC flag associated with
the new file descriptor is set.
F_DUPFD_CLOFORK
Similar to F_DUPFD, except that the FD_CLOFORK flag associated with
the new file descriptor is set.
F_DUP2FD
Similar to F_DUPFD, except that it always returns arg as the new
file descriptor. F_DUP2FD closes arg if it is open and not equal to
fildes. If fildes is not equal to arg, the FD_CLOEXEC and FD_CLO‐
FORK flags associated with the new file descriptor are cleared. If
fildes is equal to arg, the FD_CLOEXEC and FD_CLOFORK flags associ‐
ated with the new file descriptor are not changed. F_DUP2FD is
equivalent to dup2(fildes, arg).
F_DUP2FD_CLOEXEC
Similar to F_DUP2FD, except that the FD_CLOEXEC flag associated
with the new file descriptor is set, unless fildes is equal to arg,
in which case the flags are unchanged.
F_DUP2FD_CLOFORK
Similar to F_DUP2FD, except that the FD_CLOFORK flag associated
with the new file descriptor is set, unless fildes is equal to arg,
in which case the flags are unchanged.
F_DUP3FD
Similar to F_DUP2FD, with the addition of a fourth argument which
allows the caller the option of specifying the FD_CLOEXEC and
FD_CLOFORK options for the newly created file descriptor. An error
is returned if fildes is equal to arg. F_DUP3FD is equivalent to
dup3(fildes, arg, flags), noting that the O_CLOEXEC and O_CLOFORK
options accepted by dup3() correspond to FD_CLOEXEC and FD_CLOFORK
options with F_DUP3FD.
F_FREESP
Free storage space associated with a section of the ordinary file
fildes. The section is specified by a variable of data type struct
flock pointed to by arg. The data type struct flock is described
below. Note that all file systems might not support all possible
variations of F_FREESP arguments. In particular, many file systems
allow space to be freed only at the end of a file.
F_FREESP64
Equivalent to F_FREESP, but takes a struct flock64 argument rather
than a struct flock argument.
F_GETFD
Get the file descriptor flags that are associated with the file de‐
scriptor fildes. File descriptor flags are associated with a single
file descriptor and do not affect other file descriptors that refer
to the same file. See the description of F_SETFD below for details
of the defined file descriptor flags.
F_GETFL
Get the file status flags and file access modes for the file de‐
scriptor specified by fildes. The file access modes can be ex‐
tracted from the return value using the mask O_ACCMODE, which is
defined in <fcntl.h>. File status flags and file access modes do
not affect other file descriptors that refer to the same file with
different open file descriptions.
F_GETOWN
If fildes refers to a socket, get the process or process group ID
specified to receive SIGURG signals when out-of-band data is avail‐
able. Positive values indicate a process ID; negative values, other
than −1, indicate a process group ID. If fildes does not refer to a
socket, the results are unspecified.
F_GETTPD
Returns whether the file is owned by the Trusted Path. For more in‐
formation, see the tpd(7) man page.
F_GETXFL
Get the file status flags, file access modes, and file creation and
assignment flags, for the file descriptor specified by fildes. The
file access modes can be extracted from the return value using the
mask O_ACCMODE, which is defined in <fcntl.h>. File status flags,
file access modes, and file creation and assignment flags do not
affect other file descriptors that refer to the same file with dif‐
ferent open file descriptions.
F_SETFD
Set the file descriptor flags that are associated with fildes, to
the third argument, arg, taken as type int. Any flags not set in
the third argument are cleared on the file descriptor.
If the FD_CLOEXEC flag is not set on the file descriptor, the file
will remain open across the exec() functions; otherwise the file
will be closed upon successful execution of one of the exec() func‐
tions or the spawn(2) system call.
If the FD_CLOFORK flag is not set on the file descriptor, the file
will remain open across the fork() functions; otherwise the file
will be unavailable after successful execution of one of the fork()
functions or the spawn(2) system call.
F_SETFL
Set the file status flags for the file descriptor specified by
fildes from the corresponding bits in the arg argument, taken as
type int. Bits corresponding to the file access mode and file cre‐
ation and assignment flags that are set in arg are ignored. If any
bits in arg other than those mentioned here are changed by the ap‐
plication, the result is unspecified.
F_SETOWN
If fildes refers to a socket, set the process or process group ID
specified to receive SIGURG signals when out-of-band data is avail‐
able, using the value of the third argument, arg, taken as type
int. Positive values indicate a process ID; negative values, other
than −1, indicate a process group ID. If fildes does not refer to a
socket, the results are unspecified.
F_SETTPD
Sets whether the file is owned by a process in the Trusted Path Do‐
main (TPD). If the int argument is zero the file is marked as not-
owned. If the int argument is not-zero, the file is marked as owned
by a TPD process. Only processes in the TPD can change the owner‐
ship. For more information, see the tpd(7) man page.
The following commands are available for advisory record locking.
Record locking is supported for regular files, and may be supported for
other files.
F_GETLK
Get the first lock which blocks the lock description pointed to by
the third argument, arg, taken as a pointer to type struct flock,
described below. The information retrieved overwrites the informa‐
tion passed to fcntl() in the structure flock. If no lock is found
that would prevent this lock from being created, then the structure
will be left unchanged except for the lock type which will be set
to F_UNLCK.
F_GETLK64
Equivalent to F_GETLK, but takes a struct flock64 argument rather
than a struct flock argument.
F_SETLK
Set or clear a file segment lock according to the lock description
pointed to by the third argument, arg, taken as a pointer to type
struct flock, described below. F_SETLK is used to establish shared
(or read) locks (F_RDLCK) or exclusive (or write) locks (F_WRLCK),
as well as to remove either type of lock (F_UNLCK). If a shared or
exclusive lock cannot be set, fcntl() will return immediately with
a return value of −1.
F_SETLK64
Equivalent to F_SETLK, but takes a struct flock64 argument rather
than a struct flock argument.
F_SETLKW
This command is the same as F_SETLK except that if a shared or ex‐
clusive lock is blocked by other locks, the process will wait until
the request can be satisfied. If a signal that is to be caught is
received while fcntl() is waiting for a region, fcntl() will be in‐
terrupted. Upon return from the process' signal handler, fcntl()
will return −1 with errno set to EINTR, and the lock operation will
not be done.
F_SETLKW64
Equivalent to F_SETLKW, but takes a struct flock64 argument rather
than a struct flock argument.
When a shared lock is set on a segment of a file, other processes will
be able to set shared locks on that segment or a portion of it. A
shared lock prevents any other process from setting an exclusive lock
on any portion of the protected area. A request for a shared lock will
fail if the file descriptor was not opened with read access.
An exclusive lock will prevent any other process from setting a shared
lock or an exclusive lock on any portion of the protected area. A re‐
quest for an exclusive lock will fail if the file descriptor was not
opened with write access.
The flock structure is defined in the <fcntl.h> header and contains at
least the following elements:
short l_type; /* lock operation type */
short l_whence; /* lock base indicator */
off_t l_start; /* starting offset from base */
off_t l_len; /* lock length; l_len == 0 means
until end of file */
int l_sysid; /* system ID running process holding lock */
pid_t l_pid; /* process ID of process holding lock */
The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate
that the relative offset l_start bytes will be measured from the start
of the file, current position or end of the file, respectively. The
value of l_len is the number of consecutive bytes to be locked. The
value of l_len may be negative (where the definition of off_t permits
negative values of l_len). After a successful F_GETLK or F_GETLK64 re‐
quest, that is, one in which a lock was found, the value of l_whence
will be SEEK_SET.
The l_pid and l_sysid fields are used only with F_GETLK or F_GETLK64 to
return the process ID of the process holding a blocking lock and to in‐
dicate which system is running that process.
If l_len is positive, the area affected starts at l_start and ends at
l_start + l_len − 1. If l_len is negative, the area affected starts at
l_start + l_len and ends at l_start − 1. Locks may start and extend be‐
yond the current end of a file, but must not be negative relative to
the beginning of the file. A lock will be set to extend to the largest
possible value of the file offset for that file by setting l_len to 0.
If such a lock also has l_start set to 0 and l_whence is set to
SEEK_SET, the whole file will be locked.
If a process has an existing lock in which l_len is 0 and which in‐
cludes the last byte of the requested segment, and an unlock (F_UNLCK)
request is made in which l_len is non-zero and the offset of the last
byte of the requested segment is the maximum value for an object of
type off_t, then the F_UNLCK request will be treated as a request to
unlock from the start of the requested segment with an l_len equal to
0. Otherwise, the request will attempt to unlock only the requested
segment.
There will be at most one type of lock set for each byte in the file.
Before a successful return from an F_SETLK, F_SETLK64, F_SETLKW, or
F_SETLKW64 request when the calling process has previously existing
locks on bytes in the region specified by the request, the previous
lock type for each byte in the specified region will be replaced by the
new lock type. As specified above under the descriptions of shared
locks and exclusive locks, an F_SETLK, F_SETLK64, F_SETLKW, or
F_SETLKW64 request will (respectively) fail or block when another
process has existing locks on bytes in the specified region and the
type of any of those locks conflicts with the type specified in the re‐
quest.
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 created using fork(2).
A potential for deadlock occurs if a process controlling a locked re‐
gion is put to sleep by attempting to lock another process' locked re‐
gion. If the system detects that sleeping until a locked region is un‐
locked would cause a deadlock, fcntl() will fail with an EDEADLK error.
The following values for cmd are used for file share reservations. A
share reservation is placed on an entire file to allow cooperating
processes to control access to the file.
F_SHARE Sets a share reservation on a file with the specified ac‐
cess mode and designates which types of access to deny.
F_UNSHARE Remove an existing share reservation.
File share reservations are an advisory form of access control among
cooperating processes, on both local and remote machines. They are most
often used by DOS or Windows emulators and DOS based NFS clients. How‐
ever, native UNIX versions of DOS or Windows applications may also
choose to use this form of access control.
A share reservation is described by an fshare structure defined in
<sys/fcntl.h>, which is included in <fcntl.h> as follows:
typedef struct fshare {
short f_access;
short f_deny;
int f_id;
} fshare_t;
A share reservation specifies the type of access, f_access, to be re‐
quested on the open file descriptor. If access is granted, it further
specifies what type of access to deny other processes, f_deny. A single
process on the same file may hold multiple non-conflicting reservations
by specifying an identifier, f_id, unique to the process, with each re‐
quest.
An F_UNSHARE request releases the reservation with the specified f_id.
The f_access and f_deny fields are ignored.
Valid f_access values are:
F_RDACC Set a file share reservation for read-only access.
F_WRACC Set a file share reservation for write-only access.
F_RWACC Set a file share reservation for read and write access.
Valid f_deny values are:
F_COMPAT Set a file share reservation to compatibility mode.
F_RDDNY Set a file share reservation to deny read access to other
processes.
F_WRDNY Set a file share reservation to deny write access to other
processes.
F_RWDNY Set a file share reservation to deny read and write access
to other processes.
F_NODNY Do not deny read or write access to any other process.
RETURN VALUES
Upon successful completion, the value returned depends on cmd as fol‐
lows:
F_ALLOCSP Value of 0.
F_ALLOCSP64 Value of 0.
F_DUPFD A new file descriptor.
F_DUPFD_CLOEXEC A new file descriptor.
F_DUPFD_CLOFORK A new file descriptor.
F_DUP2FD A new file descriptor.
F_DUP2FD_CLOEXEC A new file descriptor.
F_DUP2FD_CLOFORK A new file descriptor.
F_DUP3FD A new file descriptor.
F_FREESP Value of 0.
F_FREESP64 Value of 0.
F_GETFD Value with bits set corresponding to the FD_* flags
associated with the file descriptor fildes. See the
entry for F_SETFD in the Description section above
for details of the defined file descriptor flags.
The return value will not be negative.
F_GETFL Value with bits set corresponding to the file sta‐
tus flags and access modes associated with the file
descriptor fildes. The return value will not be
negative.
F_GETLK Value other than −1.
F_GETLK64 Value other than −1.
F_GETOWN Value of the socket owner process or process group;
this will not be −1.
F_GETTPD 0 if the file is not owned by the TPD or 1 if the
file is owned by the TPD.
F_GETXFL Value of file status flags, access modes, and cre‐
ation and assignment flags. The return value will
not be negative.
F_SETFD Value other than −1.
F_SETFL Value other than −1.
F_SETLK Value other than −1.
F_SETLK64 Value other than −1.
F_SETLKW Value other than −1.
F_SETLKW64 Value other than −1.
F_SETOWN Value other than −1.
F_SETTPD Value other than −1.
F_SHARE Value other than −1.
F_UNSHARE Value other than −1.
Otherwise, −1 is returned and errno is set to indicate the error.
ERRORS
The fcntl() function will fail if:
EAGAIN
The cmd argument is F_SETLK or F_SETLK64, the type of lock (l_type)
is a shared (F_RDLCK) or exclusive (F_WRLCK) lock, and the segment
of a file to be locked is already exclusive-locked by another
process; or the type is an exclusive lock and some portion of the
segment of a file to be locked is already shared-locked or exclu‐
sive-locked by another process.
The cmd argument is F_FREESP or F_FREESP64, the file exists, manda‐
tory file/record locking is set, and there are outstanding record
locks on the file,
The cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64,
mandatory file/record locking is set, and the file is currently be‐
ing mapped to virtual memory using mmap(2).
The cmd argument is F_SHARE and f_access conflicts with an existing
f_deny share reservation.
EBADF
The fildes argument is not a valid open file descriptor.
The cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64,
the type of lock, l_type, is a shared lock (F_RDLCK), and fildes is
not a valid file descriptor open for reading; or the type of lock
l_type is an exclusive lock (F_WRLCK) and fildes is not a valid
file descriptor open for writing.
The cmd argument is F_FREESP or F_FREESP64, and fildes is not a
valid file descriptor open for writing.
The cmd argument is F_DUP2FD, F_DUP2FD_CLOEXEC, F_DUP2FD_CLOFORK,
or F_DUP3FD, and arg is negative or is not less than the current
resource limit for RLIMIT_NOFILE.
The cmd argument is F_SHARE, the f_access share reservation is for
write access, and fildes is not a valid file descriptor open for
writing.
The cmd argument is F_SHARE, the f_access share reservation is for
read access, and fildes is not a valid file descriptor open for
reading.
EFAULT
The cmd argument is F_GETLK, F_GETLK64, F_SETLK, F_SETLK64,
F_SETLKW, F_SETLKW64, F_FREESP, F_FREESP64, F_SHARE, or F_UNSHARE
and the arg argument points to an illegal address.
EINTR
The cmd argument is F_SETLKW or F_SETLKW64 and the function was in‐
terrupted by a signal.
EINVAL
The cmd argument is invalid or not supported by the file system.
The cmd argument is F_DUPFD, F_DUPFD_CLOEXEC, or F_DUPFD_CLOFORK,
and arg is negative or is not less than the current resource limit
for RLIMIT_NOFILE.
The cmd argument is F_GETLK, F_GETLK64, F_SETLK, F_SETLK64,
F_SETLKW, or F_SETLKW64 and the data pointed to by arg is not
valid; or fildes refers to a file that does not support locking.
The cmd argument is F_UNSHARE and a reservation with this f_id for
this process does not exist.
The cmd argument is F_DUP3FD, and the third argument is the same as
the first argument or the fourth argument has invalid flags.
EIO
An I/O error occurred while reading from or writing to the file
system.
EMFILE
The cmd argument is F_DUPFD, F_DUPFD_CLOEXEC, or F_DUPFD_CLOFORK,
and either OPEN_MAX file descriptors are currently open in the
calling process, or no file descriptors greater than or equal to
arg are available.
ENOLCK
The cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64 and
satisfying the lock or unlock request would result in the number of
locked regions in the system exceeding a system-imposed limit.
ENOLINK
The fildes argument is on a remote machine and the link to that ma‐
chine is no longer active.
EOVERFLOW
One of the values to be returned cannot be represented correctly.
The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest
or, if l_len is non-zero, the largest, offset of any byte in the
requested segment cannot be represented correctly in an object of
type off_t.
The cmd argument is F_GETLK64, F_SETLK64, or F_SETLKW64 and the
smallest or, if l_len is non-zero, the largest, offset of any byte
in the requested segment cannot be represented correctly in an ob‐
ject of type off64_t.
EPERM
The cmd argument is F_ALLOCSP, F_ALLOCSP64, F_FREESP, or
F_FREESP64, and the file has one or more of the appendonly, read‐
only, immutable, or rtime system attributes set.
The fcntl() function may fail if:
EAGAIN
The cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64,
and the file is currently being mapped to virtual memory using
mmap(2).
EDEADLK
The cmd argument is F_SETLKW or F_SETLKW64, 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.
The cmd argument is F_FREESP or F_FREESP64, mandatory record lock‐
ing is enabled, O_NDELAY and O_NONBLOCK are clear, and a deadlock
condition was detected.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelAsync-Signal-
Safe _ StandardSee standards(7).
SEE ALSO
chmod(2), close(2), creat(2), dup(2), exec(2), fork(2), mmap(2),
open(2), pipe(2), read(2), sigaction(2), write(2), dup2(3C), fc‐
ntl.h(3HEAD), attributes(7), standards(7), sysattr(7), lockd(8)
NOTES
In the past, the variable errno was set to EACCES rather than EAGAIN
when a section of a file is already locked by another process. There‐
fore, portable application programs should expect and test for either
value.
Advisory locks allow cooperating processes to perform consistent opera‐
tions on files, but do not guarantee exclusive access. Files can be ac‐
cessed without advisory locks, but inconsistencies may result. The net‐
work share locking protocol does not support the f_deny value of F_COM‐
PAT. For network file systems, if f_access is F_RDACC, f_deny is mapped
to F_RDDNY. Otherwise, it is mapped to F_RWDNY.
To prevent possible file corruption, the system may reject mmap() re‐
quests for advisory locked files, or it may reject advisory locking re‐
quests for mapped files. Applications that require a file be both
locked and mapped should lock the entire file (l_start and l_len both
set to 0). If a file is mapped, the system may reject an unlock re‐
quest, resulting in a lock that does not cover the entire file.
The process ID returned for locked files on network file systems might
not be meaningful.
If the file server crashes and has to be rebooted, the lock manager
(see lockd(8)) attempts to recover all locks that were associated with
that server. If a lock cannot be reclaimed, the process that held the
lock is issued a SIGLOST signal.
HISTORY
The fcntl() function has been included in all Sun and Oracle releases
of Solaris.
Support for the following cmd values is available in Solaris starting
with the listed release:
tab() box; cw(4.71i) |cw(0.79i) lw(4.71i) |lw(0.79i) COMMANDRELEASE _
F_DUP3FD11.4.0 _ F_GETTPD, F_SETTPD11.3.18 _ F_DUPFD_CLOFORK,
F_DUP2FD_CLOFORK11.3.0 _ T{ F_ALLOCSP, F_ALLOCSP64, F_DUPFD_CLOEXEC,
F_DUP2FD_CLOEXEC T}11.0.0 _ F_GETXFL9 _ T{ F_DUP2FD, F_FREESP64,
F_GETLK64, F_SETLK64, F_SETLKW64, F_SHARE, F_UNSHARE T}2.6 _
F_FREESP2.0 _ T{ F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETOWN,
F_SETOWN, F_GETLK, F_SETLK, F_SETLKW T}1.0
Oracle Solaris 11.4 30 Jan 2023 fcntl(2)