[Linux manuál]
Návod, kniha: POSIX Programmer's Manual
#include <fcntl.h>
int fcntl(int fildes, int
cmd, ...);
fcntl: ovládání souborů
Originální popis anglicky: fcntl - file controlNávod, kniha: POSIX Programmer's Manual
STRUČNĚ
#include <unistd.h>POPIS / INSTRUKCE
The fcntl() function shall perform the operations described below on open files. The fildes argument is a file descriptor. The available values for cmd are defined in <fcntl.h> and are as follows:- F_DUPFD
- Return a new file descriptor which shall be 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 shall refer to the same open file description as the original file descriptor, and shall share any locks. The FD_CLOEXEC flag associated with the new file descriptor shall be cleared to keep the file open across calls to one of the exec functions.
- 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 type int. If the FD_CLOEXEC flag in the third argument is 0, the file shall remain open across the exec functions; otherwise, the file shall be closed upon successful execution of one of the exec functions.
- F_GETFL
- Get the file status flags and file access modes, defined in <fcntl.h>, for the file description associated with 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 and file access modes are associated with the file description and do not affect other file descriptors that refer to the same file with different open file descriptions.
- F_SETFL
- Set the file status flags, defined in <fcntl.h>, for the file description associated with fildes from the corresponding bits in the third argument, arg, taken as type int. Bits corresponding to the file access mode and the file creation flags, as defined in <fcntl.h>, that are set in arg shall be ignored. If any bits in arg other than those mentioned here are changed by the application, the result is unspecified.
- 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 available. 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_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 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. If fildes does not
refer to a socket, the results are unspecified.
- 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, defined in <fcntl.h>. The information retrieved shall overwrite the information passed to fcntl() in the structure flock. If no lock is found that would prevent this lock from being created, then the structure shall be left unchanged except for the lock type which shall be set to F_UNLCK.
- 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, defined in <fcntl.h>. F_SETLK can 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). F_RDLCK, F_WRLCK, and F_UNLCK are defined in <fcntl.h>. If a shared or exclusive lock cannot be set, fcntl() shall return immediately with a return value of -1.
- F_SETLKW
- This command shall be equivalent to F_SETLK except that if
a shared or exclusive lock is blocked by other locks, the thread shall
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()
shall be interrupted. Upon return from the signal handler, fcntl()
shall return -1 with errno set to [EINTR], and the lock operation
shall not be done.
- l_type
- Type of blocking lock found.
- l_whence
- SEEK_SET.
- l_start
- Start of the blocking lock.
- l_len
- Length of the blocking lock.
- l_pid
- Process ID of the process that holds the blocking lock.
NÁVRATOVÁ HODNOTA
Upon successful completion, the value returned shall depend on cmd as follows:- F_DUPFD
- A new file descriptor.
- F_GETFD
- Value of flags defined in <fcntl.h>. The return value shall not be negative.
- F_SETFD
- Value other than -1.
- F_GETFL
- Value of file status flags and access modes. The return value is not negative.
- 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_GETOWN
- Value of the socket owner process or process group; this will not be -1.
- F_SETOWN
- Value other than -1.
CHYBY / ERRORY
The fcntl() function shall fail if:- EACCES or EAGAIN
-
The cmd argument is F_SETLK; 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 exclusive-locked by another process.
- EBADF
- The fildes argument is not a valid open file descriptor, or the argument cmd is F_SETLK or F_SETLKW, 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.
- EINTR
- The cmd argument is F_SETLKW and the function was interrupted by a signal.
- EINVAL
- The cmd argument is invalid, or the cmd argument is F_DUPFD and arg is negative or greater than or equal to {OPEN_MAX}, or the cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by arg is not valid, or fildes refers to a file that does not support locking.
- EMFILE
- The argument cmd is F_DUPFD and {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 argument cmd is F_SETLK or F_SETLKW and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit.
- EOVERFLOW
- One of the values to be returned cannot be represented correctly.
- EOVERFLOW
- 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.
- EDEADLK
- The cmd argument is F_SETLKW, the lock is blocked by
a lock from another process, and putting the calling process to sleep to
wait for that lock to become free would cause a deadlock.
PŘÍKLADY POUŽITÍ
None.APPLICATION USAGE
None.RATIONALE
The ellipsis in the SYNOPSIS is the syntax specified by the ISO C standard for a variable number of arguments. It is used because System V uses pointers for the implementation of file locking functions. The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag values to allow for future growth. Applications using these functions should do a read-modify-write operation on them, rather than assuming that only the values defined by this volume of IEEE Std 1003.1-2001 are valid. It is a common error to forget this, particularly in the case of F_SETFD. This volume of IEEE Std 1003.1-2001 permits concurrent read and write access to file data using the fcntl() function; this is a change from the 1984 /usr/group standard and early proposals. Without concurrency controls, this feature may not be fully utilized without occasional loss of data. Data losses occur in several ways. One case occurs when several processes try to update the same record, without sequencing controls; several updates may occur in parallel and the last writer "wins". Another case is a bit-tree or other internal list-based database that is undergoing reorganization. Without exclusive use to the tree segment by the updating process, other reading processes chance getting lost in the database when the index blocks are split, condensed, inserted, or deleted. While fcntl() is useful for many applications, it is not intended to be overly general and does not handle the bit-tree example well. This facility is only required for regular files because it is not appropriate for many devices such as terminals and network connections. Since fcntl() works with "any file descriptor associated with that file, however it is obtained", the file descriptor may have been inherited through a fork() or exec operation and thus may affect a file that another process also has open. The use of the open file description to identify what to lock requires extra calls and presents problems if several processes are sharing an open file description, but there are too many implementations of the existing mechanism for this volume of IEEE Std 1003.1-2001 to use different specifications. Another consequence of this model is that closing any file descriptor for a given file (whether or not it is the same open file description that created the lock) causes the locks on that file to be relinquished for that process. Equivalently, any close for any file/process pair relinquishes the locks owned on that file for that process. But note that while an open file description may be shared through fork(), locks are not inherited through fork(). Yet locks may be inherited through one of the exec functions. The identification of a machine in a network environment is outside the scope of this volume of IEEE Std 1003.1-2001. Thus, an l_sysid member, such as found in System V, is not included in the locking structure. Changing of lock types can result in a previously locked region being split into smaller regions. Mandatory locking was a major feature of the 1984 /usr/group standard. For advisory file record locking to be effective, all processes that have access to a file must cooperate and use the advisory mechanism before doing I/O on the file. Enforcement-mode record locking is important when it cannot be assumed that all processes are cooperating. For example, if one user uses an editor to update a file at the same time that a second user executes another process that updates the same file and if only one of the two processes is using advisory locking, the processes are not cooperating. Enforcement-mode record locking would protect against accidental collisions. Secondly, advisory record locking requires a process using locking to bracket each I/O operation with lock (or test) and unlock operations. With enforcement-mode file and record locking, a process can lock the file once and unlock when all I/O operations have been completed. Enforcement-mode record locking provides a base that can be enhanced; for example, with sharable locks. That is, the mechanism could be enhanced to allow a process to lock a file so other processes could read it, but none of them could write it. Mandatory locks were omitted for several reasons:- 1.
- Mandatory lock setting was done by multiplexing the set-group-ID bit in most implementations; this was confusing, at best.
- 2.
- The relationship to file truncation as supported in 4.2 BSD was not well specified.
- 3.
- Any publicly readable file could be locked by anyone. Many historical implementations keep the password database in a publicly readable file. A malicious user could thus prohibit logins. Another possibility would be to hold open a long-distance telephone line.
- 4.
- Some demand-paged historical implementations offer memory mapped files, and enforcement cannot be done on that type of file.
FUTURE DIRECTIONS
None.SOUVISEJÍCÍ
alarm() , close() , exec() , open() , sigaction() , the Base Definitions volume of IEEE Std 1003.1-2001, <fcntl.h>, <signal.h>, <unistd.h>COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .| 2003 | IEEE/The Open Group |