fcntl(2)

NAME

fcntl() — file control

SYNOPSIS

#include <fcntl.h>

int fcntl(int fildes, int cmd, ... /* arg */);

Remarks

The ANSI C ", ... " construct denotes a variable length argument list whose optional [or required] members are given in the associated comment (/* */).

DESCRIPTION

fcntl() provides for control over open files. fildes is an open file descriptor.

The following are possible values for the cmd argument:

F_ADVISE

Fadvise service request (see fadvise(2)).

F_DUPFD

Return a new file descriptor having the following characteristics:

Lowest numbered available file descriptor greater than or equal to the third argument, arg, taken as an integer of type int.
Same open file (or pipe) as the original file.
Same file pointer as the original file (that is, both file descriptors share one file pointer).
Same access mode (read, write or read/write).
Same file status flags (that is, both file descriptors share the same file status flags).
The close-on-exec flag associated with the new file descriptor is set to remain open across exec() system calls.

F_GETFD

Get the file descriptor flags (defined in <fcntl.h>) that are associated with the file descriptor fildes. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file.

F_SETFD

Set the file descriptor flags (defined in <fcntl.h>) that are associated with fildes, to the third argument, arg, taken as an integer of type int (see F_GETFD). If the FD_CLOEXEC flag in the third argument is 0, the file will remain open across exec(); otherwise, the file will be closed upon execution of exec().

F_GETFL

Get file status flags and access modes; see fcntl(5).

F_SETFL

Set file status flags to the third argument, arg, taken as an integer of type int. Only certain flags can be set; see fcntl(5). It is not possible to set both O_NDELAY and O_NONBLOCK.

F_GETLK

Get the first lock that blocks the lock described by the variable of type struct flock pointed to by the third argument, arg, taken as a pointer to type struct flock. The information retrieved overwrites the information passed to fcntl() in the flock structure. If no lock is found that would prevent this lock from being created, the structure is passed back unchanged, except that the lock type is set to F_UNLCK.

F_SETLK

Set or clear a file segment lock according to the variable of type struct flock pointed to by the third argument, arg, taken as a pointer to type struct flock (see fcntl(5)). The cmd F_SETLK is used to establish read (F_RDLCK) and write (F_WRLCK) locks, as well as to remove either type of lock (F_UNLCK). If a read or write lock cannot be set, fcntl() returns immediately with an error value of -1.

F_SETLKW

This cmd is the same as F_SETLK 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.

F_GETLK64

Same as F_GETLK, except arg is a pointer to struct flock64 instead of struct flock.

F_SETLK64

Same as F_SETLK, except arg is a pointer to struct flock64 instead of struct flock.

F_SETLKW64

Same as F_SETLKW, except arg is a pointer to struct flock64 instead of struct flock.

F_GETOWN

If fildes refers to a socket, fcntl() returns the process or process group ID specified to receive SIGURG signals when out-of-band data is available. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID.

F_SETOWN

If fildes refers to a socket, fcntl() sets the process or process group ID specified to receive SIGURG signals when out-of-band data is available, 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.

F_GETTIMES

Gets the current times for the file identified by fildes. The F_GETTIMES third argument, arg, is a pointer to the struct attr_timbuf defined in <sys/fcntl1.h> (see F_SETTIMES).

F_SETTIMES

Sets the current times for the file identified by fildes. To execute the cmd without error, F_SETTIMES requires superuser privilege. The F_SETTIMES third argument, arg, is a pointer to the struct attr_timbuf that is defined in <sys/fcntl1.h>. The attr_timbuf structure contains the file's atime (access time), mtime (modification time), and ctime (file attribute change time) values. Here is the definition of the structure:

struct attr_timbuf { 
        timestruc_t atime; /* access            */ 
        timestruc_t mtime; /* data modification */ 
        timestruc_t ctime; /* attribute change  */ 
       }; 

