sys_fcntl [fs/fcntl.c]
Performs one of the available operations on a file descriptor. Arguments
eax | 55
ebx | File descriptor.
ecx | Operation to execute. It should be one of the following predefined values:
`F_DUPFD` | `Duplicate the file descriptor. New file descriptor will be returned in eax.`
`F_GETFD` | `Read the file descriptor flags. Currently only one flag is defined: FD_CLOEXEC - Close on execution.`
`F_SETFD` | `Set the file descriptor flags to the value specified by edx. Currently only one flag is defined: FD_CLOEXEC - Close on execution.`
`F_GETFL` | `Read the file status flags.`
`F_SETFL` | `Set the file status flags to the value specified by edx. Only the following flags can be changed: O_APPEND, O_NONBLOCK, O_DIRECT, O_NOATIME or O_ASYNC`
`F_GETLK` | `Check if a lock could be placed. A pointer to a properly initialized flock structure should be specified by edx:`
`struc flock { .l_type rw 1 ; Type of lock: F_RDLCK, F_WRLCK, F_UNLCK .l_whence rw 1 ; How to interpret l_start: SEEK_SET, SEEK_CUR, SEEK_END .l_start rd 1 ; Starting offset for lock .l_len rd 1 ; Number of bytes to lock .l_pid rd 1 ; PID of process blocking our lock (F_GETLK only) }`
`If lock could be placed, sys_fcntl does not actually place it, but returns F_UNLCK in the l_type field of flock structure and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then sys_fcntl returns details about one of these locks in the l_type, l_whence, l_start, and l_len fields of lock and sets l_pid to be the PID of the process holding that lock. In order to place a read lock, file descriptor must be open for reading. In order to place a write lock, file descriptor must be open for writing. To place both types of lock, open a file read-write. As well as being removed by an explicit F_UNLCK, record locks are automatically released when the process terminates or if it closes any file descriptor referring to a file on which locks are held.`
`F_SETLK` | `Acquires or releases a lock. A pointer to a properly initialized flock structure should be specified by edx. To acquire a lock l_type should be set to F_RDLCK or F_WRLCK and l_whence, l_start, l_len set to correct bytes range to whom the lock should apply. To release a lock l_type should be set to F_UNLCK. If lock is held by another process the return values is -EACCES or -EAGAIN. l_len can be negative. And if it is, the interval described by the lock covers bytes l_start+l_len up to and including l_start-1.`
`F_SETLKW` | `F_SETLKW is the same as F_SETLK except that if a conflicting lock is held on the file, then wait for that lock to be released. If a signal is caught while waiting, then the call is interrupted and returns immediately with return value set to -EINTR.`
`F_SETOWN` | `Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on file descriptor. A process ID is specified as a positive value. A process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner.` `If you set the O_ASYNC status flag on a file descriptor (either by providing this flag with the sys_open call, or by using the F_SETFL command of sys_fcntl), a SIGIO signal is sent whenever input or output becomes possible on that file descriptor. F_SETSIG can be used to obtain delivery of a signal other than SIGIO. If this permission check fails, then the signal is silently discarded.` `Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for sys_kill, where the sending process is the one that employs F_SETOWN (but see BUGS below).` `If the file descriptor refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where sys_select would report the socket as having an "exceptional condition".)` `If a non-zero value is given to F_SETSIG in a multi-threaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of sys_gettid instead of sys_getpid to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use sys_gettid or sys_getpid in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN. Note also that Linux imposes a limit on the number of real-time signals that may be queued to a process (see sys_getrlimit and sys_signa) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.`
`F_GETOWN` | `Get the process ID or process group currently receiving SIGIO and SIGURG signals for events on file descriptor. Process IDs are returned as positive values; process group IDs are returned as negative values.`
`F_SETSIG` | `Sets the signal sent when input or output becomes possible. A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.` `Additionally, passing a non-zero value to F_SETSIG changes the signal recipient from a whole process to a specific thread within a process. See the description of F_SETOWN for more details.` `By using F_SETSIG with a non-zero value, and setting SA_SIGINFO for the signal handler (see sys_sigaction), extra information about I/O events is passed to the handler in a siginfo structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (sys_select, sys_poll, sys_read with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.` `By selecting a POSIX.1b real time signal (value >= SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory). Extra information is available if SA_SIGINFO is set for the signal handler, as above.`
`F_GETSIG` | `Get the signal sent when input or output becomes possible. A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.`
`F_SETLEASE` | `Set or remove a file lease according to which of the following values is specified in the edx:`
`F_RDLCK` | `Take out a read lease. This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can only be placed on a file descriptor that is opened read-only.`
`F_WRLCK` | `Take out a write lease. This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if no other process currently has the file open.`
`F_UNLCK` | `Remove our lease from the file.`
`A process may hold only one type of lease on a file. Leases may only be taken out on regular files. An unprivileged process may only take out a lease on a file whose UID matches the file system UID of the process. A process with the CAP_LEASE capability may take out leases on arbitrary files.`
`F_GETLEASE` | `Indicates what type of lease we hold on the file referred to by file descriptor by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, that the calling process holds a read, a write, or no lease on the file. Argument in edx is omitted.`
`F_NOTIFY` | `Provide notification when the directory referred to by file descriptor or any of the files that it contains is changed. The events to be notified are specified in edx, which is a bit mask specified by ORing together zero or more of the following bits:` `DN_ACCESS - File accessed DN_MODIFY - File modified DN_CREATE - File created DN_DELETE - File removed DN_RENAME - File renamed DN_ATTRIB - File changed attributes`
edx | Depends on the ebx. See above.
Return values If the system call succeeds the return value depends on the performed operation (See above. If no return value is described then it's 0.) If the system call fails the return value is one of the following errno values:
`-EACCES, -EAGAIN` | `Operation is prohibited by locks held by other processes. Or, operation is prohibited because the file has been memory-mapped by another process.`
`-EBADF` | `File descriptor is not an open file descriptor, or the command was F_SETLK or F_SETLKW and the file descriptor open mode doesn't match with the type of lock requested.`
`-EDEADLK` | `It was detected that the specified F_SETLKW command would cause a deadlock`
`-EFAULT` | `flock is outside your accessible address space.`
`-EINTR` | `For F_SETLKW, the command was interrupted by a signal. For F_GETLK and F_SETLK, the command was interrupted by a signal before the lock was checked or acquired. Most likely when locking a remote file (e.g. locking over NFS), but can sometimes happen locally.`
`-EINVAL` | `For F_DUPFD, edx is negative or is greater than the maximum allowable value. For F_SETSIG, edx doesn't contain an allowable signal number.`
`-EMFILE` | `For F_DUPFD, the process already has the maximum number of file descriptors open.`
`-ENOLCK` | `Too many segment locks open, lock table is full, or a remote locking protocol failed (e.g. locking over NFS).`
`-EPERM` | `Attempted to clear the O_APPEND flag on a file that has the append-only attribute set.`
Remarks There is no interaction between the types of lock placed by sys_flock and sys_fcntl. Compatibility n/a