Lines Matching refs:file
6 operations on file descriptors. These functions include the primitives
20 For reading an entire file into core before parsing it.
34 * Opening and Closing Files:: How to open and close file
37 * File Position Primitive:: Setting a descriptor's file
47 on multiple file descriptors.
50 * Control Operations:: Various other operations on file
53 file descriptors.
55 flags associated with file
60 file locking.
62 open file description locking.
63 * Open File Description Locks Example:: An example of open file description lock
74 @cindex opening a file descriptor
75 @cindex closing a file descriptor
77 using file descriptors. The @code{open} and @code{creat} functions are
78 declared in the header file @file{fcntl.h}, while @code{close} is
79 declared in @file{unistd.h}.
86 The @code{open} function creates and returns a new file descriptor for
87 the file named by @var{filename}. Initially, the file position
88 indicator for the file is at the beginning of the file. The argument
89 @var{mode} (@pxref{Permission Bits}) is used only when a file is
92 The @var{flags} argument controls how the file is to be opened. This is
97 The normal return value from @code{open} is a non-negative integer file
99 instead. In addition to the usual file name errors (@pxref{File
105 The file exists but is not readable/writable as requested by the @var{flags}
106 argument, or the file does not exist and the directory is unwritable so
110 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
118 The @var{flags} argument specified write access, and the file is a directory.
122 The maximum number of file descriptors is controlled by the
126 The entire system, or perhaps the file system which contains the
131 The named file does not exist, and @code{O_CREAT} is not specified.
134 The directory or file system that would contain the new file cannot be
139 argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
140 FIFOs}), and no process has the file open for reading.
143 The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
145 or @code{O_CREAT} is set and the file does not already exist.
151 @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
152 descriptor opened in the large file mode which enables the file handling
155 since all of the low-level file handling functions are equally replaced.
158 is a problem if the thread allocates some resources (like memory, file
172 This function is similar to @code{open}. It returns a file descriptor
173 which can be used to access the file named by @var{filename}. The only
174 difference is that on 32 bit systems the file is opened in the
175 large file mode. I.e., file length and file offsets can exceed 31 bits.
179 new, extended API using 64 bit file sizes and offsets transparently
200 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
201 descriptor opened in the large file mode which enables the file handling
204 since all of the low-level file handling functions are equally replaced.
210 This function is similar to @code{creat}. It returns a file descriptor
211 which can be used to access the file named by @var{filename}. The only
212 difference is that on 32 bit systems the file is opened in the
213 large file mode. I.e., file length and file offsets can exceed 31 bits.
215 To use this file descriptor one must not use the normal operations but
220 new, extended API using 64 bit file sizes and offsets transparently
227 The function @code{close} closes the file descriptor @var{filedes}.
228 Closing a file has the following consequences:
232 The file descriptor is deallocated.
235 Any record locks owned by the process on the file are unlocked.
238 When all file descriptors associated with a pipe or FIFO have been closed,
243 is a problem if the thread allocates some resources (like memory, file
256 The @var{filedes} argument is not a valid file descriptor.
270 When the file is accessed by NFS, these errors from @code{write} can sometimes
277 on the mode of the file. The kernel which performs the @code{close}
283 of trying to close its underlying file descriptor with @code{close}.
293 The function @code{close_range} closes the file descriptor from @var{lowfd}
295 specified file descriptor range depending on the @var{flags}.
306 Unshare the file descriptor table before closing file descriptors.
309 Set the @code{FD_CLOEXEC} bit instead of closing the file descriptor.
329 The maximum number of file descriptors is controlled by the
341 The function @code{closefrom} closes all file descriptors greater than or equal
343 @code{close} for all open file descriptors not less than @var{lowfd}.
345 Already closed file descriptors are ignored.
352 output operations on file descriptors: @code{read}, @code{write}, and
353 @code{lseek}. These functions are declared in the header file
354 @file{unistd.h}.
364 @cindex reading from a file descriptor
368 The @code{read} function reads up to @var{size} bytes from the file
373 @cindex end-of-file, on a file descriptor
376 in the file or if there aren't that many bytes immediately available.
377 The exact behavior depends on what kind of file it is. Note that
380 A value of zero indicates end-of-file (except if the value of the
382 If you keep calling @code{read} while at end-of-file, it will keep
386 tell whether end-of-file was reached. But if you did reach the end, the
395 some input. But if the @code{O_NONBLOCK} flag is set for the file
405 file can also fail with @code{EAGAIN} if the kernel cannot find enough
417 The @var{filedes} argument is not a valid file descriptor,
445 possibly wide file offset. Since the kernel handles this state
449 is a problem if the thread allocates some resources (like memory, file
471 is not read from the current position of the file descriptor
472 @code{filedes}. Instead the data is read from the file starting at
473 position @var{offset}. The position of the file descriptor itself is
476 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
490 The file descriptor @var{filedes} is associated with a pipe or a FIFO and
491 this device does not allow positioning of the file pointer.
508 file descriptor @code{filedes} must be opened using @code{open64} since
510 errors with a descriptor in small file mode.
512 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
517 @cindex writing to a file descriptor
522 @c the vfs_write() does no locking around the acquisition of a file offset and
531 @c file position and that the file position is updated *before* the function
540 @c should never see interleaving sets of file operations, but it is insane
547 @c The fix for file offsets racing was merged in 3.14, the commits were:
552 @var{buffer} to the file with descriptor @var{filedes}. The data in
567 @code{fdatasync} which guarantees integrity only for the file data and
579 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
592 file can also fail with @code{EAGAIN} if the kernel cannot find enough
600 The @var{filedes} argument is not a valid file descriptor,
604 The size of the file would become larger than the implementation can support.
618 The device containing the file is full.
643 possibly wide file offset. Since the kernel handles this state
647 is a problem if the thread allocates some resources (like memory, file
669 is not written to the current position of the file descriptor
670 @code{filedes}. Instead the data is written to the file starting at
671 position @var{offset}. The position of the file descriptor itself is
674 However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite}
675 appends data to the end of the file, regardless of the value of
678 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
692 The file descriptor @var{filedes} is associated with a pipe or a FIFO and
693 this device does not allow positioning of the file pointer.
710 file descriptor @code{filedes} must be opened using @code{open64} since
712 errors with a descriptor in small file mode.
714 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
722 Just as you can set the file position of a stream with @code{fseek}, you
723 can set the file position of a descriptor with @code{lseek}. This
724 specifies the position in the file for the next @code{read} or
726 on the file position and what it means.
728 To read the current file position value from a descriptor, use
731 @cindex file positioning on a file descriptor
732 @cindex positioning a file descriptor
733 @cindex seeking on a file descriptor
737 The @code{lseek} function is used to change the file position of the
738 file with descriptor @var{filedes}.
748 of the file.
752 file position. This count may be positive or negative.
756 the file. A negative count specifies a position within the current
757 extent of the file; a positive count specifies a position past the
759 actually write data, you will extend the file with zeros up to that
763 The return value from @code{lseek} is normally the resulting file
764 position, measured in bytes from the beginning of the file.
766 current file position.
768 If you want to append to the file, setting the file position to the
769 current end of file with @code{SEEK_END} is not sufficient. Another
771 extending the file so the position you write onto clobbers their data.
774 You can set the file position past the current end of the file. This
775 does not by itself make the file longer; @code{lseek} never changes the
776 file. But subsequent output at that position will extend the file.
777 Characters between the previous end of file and the new position are
778 filled with zeros. Extending the file in this way can create a
780 file takes up less space than it appears to; it is then called a
781 ``sparse file''.
785 If the file position cannot be changed, or the operation is in some way
791 The @var{filedes} is not a valid file descriptor.
795 file offset is not valid. A file offset is invalid.
804 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
810 is a problem if the thread allocates some resources (like memory, file
819 @code{rewind} functions, which operate on streams instead of file
830 file descriptor @code{filedes} must be opened using @code{open64} since
832 errors with a descriptor in small file mode.
834 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
839 You can have multiple descriptors for the same file if you open the file
842 file positions; using @code{lseek} on one descriptor has no effect on the
859 will read the first four characters of the file @file{foo}. (The
863 By contrast, descriptors made by duplication share a common file
865 which alters the file position of one of the duplicates, including
883 @file{foo}, and then four more characters starting with the 1028'th
888 This is a signed integer type used to represent file sizes. In
908 different header files: @file{fcntl.h} and @file{sys/file.h}.
923 @cindex streams, and file descriptors
924 @cindex converting file descriptor to stream
925 @cindex extracting file descriptor from stream
927 Given an open file descriptor, you can create a stream for it with the
928 @code{fdopen} function. You can get the underlying file descriptor for
930 declared in the header file @file{stdio.h}.
936 The @code{fdopen} function returns a new stream for the file descriptor
943 @code{"w+"} do not cause truncation of the file; these have an effect only
944 when opening a file, and in this case the file has already been opened.
946 mode of the open file descriptor.
949 (for example, if the modes for the file indicated by the file descriptor
954 for file descriptors do not permit the access specified by
964 This function returns the file descriptor associated with the stream
966 is not valid) or if @var{stream} does not do I/O to a file,
980 @cindex standard file descriptors
981 @cindex file descriptors, standard
982 There are also symbolic constants defined in @file{unistd.h} for the
983 file descriptors belonging to the standard streams @code{stdin},
990 This macro has value @code{0}, which is the file descriptor for
992 @cindex standard input file descriptor
996 This macro has value @code{1}, which is the file descriptor for
998 @cindex standard output file descriptor
1002 This macro has value @code{2}, which is the file descriptor for
1005 @cindex standard error file descriptor
1014 You can have multiple file descriptors and streams (let's call both
1016 file, but you must take care to avoid confusion between channels. There
1018 file position value, and @dfn{independent} channels that have their own
1019 file positions.
1022 transfer to any given file, except when all the access is for input.
1023 For example, if you open a pipe (something you can only do at the file
1029 * Linked Channels:: Dealing with channels sharing a file position.
1039 Channels that come from a single opening share the same file position;
1058 streams persist in other processes, their file positions become
1067 file, each channel has its own file position. These are called
1072 can read or write sequentially at its own place in the file. However,
1078 that might read or write from the same part of the file.
1086 If you do output to one channel at the end of the file, this will
1088 before the new end. You cannot reliably set their file positions to the
1089 new end of file before writing, because the file can always be extended
1090 by another process between when you set the file position and when you
1092 always output at the current end of the file. In order to make the
1093 end-of-file position accurate, you must clean the output channel you
1096 It's impossible for two channels to have separate file pointers for a
1097 file that doesn't support random access. Thus, channels for reading or
1111 at end-of-file is clean. A line-buffered stream is clean when the last
1116 systems. This is when the stream is doing input from a file that is not
1117 random-access. Such streams typically read ahead, and when the file is
1119 read. When an input stream reads from a random-access file,
1120 @code{fflush} does clean the stream, but leaves the file pointer at an
1121 unpredictable place; you must set the file pointer before doing any
1129 the file position and are not affected by it. You can use any
1189 indicating end-of-file, or @math{-1} indicating an error. The possible
1225 @code{pread}. The data is read from the file starting at position
1226 @var{offset}. The position of the file descriptor itself is not affected
1229 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1235 indicating end-of-file, or @math{-1} indicating an error. The possible
1251 file descriptor @code{filedes} must be opened using @code{open64} since
1253 errors with a descriptor in small file mode.
1255 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1270 @code{pwrite}. The data is written to the file starting at position
1271 @var{offset}. The position of the file descriptor itself is not affected
1274 However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite}
1275 appends data to the end of the file, regardless of the value of
1278 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1284 indicating end-of-file, or @math{-1} indicating an error. The possible
1300 file descriptor @code{filedes} must be opened using @code{open64} since
1302 errors with a descriptor in small file mode.
1304 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1317 Additionally, if @var{offset} is @math{-1}, the current file position
1325 High priority request. This adds a flag that tells the file system that
1331 Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag.
1334 Per-IO synchronization as if the file was opened with @code{O_SYNC} flag.
1341 Per-IO synchronization as if the file was opened with @code{O_APPEND} flag.
1344 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1350 indicating end-of-file, or @math{-1} indicating an error. The possible
1375 file descriptor @code{filedes} must be opened using @code{open64} since
1377 errors with a descriptor in small file mode.
1379 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1393 Additionally, if @var{offset} is @math{-1}, the current file position
1399 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1405 indicating end-of-file, or @math{-1} indicating an error. The possible
1419 file descriptor @code{filedes} must be opened using @code{open64} since
1421 errors with a descriptor in small file mode.
1423 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1431 @cindex file copy
1434 same file system. The system can optimize such copy operations. This
1435 is particularly important on network file systems, where the data would
1438 Note that this function only copies file data, but not metadata such as
1439 file permissions or extended attributes.
1445 This function copies up to @var{length} bytes from the file descriptor
1446 @var{inputfd} to the file descriptor @var{outputfd}.
1448 The function can operate on both the current file position (like
1450 and @code{pwrite}). If the @var{inputpos} pointer is null, the file
1452 operation, and the file position is advanced during it. If
1455 incremented by the number of copied bytes, but the file position remains
1457 for the output file position.
1462 This can be less than the specified @var{length} in case the input file
1464 failure occurs. The return value is zero if the end of the input file
1481 to a non-regular, non-directory file (such as a socket or a FIFO).
1489 The new file size would exceed the process file size limit.
1493 outside of an implementation-defined limit. This can happen if the file
1494 was not opened with large file support (LFS) on 32-bit machines, and the
1495 copy operation would create a file which is larger than what
1499 The argument @var{inputfd} is not a valid file descriptor open for
1502 The argument @var{outputfd} is not a valid file descriptor open for
1511 cancellation, the input location (the file position or the value at
1519 ``em-map'') a file to a region of memory. When this is done, the file can
1523 of the file that a program actually accesses are loaded. Accesses to
1527 Since mmapped pages can be stored back to their file when physical
1532 reserved for other purposes. If the LFS interface is used the file size
1550 The following functions are declared in @file{sys/mman.h}:
1557 (@var{offset}) to (@var{offset} + @var{length} - 1) in the file open on
1558 @var{filedes}. A new reference for the file specified by @var{filedes}
1559 is created, which is not removed by closing the file.
1580 to the attached file. Instead, a copy is made for the process, and the
1590 file. Changes made will be shared immediately with other processes
1591 mmaping the same file.
1595 using conventional I/O get a consistent view of the file.
1606 to a file. @var{filedes} and @var{offset} are ignored, and the region is
1611 without creating a file.
1633 Not all file systems support mappings with an increased page size.
1659 If @code{MAP_HUGETLB} was specified, the file or system does not support
1673 This file is of a type that doesn't support mapping.
1677 The file is on a filesystem that doesn't support mapping.
1679 @c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock.
1683 @c here) is used and the file is already open for writing.
1696 this allows the file associated with the @var{filedes} descriptor to be
1703 new, extended API using 64 bit file sizes and offsets transparently
1737 When using shared mappings, the kernel can write the file at any time
1739 written to the file and will be accessible to non-memory-mapped I/O, it
1753 Normally @code{msync} only makes sure that accesses to a file with
1821 Not all file descriptors may be mapped. Sockets, pipes, and most devices
1933 This function returns a file descriptor that can be used to allocate shared
1943 @code{shm_open} returns the file descriptor on success or @math{-1} on error.
1966 The @code{memfd_create} function returns a file descriptor which can be
1972 appear in @file{/proc}), and separate invocations of @code{memfd_create}
1977 The descriptor initially refers to a zero-length file. Before mappings
1978 can be created which are backed by memory, the file size needs to be
1995 This requests that mappings created using the returned file descriptor
2001 @code{memfd_create} returns a file descriptor on success, and @math{-1}
2016 The operation would exceed the file descriptor limit for this process.
2019 The operation would exceed the system-wide file descriptor limit.
2041 blocks the program until input is available on one particular file
2043 nonblocking mode and poll each file descriptor in turn, but this is very
2047 program until input or output is ready on a specified set of file
2049 facility is declared in the header file @file{sys/types.h}.
2058 @cindex file descriptor sets, for @code{select}
2059 The file descriptor sets for the @code{select} function are specified
2065 The @code{fd_set} data type represents file descriptor sets for the
2071 The value of this macro is the maximum number of file descriptors that a
2076 controls the number of bits in an @code{fd_set}; if you get a file
2084 This macro initializes the file descriptor set @var{set} to be the
2093 This macro adds @var{filedes} to the file descriptor set @var{set}.
2104 This macro removes @var{filedes} from the file descriptor set @var{set}.
2114 of the file descriptor set @var{set}, and zero (false) otherwise.
2129 activity on any of the specified sets of file descriptors, or until the
2132 The file descriptors specified by the @var{read-fds} argument are
2133 checked to see if they are ready for reading; the @var{write-fds} file
2135 @var{except-fds} file descriptors are checked for exceptional
2139 A file descriptor is considered ready for reading if a @code{read}
2141 the end of the file or there is an error to report. A server socket
2153 The @code{select} function checks only the first @var{nfds} file
2159 one of the file descriptors is ready. Otherwise, you should provide
2165 The normal return value from @code{select} is the total number of ready file
2182 the argument file descriptor sets. The following @code{errno} error
2187 One of the file descriptor sets specified an invalid file descriptor.
2202 timeout period for reading from a file descriptor. The @code{input_timeout}
2204 file descriptor, or until the timeout period expires.
2235 A prototype for @code{sync} can be found in @file{unistd.h}.
2238 Programs more often want to ensure that data written to a given file is
2246 the open file @var{fildes} is written to the device associated with the
2250 A prototype for @code{fsync} can be found in @file{unistd.h}.
2253 is a problem if the thread allocates some resources (like memory, file
2273 file descriptor. E.g., in database files which do not change in size it
2274 is enough to write all the file content data to the device.
2277 recovery of the file in case of a problem.
2283 that all of the file data is written to the device. For all pending I/O
2291 The prototype for @code{fdatasync} is in @file{unistd.h}.
2314 @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
2317 @file{librt}. They are not actually part of the @file{libc} binary.
2321 with the thread library @file{libpthread} in addition to @file{librt}.
2324 might be arbitrarily many operations running for one file. The
2327 @file{aio.h} as follows.
2338 This element specifies the file descriptor to be used for the
2342 The device on which the file is opened must allow the seek operation.
2347 This element specifies the offset in the file at which the operation (input
2349 order and more than one operation for one file descriptor can be
2350 started, one cannot expect a current read/write position of the file
2385 Start a read operation. Read from the file at position
2391 @code{aio_buf} into the file starting at position @code{aio_offset}.
2415 This element specifies the file descriptor which is used for the
2419 The device on which the file is opened must allow the seek operation.
2424 This element specifies at which offset in the file the operation (input
2426 order and more than one operation for one file descriptor can be
2427 started, one cannot expect a current read/write position of the file
2636 The first @code{aiocbp->aio_nbytes} bytes of the file for which
2639 position @code{aiocbp->aio_offset} in the file.
2698 difference is that on @w{32 bit} machines, the file descriptor should
2699 be opened in the large file mode. Internally, @code{aio_read64} uses
2701 Primitive}) to position the file descriptor correctly for the reading,
2709 To write data asynchronously to a file, there exists an equivalent pair
2720 @code{aiocbp->aio_buf} are written to the file for which
2722 position @code{aiocbp->aio_offset} in the file.
2782 difference is that on @w{32 bit} machines the file descriptor should
2783 be opened in the large file mode. Internally @code{aio_write64} uses
2785 Primitive}) to position the file descriptor correctly for the writing,
2809 meant for the same file, all for different files or every solution in
2891 difference is that on @w{32 bit} machines, the file descriptor should
2892 be opened in the large file mode. Internally, @code{lio_listio64} uses
2894 Primitive}) to position the file descriptor correctly for the reading or
2997 if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
3006 time of the function call operating on the file descriptor
3011 file descriptor have terminated and the file is synchronized. This also
3012 means that requests for this very same file descriptor which are queued
3026 consistency of the data written to this file descriptor.
3036 The file descriptor @code{@var{aiocbp}->aio_fildes} is not valid.
3136 to be written in a file which will be updated by an enqueued request.
3157 the file descriptor @var{fildes} (i.e., whose @code{aio_fildes} member
3188 The file descriptor @var{fildes} is not valid.
3276 file descriptors, such as inquiring about or setting flags describing
3277 the status of the file descriptor, manipulating record locks, and the
3282 various flags that are used with it are declared in the header file
3283 @file{fcntl.h}. Many of these flags are also used by the @code{open}
3291 @var{command} on the file descriptor @var{filedes}. Some commands
3300 Duplicate the file descriptor (return another file descriptor pointing
3301 to the same open file). @xref{Duplicating Descriptors}.
3304 Get flags associated with the file descriptor. @xref{Descriptor Flags}.
3307 Set flags associated with the file descriptor. @xref{Descriptor Flags}.
3310 Get flags associated with the open file. @xref{File Status Flags}.
3313 Set flags associated with the open file. @xref{File Status Flags}.
3316 Test a file lock. @xref{File Locks}.
3319 Set or clear a file lock. @xref{File Locks}.
3325 Test an open file description lock. @xref{Open File Description Locks}.
3329 Set or clear an open file description lock. @xref{Open File Description Locks}.
3348 resources (like memory, file descriptors, semaphores or whatever) at the time
3359 @cindex duplicating file descriptors
3362 You can @dfn{duplicate} a file descriptor, or allocate another file
3363 descriptor that refers to the same open file as the original. Duplicate
3364 descriptors share one file position and one set of file status flags
3365 (@pxref{File Status Flags}), but each has its own set of file descriptor
3368 The major use of duplicating a file descriptor is to implement
3370 file or pipe that a particular file descriptor corresponds to.
3378 The @code{fcntl} function and flags are declared in @file{fcntl.h},
3379 while prototypes for @code{dup} and @code{dup2} are in the header file
3380 @file{unistd.h}.
3417 copy the file descriptor given as the first argument.
3426 the file descriptor returned should be the next available one greater
3430 of the new file descriptor. A return value of @math{-1} indicates an
3442 There are no more file descriptors available---your program is already
3449 @code{dup2} does not create a new opening of a file; duplicate
3461 corresponding file descriptors, before its @code{main} function is
3464 So, to redirect standard input to a file, the shell could do something
3473 int file;
3475 file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
3476 dup2 (file, STDIN_FILENO);
3477 TEMP_FAILURE_RETRY (close (file));
3488 @cindex file descriptor flags
3490 @dfn{File descriptor flags} are miscellaneous attributes of a file
3491 descriptor. These flags are associated with particular file
3492 descriptors, so that if you have created duplicate file descriptors
3493 from a single opening of a file, each descriptor has its own set of flags.
3495 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
3499 The symbols in this section are defined in the header file
3500 @file{fcntl.h}.
3506 specify that it should return the file descriptor flags associated
3526 specify that it should set the file descriptor flags associated with the
3540 The following macro is defined for use as a file descriptor flag with
3546 @cindex close-on-exec (file descriptor flag)
3547 This flag specifies that the file descriptor should be closed when
3549 a file descriptor is allocated (as with @code{open} or @code{dup}),
3550 this bit is initially cleared on the new file descriptor, meaning that
3554 If you want to modify the file descriptor flags, you should get the
3585 @cindex file status flags
3588 file. Unlike the file descriptor flags discussed in @ref{Descriptor
3589 Flags}, the file status flags are shared by duplicated file descriptors
3590 resulting from a single opening of the file. The file status flags are
3600 file: reading, writing, or both. They are set by @code{open} and are
3613 The symbols in this section are defined in the header file
3614 @file{fcntl.h}.
3627 The file access mode allows a file descriptor to be used for reading,
3628 writing, both, or neither. The access mode is determined when the file
3633 Open the file for read access.
3638 Open the file for write access.
3643 Open the file for both reading and writing.
3648 Obtain a file descriptor for the file, but do not open the file for
3649 reading or writing. Permission checks for the file itself are skipped
3650 when the file is opened (but permission to access the directory that
3662 The portable file access modes @code{O_RDONLY}, @code{O_WRONLY}, and
3664 file access mode with @code{fcntl}, you must extract the access mode
3665 bits from the retrieved file status flags, using the @code{O_ACCMODE}
3671 This macro is a mask that can be bitwise-ANDed with the file status flag
3672 value to recover the file access mode, assuming that a standard file
3676 If a non-standard file access mode is used (such as @code{O_PATH} or
3685 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}. A file access
3687 output to the file, but does allow other operations such as
3689 is a misnomer, @file{fcntl.h} defines additional names for the file
3694 Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU/Hurd.
3699 Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU/Hurd.
3704 Open the file for executing. Only defined on GNU/Hurd.
3711 These options are not preserved once the file is open. The exception to
3721 file name to locate the file, and whether the file can be created.
3722 @cindex file name translation flags
3723 @cindex flags, file name translation
3727 perform on the file once it is open.
3732 Here are the file name translation flags.
3736 If set, the file will be created if it doesn't already exist.
3738 @cindex create on open (file status flag)
3744 if the specified file already exists. This is guaranteed to never
3745 clobber an existing file.
3760 If set, the open operation fails if the final component of the file name
3768 unnamed temporary file. In this case, the pathname argument to the
3770 interpreted as the directory in which the temporary file is created
3771 (thus determining the file system which provides the storage for the
3772 file). The @code{O_TMPFILE} flag must be combined with @code{O_WRONLY}
3775 The temporary file can later be given a name using @code{linkat},
3776 turning it into a regular file. This allows the atomic creation of a
3777 file with the specific file attributes (mode and extended attributes)
3778 and file contents. If, for security reasons, it is not desirable that a
3779 name can be given to the file, the @code{O_EXCL} flag can be specified
3783 attempt to create an unnamed temporary file fails with an error of
3784 @code{EINVAL}. If the underlying file system does not support the
3794 file. This is only meaningful for some kinds of files, usually devices
3801 mode and a file name translation flag. This means that specifying
3803 @pxref{Operating Modes}. To open the file without blocking but do normal
3810 If the named file is a terminal device, don't make it the controlling
3814 On @gnuhurdsystems{} and 4.4 BSD, opening a file never makes it the
3817 controlling terminal when you open a file that is a terminal device; so
3822 The following three file name translation flags exist only on
3827 Do not recognize the named file as the controlling terminal, even if it
3829 on the new file descriptor will never induce job control signals.
3835 If the named file is a symbolic link, open the link itself instead of
3836 the file it refers to. (@code{fstat} on the new file descriptor will
3843 If the named file is specially translated, do not invoke the translator.
3844 Open the bare file the translator itself sees.
3849 which are not really related to opening the file. The reason to do them
3855 Truncate the file to zero length. This option is only useful for
3857 requires that you open the file for writing to use @code{O_TRUNC}. In
3858 BSD and GNU you must have permission to write the file to truncate it,
3873 Acquire a shared lock on the file, as with @code{flock}.
3877 creating the file. You are guaranteed that no other process will get
3878 the lock on the new file first.
3883 Acquire an exclusive lock on the file, as with @code{flock}.
3890 The operating modes affect how input and output operations using a file
3896 The bit that enables append mode for the file. If set, then all
3897 @code{write} operations write the data at the end of the file, extending
3898 it, regardless of the current file position. This is the only reliable
3899 way to append to a file. In append mode, you are guaranteed that the
3900 data you write will always go to the current end of the file, regardless
3901 of other processes writing to the file. Conversely, if you simply set
3902 the file position to the end of file and write, then another process can
3903 extend the file after you set the file position but before you write,
3904 resulting in your data appearing someplace before the real end of file.
3909 The bit that enables nonblocking mode for the file. If this bit is set,
3910 @code{read} requests on the file can return immediately with a failure
3916 operating mode and a file name translation flag; @pxref{Open-time Flags}.
3938 The bit that enables synchronous writing for the file. If set, each
3953 file. @xref{File Times}. This is used by programs that do backups, so
3954 that backing a file up does not count as reading it.
3955 Only the owner of the file or the superuser may use this bit.
3963 The @code{fcntl} function can fetch or change file status flags.
3968 read the file status flags for the open file with descriptor
3973 individual flags. Since the file access modes are not single-bit values,
3989 the file status flags for the open file corresponding to the
3997 You can't change the access mode for the file in this way; that is,
3998 whether the file descriptor was opened for reading or writing.
4005 If you want to modify the file status flags, you should get the current
4039 @cindex file locks
4043 open file description instead of the process. @xref{Open File Description Locks}.
4047 other from simultaneously accessing parts of a file in error-prone
4053 for writing to the specified part of the file. While a write lock is in
4054 place, no other process can lock that part of the file.
4059 requesting a write lock on the specified part of the file. However,
4064 locking protocol for a file shared by multiple processes, your application
4069 of lock set for each byte of a given file. When any file descriptor for
4070 that file is closed by the process, all of the locks that process holds
4071 on that file are released, even if the locks were made using other
4078 @code{fcntl} function are declared in the header file @file{fcntl.h}.
4083 This structure is used with the @code{fcntl} function to describe a file
4104 the file.
4110 conflicting lock is an open file description lock
4155 or the file associated with @var{filedes} doesn't support locks.
4186 file. Some systems use @code{EAGAIN} in this case, and other systems
4197 or the file associated with @var{filedes} doesn't support locks.
4200 The system has run out of file lock resources; there are already too
4201 many file locks in place.
4203 Well-designed file systems never report this error, because they have no
4206 to a file system on another machine.
4256 As an example of a situation where file locking is useful, consider a
4258 logs status information to a common file. One example of such a program
4259 might be a game that uses a file to keep track of high scores. Another
4264 file could cause the contents of the file to become mixed up. But
4266 file before actually writing to the file.
4268 If the program also needs to read the file and wants to make sure that
4269 the contents of the file are in a consistent state, then it can also use
4271 that part of the file for writing.
4275 Remember that file locks are only an @emph{advisory} protocol for
4276 controlling access to a file. There is still potential for access to
4277 the file by programs that don't use the lock protocol.
4283 open file description record locks are associated with an open file
4286 Using @code{fcntl} to apply an open file description lock on a region that
4287 already has an existing open file description lock that was created via the
4288 same file descriptor will never cause a lock conflict.
4290 Open file description locks are also inherited by child processes across
4292 (@pxref{Creating a Process}), along with the file descriptor.
4294 It is important to distinguish between the open file @emph{description} (an
4295 instance of an open file, usually created by a call to @code{open}) and
4296 an open file @emph{descriptor}, which is a numeric value that refers to the
4297 open file description. The locks described here are associated with the
4298 open file @emph{description} and not the open file @emph{descriptor}.
4300 Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file
4301 descriptor does not give you a new open file description, but rather copies a
4302 reference to an existing open file description and assigns it to a new
4303 file descriptor. Thus, open file description locks set on a file
4304 descriptor cloned by @code{dup} will never conflict with open file
4306 same open file description. Depending on the range and type of lock
4310 Open file description locks always conflict with process-associated locks,
4311 even if acquired by the same process or on the same open file
4314 Open file description locks use the same @code{struct flock} as
4316 macros for the @code{command} values are also declared in the header file
4317 @file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be
4318 defined prior to including any header file.
4321 an argument to open file description lock commands must have the @code{l_pid}
4323 open file description lock in a @code{F_GETLK} or @code{F_OFD_GETLK} request,
4373 the operating system kernel doesn't support open file description locks, or the file
4389 If the open file already has a lock on any part of the
4403 file.
4412 the operating system kernel doesn't support open file description locks, or the
4413 file associated with @var{filedes} doesn't support locks.
4416 The system has run out of file lock resources; there are already too
4417 many file locks in place.
4419 Well-designed file systems never report this error, because they have no
4422 to a file system on another machine.
4448 Open file description locks are useful in the same sorts of situations as
4449 process-associated locks. They can also be used to synchronize file
4451 its own @code{open} of the file, to obtain its own open file description.
4453 Because open file description locks are automatically freed only upon
4454 closing the last file descriptor that refers to the open file
4457 a file without the application being aware.
4459 As with process-associated locks, open file description locks are advisory.
4464 Here is an example of using open file description locks in a threaded
4478 appending to the file. Access to the file is serialized via open file
4493 If you set the @code{O_ASYNC} status flag on a file descriptor
4495 input or output becomes possible on that file descriptor. The process
4497 @code{F_SETOWN} command to the @code{fcntl} function. If the file
4504 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
4509 The symbols in this section are defined in the header file
4510 @file{fcntl.h}.
4567 devices and objects in terms of a few file primitives - @code{read},