This cmd is useful when it is necessary to save a file's current time values and then, after copying or moving the file, set back atime and mtime. Note that ctime is not restored to the original value; the value of ctime after F_SETTIMES is file system dependent.

An example using F_GETTIMES and F_SETTIMES follows:

# include <sys/fcntl.h> 
# include <sys/fcntl1.h> 

int 
main() 
{ 
  int fd ; 
  struct attr_timbuf  tstamp; 
   
  /* Create a file*/ 
  fd=open("/var/tmp/foo",O_CREAT|O_RDWR); 
   
  /* Use F_GETTIMES to obtain the current times 
   * of the file 
   */ 
  fcntl(fd,F_GETTIMES,&tstamp); 
   
  /* Access or modify fd */ 
  
  /* Now use F_SETTIMES to reinstate the 
   * original atime and mtime. 
   */ 
  fcntl(fd,F_SETTIMES,&tstamp); 
} 

F_SHARE

Sets a share reservation on a file with the specified access mode and designates which types of access to deny. The details of the file share reservation request are specified using the third argument arg, which should be a pointer to a struct fshare (defined in <sys/fcntl.h>). See the File Share Reservations section below.

F_UNSHARE

Removes an existing share reservation.

A read lock prevents any other process from write-locking the protected area. More than one read lock can 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.

A write lock prevents any other process from read-locking or write-locking the protected area. Only one write lock 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.

The structure flock describes the type (l_type), starting offset (l_whence), relative offset (l_start), size (l_len), and process ID (l_pid) of the segment of the file to be affected. The process ID field is only used with the F_GETLK cmd to return the value of a block in lock. Locks can start and extend beyond the current end of a file, but cannot be negative relative to the beginning of the file. A lock can be set to always extend to the end of file by setting l_len to zero (0). If such a lock also has l_start 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 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 fork() system call.

When enforcement-mode file and record locking is activated on a file (see chmod(2)), future creat(), open(), read(), write(), truncate(), and ftruncate() system calls on the file are affected by the record locks in effect.

File Share Reservations

File share reservations are an advisory form of access control among cooperating processes, on both local and remote machines. They are most commonly used by DOS or Windows emulators and DOS based NFS clients. The fcntl() system call can be used to set file share reservations via the F_SHARE command.

A share reservation is described by an fshare structure defined in <sys/fcntl.h> as follows:

  
struct fshare { 
       short   f_access; 
       short   f_deny; 
       long    f_id; 
       }; 

The structure fshare describes the type of access (f_access), to be requested on the open file descriptor. If the command succeeds it also specifies what type of access to deny other processes (f_deny), A single process on the same file may hold several non-conflicting reservations by specifying an identifier, (f_id), unique to the process with each share reservation request.

Valid f_access values are:

R_RDACC: Set a file share reservation for read-only access.
R_WRACC: Set a file share reservation for write-only access.
R_RWACC: Set a file share reservation for read-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: Set a file share reservation to not deny read or write access to other processes.

Oplocks

An oplock is a type of caching hint used mostly by CIFS clients so they may cache data locally. This helps increase performance by not having to read data across a network each time a file operation is performed. The oplock guarantees that no other remote process is accessing the file in a way that might lead to data inconsistencies.

The following arguments are supported for oplocks.

F_SETOPLOCK: Requests an opportunistic lock reservation (oplock) on a file. The supported oplock types are defined in <sys/oplock.h>.
F_SETOPLOCKW: Requests an opportunistic lock reservation (oplock) on a file and will wait (in other words, block) until the request may be granted.
F_REMOVEOPLOCK: Removes all oplocks by pid.
F_HAVEOPLOCK: Checks to see if an oplock is present on a file. The possible returns values are one of the oplock types defined in <sys/oplock.h>.

An oplock request is described by an oplock structure which is defined in <sys/oplock.h> as follows:

