diff options
Diffstat (limited to 'man2/fcntl.2')
| -rw-r--r-- | man2/fcntl.2 | 252 |
1 files changed, 130 insertions, 122 deletions
diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 4973ab028..b01ed73d3 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -95,13 +95,13 @@ Duplicate the file descriptor using the lowest-numbered available file descriptor greater than or equal to .IR arg . This is different from -.BR dup2 (2), +.MR dup2 2 , which uses exactly the file descriptor specified. .IP On success, the new file descriptor is returned. .IP See -.BR dup (2) +.MR dup 2 for further details. .TP .BR F_DUPFD_CLOEXEC " (\fIint\fP; since Linux 2.6.24)" @@ -119,7 +119,7 @@ For an explanation of why this flag is useful, see the description of .B O_CLOEXEC in -.BR open (2). +.MR open 2 . .SS File descriptor flags The following commands manipulate the flags associated with a file descriptor. @@ -130,14 +130,14 @@ If the .B FD_CLOEXEC bit is set, the file descriptor will automatically be closed during a successful -.BR execve (2). +.MR execve 2 . (If the -.BR execve (2) +.MR execve 2 fails, the file descriptor is left open.) If the .B FD_CLOEXEC bit is not set, the file descriptor will remain open across an -.BR execve (2). +.MR execve 2 . .TP .BR F_GETFD " (\fIvoid\fP)" Return (as the function result) the file descriptor flags; @@ -152,34 +152,34 @@ In multithreaded programs, using .BR fcntl () .B F_SETFD to set the close-on-exec flag at the same time as another thread performs a -.BR fork (2) +.MR fork 2 plus -.BR execve (2) +.MR execve 2 is vulnerable to a race condition that may unintentionally leak the file descriptor to the program executed in the child process. See the discussion of the .B O_CLOEXEC flag in -.BR open (2) +.MR open 2 for details and a remedy to the problem. .SS File status flags Each open file description has certain associated status flags, initialized by -.BR open (2) +.MR open 2 .\" or .\" .BR creat (2), and possibly modified by .BR fcntl (). Duplicated file descriptors (made with -.BR dup (2), +.MR dup 2 , .BR fcntl (F_DUPFD), -.BR fork (2), +.MR fork 2 , etc.) refer to the same open file description, and thus share the same file status flags. .P The file status flags and their semantics are described in -.BR open (2). +.MR open 2 . .TP .BR F_GETFL " (\fIvoid\fP)" Return (as the function result) @@ -355,7 +355,7 @@ returns immediately (with return value \-1 and set to .BR EINTR ; see -.BR signal (7)). +.MR signal 7 ). .TP .BR F_GETLK " (\fIstruct flock *\fP)" On input to this call, @@ -424,17 +424,17 @@ As well as being removed by an explicit record locks are automatically released when the process terminates. .P Record locks are not inherited by a child created via -.BR fork (2), +.MR fork 2 , but are preserved across an -.BR execve (2). +.MR execve 2 . .P Because of the buffering performed by the -.BR stdio (3) +.MR stdio 3 library, the use of record locking with routines in that package should be avoided; use -.BR read (2) +.MR read 2 and -.BR write (2) +.MR write 2 instead. .P The record locks described above are associated with the process @@ -473,7 +473,7 @@ and available since Linux 3.15. .\" http://austingroupbugs.net/view.php?id=768 to include this lock type in the next revision of POSIX.1.) For an explanation of open file descriptions, see -.BR open (2). +.MR open 2 . .P The principal difference between the two lock types is that whereas traditional record locks @@ -481,12 +481,12 @@ are associated with a process, open file description locks are associated with the open file description on which they are acquired, much like locks acquired with -.BR flock (2). +.MR flock 2 . Consequently (and unlike traditional advisory record locks), open file description locks are inherited across -.BR fork (2) +.MR fork 2 (and -.BR clone (2) +.MR clone 2 with .BR CLONE_FILES ), and are only automatically released on the last close @@ -502,8 +502,8 @@ even when they are acquired by the same process on the same file descriptor. Open file description locks placed via the same open file description (i.e., via the same file descriptor, or via a duplicate of the file descriptor created by -.BR fork (2), -.BR dup (2), +.MR fork 2 , +.MR dup 2 , .BR fcntl () .BR F_DUPFD , and so on) are always compatible: @@ -517,7 +517,7 @@ each other when they are acquired via different open file descriptions. Thus, the threads in a multithreaded program can use open file description locks to synchronize access to a file region by having each thread perform its own -.BR open (2) +.MR open 2 on the file and applying locks via the resulting file descriptor. .P As with traditional advisory locks, the third argument to @@ -567,7 +567,7 @@ and (after the signal handler has returned) returns immediately set to .BR EINTR ; see -.BR signal (7)). +.MR signal 7 ). .TP .BR F_OFD_GETLK " (\fIstruct flock *\fP)" On input to this call, @@ -613,9 +613,9 @@ cooperating processes. Both lock types can also be mandatory. Mandatory locks are enforced for all processes. If a process tries to perform an incompatible access (e.g., -.BR read (2) +.MR read 2 or -.BR write (2)) +.MR write 2 ) on a file region that has an incompatible mandatory lock, then the result depends upon whether the .B O_NONBLOCK @@ -635,17 +635,17 @@ both on the filesystem that contains the file to be locked, and on the file itself. Mandatory locking is enabled on a filesystem using the "\-o mand" option to -.BR mount (8), +.MR mount 8 , or the .B MS_MANDLOCK flag for -.BR mount (2). +.MR mount 2 . Mandatory locking is enabled on a file by disabling group execute permission on the file and enabling the set-group-ID permission bit (see -.BR chmod (1) +.MR chmod 1 and -.BR chmod (2)). +.MR chmod 2 ). .P Mandatory locking is not specified by POSIX. Some other systems also support mandatory locking, @@ -660,9 +660,9 @@ which lasts long enough for the server to assume that the client is no longer functioning. .P When the filesystem determines that a lock has been lost, future -.BR read (2) +.MR read 2 or -.BR write (2) +.MR write 2 requests may fail with the error .BR EIO . This error will persist until the lock is removed or the file @@ -715,7 +715,7 @@ Most commonly, the calling process specifies itself as the owner (that is, .I arg is specified as -.BR getpid (2)). +.MR getpid 2 ). .IP As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. @@ -738,7 +738,7 @@ command can be used to obtain delivery of a signal other than Sending a signal to the owner process (group) specified by .B F_SETOWN is subject to the same permissions checks as are described for -.BR kill (2), +.MR kill 2 , where the sending process is the one that employs .B F_SETOWN (but see BUGS below). @@ -763,7 +763,7 @@ signals that are delivered when out-of-band data arrives on that socket. .RB ( SIGURG is sent in any situation where -.BR select (2) +.MR select 2 would report the socket as having an "exceptional condition".) .\" The following appears to be rubbish. It doesn't seem to .\" be true according to the kernel source, and I can write @@ -793,18 +793,18 @@ it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass .B F_SETOWN the result of -.BR gettid (2) +.MR gettid 2 instead of -.BR getpid (2) +.MR getpid 2 to get sensible results when .B 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 -.BR gettid (2) +.MR gettid 2 or -.BR getpid (2) +.MR getpid 2 in this scenario.) Note, however, that the statements in this paragraph do not apply to the @@ -882,9 +882,9 @@ is interpreted: .B F_OWNER_TID Send the signal to the thread whose thread ID (the value returned by a call to -.BR clone (2) +.MR clone 2 or -.BR gettid (2)) +.MR gettid 2 ) is specified in .IR pid . .TP @@ -946,7 +946,7 @@ with a nonzero value, and setting .B SA_SIGINFO for the signal handler (see -.BR sigaction (2)), +.MR sigaction 2 ), extra information about I/O events is passed to the handler in a .I siginfo_t @@ -961,9 +961,10 @@ 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 -.RB ( select (2), -.BR poll (2), -.BR read (2) +\%(\c +.MR select 2 , +.MR poll 2 , +.MR read 2 with .B O_NONBLOCK set etc.) to determine which file descriptors are available for I/O. @@ -993,9 +994,9 @@ is set for the signal handler, as above. Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see -.BR getrlimit (2) +.MR getrlimit 2 and -.BR signal (7)) +.MR signal 7 ) and if this limit is reached, then the kernel reverts to delivering .BR SIGIO , @@ -1005,9 +1006,9 @@ process rather than to a specific thread. .P Using these mechanisms, a program can implement fully asynchronous I/O without using -.BR select (2) +.MR select 2 or -.BR poll (2) +.MR poll 2 most of the time. .P The use of @@ -1044,9 +1045,9 @@ referred to by the file descriptor A file lease provides a mechanism whereby the process holding the lease (the "lease holder") is notified (via delivery of a signal) when a process (the "lease breaker") tries to -.BR open (2) +.MR open 2 or -.BR truncate (2) +.MR truncate 2 the file referred to by that file descriptor. .TP .BR F_SETLEASE " (\fIint\fP)" @@ -1076,11 +1077,11 @@ Remove our lease from the file. .RE .P Leases are associated with an open file description (see -.BR open (2)). +.MR open 2 ). This means that duplicate file descriptors (created by, for example, -.BR fork (2) +.MR fork 2 or -.BR dup (2)) +.MR dup 2 ) refer to the same lease, and this lease may be modified or released using any of these descriptors. Furthermore, the lease is released by either an explicit @@ -1105,9 +1106,9 @@ indicating, respectively, a read lease , a write lease, or no lease. is ignored. .P When a process (the "lease breaker") performs an -.BR open (2) +.MR open 2 or -.BR truncate (2) +.MR truncate 2 that conflicts with a lease established via .BR F_SETLEASE , the system call is blocked by the kernel and @@ -1155,22 +1156,22 @@ and assuming the lease breaker has not unblocked its system call, the kernel permits the lease breaker's system call to proceed. .P If the lease breaker's blocked -.BR open (2) +.MR open 2 or -.BR truncate (2) +.MR truncate 2 is interrupted by a signal handler, then the system call fails with the error .BR EINTR , but the other steps still occur as described above. If the lease breaker is killed by a signal while blocked in -.BR open (2) +.MR open 2 or -.BR truncate (2), +.MR truncate 2 , then the other steps still occur as described above. If the lease breaker specifies the .B O_NONBLOCK flag when calling -.BR open (2), +.MR open 2 , then the call immediately fails with the error .BR EWOULDBLOCK , but the other steps still occur as described above. @@ -1212,48 +1213,54 @@ the following bits: .TP .B DN_ACCESS A file was accessed -.RB ( read (2), -.BR pread (2), -.BR readv (2), +\%(\c +.MR read 2 , +.MR pread 2 , +.MR readv 2 , and similar) .TP .B DN_MODIFY A file was modified -.RB ( write (2), -.BR pwrite (2), -.BR writev (2), -.BR truncate (2), -.BR ftruncate (2), +\%(\c +.MR write 2 , +.MR pwrite 2 , +.MR writev 2 , +.MR truncate 2 , +.MR ftruncate 2 , and similar). .TP .B DN_CREATE A file was created -.RB ( open (2), -.BR creat (2), -.BR mknod (2), -.BR mkdir (2), -.BR link (2), -.BR symlink (2), -.BR rename (2) +\%(\c +.MR open 2 , +.MR creat 2 , +.MR mknod 2 , +.MR mkdir 2 , +.MR link 2 , +.MR symlink 2 , +.MR rename 2 into this directory). .TP .B DN_DELETE A file was unlinked -.RB ( unlink (2), -.BR rename (2) +\%(\c +.MR unlink 2 , +.MR rename 2 to another directory, -.BR rmdir (2)). +.MR rmdir 2 ). .TP .B DN_RENAME A file was renamed within this directory -.RB ( rename (2)). +\%(\c +.MR rename 2 ). .TP .B DN_ATTRIB The attributes of a file were changed -.RB ( chown (2), -.BR chmod (2), -.BR utime (2), -.BR utimensat (2), +\%(\c +.MR chown 2 , +.MR chmod 2 , +.MR utime 2 , +.MR utimensat 2 , and similar). .PD .RE @@ -1319,7 +1326,7 @@ interface (available since Linux 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See -.BR inotify (7). +.MR inotify 7 . .SS Changing the capacity of a pipe .TP .BR F_SETPIPE_SZ " (\fIint\fP; since Linux 2.6.35)" @@ -1332,7 +1339,7 @@ An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in .I /proc/sys/fs/pipe\-max\-size (see -.BR proc (5)). +.MR proc 5 ). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in @@ -1376,11 +1383,11 @@ The default set of seals depends on the type of the underlying file and filesystem. For an overview of file sealing, a discussion of its purpose, and some code examples, see -.BR memfd_create (2). +.MR memfd_create 2 . .P Currently, file seals can be applied only to a file descriptor returned by -.BR memfd_create (2) +.MR memfd_create 2 (if the .B MFD_ALLOW_SEALING was employed). @@ -1439,13 +1446,13 @@ then this effectively causes the set of seals to be constant and locked. .B F_SEAL_SHRINK If this seal is set, the file in question cannot be reduced in size. This affects -.BR open (2) +.MR open 2 with the .B O_TRUNC flag as well as -.BR truncate (2) +.MR truncate 2 and -.BR ftruncate (2). +.MR ftruncate 2 . Those calls fail with .B EPERM if you try to shrink the file in question. @@ -1454,12 +1461,12 @@ Increasing the file size is still possible. .B F_SEAL_GROW If this seal is set, the size of the file in question cannot be increased. This affects -.BR write (2) +.MR write 2 beyond the end of the file, -.BR truncate (2), -.BR ftruncate (2), +.MR truncate 2 , +.MR ftruncate 2 , and -.BR fallocate (2). +.MR fallocate 2 . These calls fail with .B EPERM if you use them to increase the file size. @@ -1479,9 +1486,9 @@ still possible and allowed. .\" Thus, this seal is normally used in combination with one of the other seals. This seal affects -.BR write (2) +.MR write 2 and -.BR fallocate (2) +.MR fallocate 2 (only in combination with the .B FALLOC_FL_PUNCH_HOLE flag). @@ -1489,7 +1496,7 @@ Those calls fail with .B EPERM if this seal is set. Furthermore, trying to create new shared, writable memory-mappings via -.BR mmap (2) +.MR mmap 2 will also fail with .BR EPERM . .IP @@ -1502,7 +1509,8 @@ seal fails with if any writable, shared mapping exists. Such mappings must be unmapped before you can add this seal. Furthermore, if there are any asynchronous I/O operations -.RB ( io_submit (2)) +\%(\c +.MR io_submit 2 ) pending on the file, all outstanding writes will be discarded. .TP @@ -1512,11 +1520,11 @@ The effect of this seal is similar to but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set. Any attempt to create a new writable mapping on the file via -.BR mmap (2) +.MR mmap 2 will fail with .BR EPERM . Likewise, an attempt to write to the file via -.BR write (2) +.MR write 2 will fail with .BR EPERM . .IP @@ -1529,7 +1537,7 @@ Write lifetime hints can be used to inform the kernel about the relative expected lifetime of writes on a given inode or via a particular open file description. (See -.BR open (2) +.MR open 2 for an explanation of open file descriptions.) In this context, the term "write lifetime" means the expected time the data will live on media, before @@ -1702,7 +1710,7 @@ is or .B F_OFD_SETLKW and the operation was interrupted by a signal; see -.BR signal (7). +.MR signal 7 . .TP .B EINTR .I cmd @@ -1750,7 +1758,7 @@ is negative or is greater than the maximum allowable value (see the discussion of .B RLIMIT_NOFILE in -.BR getrlimit (2)). +.MR getrlimit 2 ). .TP .B EINVAL .I cmd @@ -1795,7 +1803,7 @@ does not refer to a directory. is .B F_SETPIPE_SZ and the soft or hard user pipe limit has been reached; see -.BR pipe (7). +.MR pipe 7 . .TP .B EPERM Attempted to clear the @@ -1881,7 +1889,7 @@ with the value 200809L or greater, or with the value 700 or greater.) .SH NOTES The errors returned by -.BR dup2 (2) +.MR dup2 2 are different from those returned by .BR F_DUPFD . .\" @@ -1910,7 +1918,7 @@ where it is available. .SS Record locks Since Linux 2.0, there is no interaction between the types of lock placed by -.BR flock (2) +.MR flock 2 and .BR fcntl (). .P @@ -2063,7 +2071,7 @@ meaning that circular deadlock chains that exceed that size will not be detected. In addition, the kernel may falsely indicate a deadlock when two or more processes created using the -.BR clone (2) +.MR clone 2 .B CLONE_FILES flag place locks that appear (to the kernel) to conflict. .\" @@ -2079,25 +2087,25 @@ is subject to race conditions which render it unreliable: .\" Date: 2014-04-28 10:07:57 GMT .\" http://thread.gmane.org/gmane.linux.file-systems/84481/focus=84518 a -.BR write (2) +.MR write 2 call that overlaps with a lock may modify data after the mandatory lock is acquired; a -.BR read (2) +.MR read 2 call that overlaps with a lock may detect changes to data that were made only after a write lock was acquired. Similar races exist between mandatory locks and -.BR mmap (2). +.MR mmap 2 . It is therefore inadvisable to rely on mandatory locking. .SH SEE ALSO -.BR dup2 (2), -.BR flock (2), -.BR open (2), -.BR socket (2), -.BR lockf (3), -.BR capabilities (7), -.BR feature_test_macros (7), -.BR lslocks (8) +.MR dup2 2 , +.MR flock 2 , +.MR open 2 , +.MR socket 2 , +.MR lockf 3 , +.MR capabilities 7 , +.MR feature_test_macros 7 , +.MR lslocks 8 .P .IR locks.txt , .IR mandatory\-locking.txt , |