struct oplock{ 
          int64_t   o_owner; 
          sysid_t   o_member_id; 
          int64_t   o_type; 
          sysid_t   o_sysid; 
          pid_t     o_pid; 
          int64_t   o_flags; 
          int64_t   o_retry; 
          int64_t   o_timeout; 
          int64_t   o_sig_val; 
}; 

The structure oplock describes the details of the lock being requested on the opened file descriptor. If the command succeeds it also contains the owner ID (o_owner) of the process as well as the type of oplock (o_type) being requested. The o_sysid may also be specified. The process ID (o_pid) is the requesting process with which to associate the oplock. Optional flags o_flags, o_timeout, and signal value (o_sig_val) may also be specified.

The only field in this structure which must be assigned is o_type. The other fields are either optional or not used and should be initialized to zero (0).

The fields in the oplock structure are described here:

o_owner

Owner type. Any integer; however, 0x8000 is reserved.

o_member_id

Member ID. Any unique integer of type sysid_t.

o_type

Type of oplock. May be one of these values:

VFS_OPLOCK_NONE: Removes an oplock.
VFS_OPLOCK_SHARED: Request a shared oplock.
VFS_OPLOCK_EXCLUSIVE: Request an exclusive oplock.
VFS_OPLOCK_BATCH: Request a batch oplock. (Requires CIFS stacked file system support)

o_sysid

The system ID of the locking process. This is an optional value.

o_pid

The process ID of the process that owns the oplock. This does not need to be filled in by the application, as this is done internally.

o_flags

This field is not currently used and is here for future needs. It is recommended this be initialized to zero (0).

o_retry

This field is the number of retries to gracefully request that an oplock be broken. After the number of retries are exhausted, then the oplock will be removed without acknowledgment from the process that owns it.

o_timeout

This value represents the wait time in seconds that the kernel will wait before re-sending the oplock break signal. The total time that an application may wait for an oplock is (o_retry+1) multiplied by o_timeout seconds.

o_sig_val

A value to be sent with signal to a process upon an oplock being broken.

Application Usage

Because in the future the external variable errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value. For example:

flk->l_type = F_RDLCK; 
   if (fcntl(fd, F_SETLK, flk) == -1) 
      if ((errno == EACCES) || (errno == EAGAIN)) 
            /* 
             * section locked by another process, 
             * check for either EAGAIN or EACCES 
             * due to different implementations 
             */ 
       else if ... 
            /* 
             * check for other errors 
             */ 

NETWORKING FEATURES

NFS

The advisory record-locking capabilities of fcntl() are implemented throughout the network by the "network lock daemon" (see lockd(1M)). If the file server crashes and is rebooted, the lock daemon attempts to recover all locks associated with the crashed server. If a lock cannot be reclaimed, the process that held the lock is issued a SIGLOST signal.

Record locking, as implemented for NFS files, is only advisory.

RETURN VALUE

Upon successful completion, the value returned depends on cmd as follows:

F_ADVISE: Value of requested hint operation.
F_DUPFD: A new file descriptor.
F_GETFD: Value of close-on-exec flag (only the low-order bit is defined).
F_SETFD: Value other than -1.
F_GETFL: Value of file status flags and access modes.
F_SETFL: Value other than -1.
F_GETLK: Value other than -1.
F_SETLK: Value other than -1.
F_SETLKW: Value other than -1.
F_SETOPLOCK: Value other than -1.
F_SETOPLOCKW: Value other than -1.
F_HAVE_OPLOCK: Value other than -1.
F_REMOVE_OPLOCK: Value other than -1.
F_GETLK64: Value other than -1.
F_SETLK64: Value other than -1.
F_SETLKW64: Value other than -1.
F_GETOWN: Value of process or process group ID specified to receive SIGURG signals when out-of-band data is available.
F_SETOWN: Value other than -1.
F_GETTIMES: Value other than -1.
F_SETTIMES: Value other than -1.
F_SHARE: Value other than -1.
F_UNSHARE: Value other than -1.

Otherwise, a value of -1 is returned and errno is set to indicate the error.

ERRORS

fcntl() fails if any of the following conditions occur:

EACCES: cmd is F_SETLK, the type of lock (l_type) is a read lock (F_RDLCK) or write lock (F_WRLCK) and the segment of a file to be locked is already write-locked by another process, or the type is a write lock (F_WRLCK) and the segment of a file to be locked is already read- or write-locked by another process.
EAGAIN: cmd is F_SETLK or F_SETLKW, and the file is mapped in to virtual memory via the mmap() system call (see mmap(2)).
EAGAIN: cmd is F_SHARE and f_access conflicts with an existing f_deny share reservation.
EAGAIN: cmd is F_SETOPLOCK, and this request conflicts with an existing byte lock or share reservation.
EBADF: fildes is not a valid open file descriptor, or was not opened for reading when setting a read lock, or for writing when setting a write lock.
EBADF: cmd arg is F_SHARE, and the f_access share reservation is for read or write access, and the file descriptor is not a valid file descriptor open for reading.
EDEADLK: cmd is F_SETLKW, when the lock is blocked by a lock from another process and sleeping (waiting) for that lock to become free. This causes a deadlock situation.
EFAULT: cmd is either F_GETLK, F_SETLK, or F_SETLKW, and arg points to an illegal address.
EFAULT: cmd is either F_SHARE or F_UNSHARE, and arg points to an illegal address.
EFAULT: cmd is either F_SETOPLOCK, F_SETOPLOCKW, F_HAVEOPLOCK, or F_REMOVEOPLOCK, and arg points to an illegal address.
EINTR: cmd is F_SETLKW and the call was interrupted by a signal.
EINVAL: cmd is F_DUPFD and arg is negative.
EINVAL: cmd is F_GETLK, F_SETLK, or F_SETLKW, and arg or the data it points to is not valid, or fildes refers to a file that does not support locking.
EINVAL: cmd is not a valid command.
EINVAL: cmd is F_SETFL and both O_NONBLOCK and O_NDELAY are specified.
EINVAL: cmd is F_SETOPLOCK or F_SETOPLOCKW and the o_type, o_timeout, or o_retry values are not valid.
EINVAL: cmd is F_SHARE or F_UNSHARE and arg is invalid.
EINVAL: cmd is F_DUPFD and arg is greater than or equal to the maximum number of file descriptors.
EMFILE: cmd is F_DUPFD and the maximum number of file descriptors is currently open.
ENOLCK: cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and no more record locks are available (too many file segments locked).
ENOLCK: cmd is F_SETLK or F_SETLKW, the type of lock (l_type) is a read lock (F_RDLCK) or write lock (F_WRLCK) and the file is an NFS file with access bits set for enforcement mode.
ENOLCK: cmd is F_GETLK, F_SETLK, or F_SETLKW, the file is an NFS file, and a system error occurred on the remote node.
[ENOSYS]: ENOSYS cmd is F_SETOPLOCK or F_SETOPLOCKW and the arg is VFS_OPLOCK_FILTER which is currently defined but not supported.
ENOTSOCK: cmd is F_GETOWN or F_SETOWN, and fildes does not refer to a socket.
EOVERFLOW: cmd is F_GETLK and the blocking lock's starting offset or length would not fit in the caller's structure.
EPERM: cmd is F_SETTIMES and the user does not have superuser privilege.
EWOULDBLOCK: cmd is F_ADVISE the hint is FADV_WILLNEED and VM has detected a blocking condition.

WARNINGS

Oplock support is release specific and as such is not guaranteed to be supported in future releases and/or with the same interface. HP reserves the right to change or remove oplock support at any time.

AUTHOR

fcntl() was developed by HP, AT&T and the University of California, Berkeley.

STANDARDS CONFORMANCE

fcntl(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1