Lines Matching refs:code

24 with a descriptor.  (You can use @code{fileno} to get the 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
86 The @code{open} function creates and returns a new file descriptor for
97 The normal return value from @code{open} is a non-negative integer file
100 Name Errors}), the following @code{errno} error conditions are defined
103 @table @code
110 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
114 The @code{open} operation was interrupted by a signal.
123 @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
131 The named file does not exist, and @code{O_CREAT} is not specified.
138 @code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
143 The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
144 @code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
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
159 descriptors, semaphores or whatever) at the time @code{open} is
161 until the program ends.  To avoid this calls to @code{open} should be
165 The @code{open} function is the underlying primitive for the @code{fopen}
166 and @code{freopen} functions, that create streams.
172 This function is similar to @code{open}.  It returns a file descriptor
177 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
178 function is actually available under the name @code{open}.  I.e., the
200 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
210 This function is similar to @code{creat}.  It returns a file descriptor
216 instead the counterparts named @code{*64}, e.g., @code{read64}.
218 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
219 function is actually available under the name @code{open}.  I.e., the
227 The function @code{close} closes the file descriptor @var{filedes}.
244 descriptors, semaphores or whatever) at the time @code{close} is
246 until the program ends.  To avoid this, calls to @code{close} should be
250 The normal return value from @code{close} is @math{0}; a value of @math{-1}
251 is returned in case of failure.  The following @code{errno} error
254 @table @code
259 The @code{close} call was interrupted by a signal.
261 Here is an example of how to handle @code{EINTR} properly:
270 When the file is accessed by NFS, these errors from @code{write} can sometimes
271 not be detected until @code{close}.  @xref{I/O Primitives}, for details
275 Please note that there is @emph{no} separate @code{close64} function.
277 on the mode of the file.  The kernel which performs the @code{close}
282 To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
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}
294 to @var{maxfd} (inclusive).  This function is similar to call @code{close} in
299 @code{ENOSYS}).
304 @vtable @code
309 Set the @code{FD_CLOEXEC} bit instead of closing the file descriptor.
312 The normal return value from @code{close_range} is @math{0}; a value
313 of @math{-1} is returned in case of failure.  The following @code{errno} error
316 @table @code
323 out of address space.  It can only happnes when @code{CLOSE_RANGE_UNSHARED}
328 @code{CLOSE_RANGE_UNSHARED} flag is used.
330 @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
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}.
352 output operations on file descriptors: @code{read}, @code{write}, and
353 @code{lseek}.  These functions are declared in the header file
360 read or written in a single operation.  It is similar to @code{size_t},
368 The @code{read} function reads up to @var{size} bytes from the file
382 If you keep calling @code{read} while at end-of-file, it will keep
385 If @code{read} returns at least one character, there is no way you can
389 In case of an error, @code{read} returns @math{-1}.  The following
390 @code{errno} error conditions are defined for this function:
392 @table @code
394 Normally, when no input is immediately available, @code{read} waits for
395 some input.  But if the @code{O_NONBLOCK} flag is set for the file
396 (@pxref{File Status Flags}), @code{read} returns immediately without
400 error code for this: @code{EWOULDBLOCK}.  In @theglibc{},
401 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
405 file can also fail with @code{EAGAIN} if the kernel cannot find enough
412 Any condition that could result in @code{EAGAIN} can instead result in a
413 successful @code{read} which returns fewer bytes than requested.
414 Calling @code{read} again immediately would result in @code{EAGAIN}.
421 @code{read} was interrupted by a signal while it was waiting for input.
423 @code{read} to return @code{EINTR}; it may instead result in a
424 successful @code{read} which returns fewer bytes than requested.
427 For many devices, and for disk files, this error code indicates
430 @code{EIO} also occurs when a background process tries to read from the
432 sending it a @code{SIGTTIN} signal isn't working.  This might happen if
443 Please note that there is no function named @code{read64}.  This is not
446 internally, the @code{read} function can be used for all cases.
450 descriptors, semaphores or whatever) at the time @code{read} is
452 until the program ends.  To avoid this, calls to @code{read} should be
456 The @code{read} function is the underlying primitive for all of the
457 functions that read from streams, such as @code{fgetc}.
466 The @code{pread} function is similar to the @code{read} function.  The
472 @code{filedes}.  Instead the data is read from the file starting at
476 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
477 @code{pread} function is in fact @code{pread64} and the type
478 @code{off_t} has 64 bits, which makes it possible to handle files up to
481 The return value of @code{pread} describes the number of bytes read.
482 In the error case it returns @math{-1} like @code{read} does and the
485 @table @code
504 This function is similar to the @code{pread} function.  The difference
505 is that the @var{offset} parameter is of type @code{off64_t} instead of
506 @code{off_t} which makes it possible on 32 bit machines to address
508 file descriptor @code{filedes} must be opened using @code{open64} since
509 otherwise the large offsets possible with @code{off64_t} will lead to
512 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
514 @code{pread} and so transparently replaces the 32 bit interface.
551 The @code{write} function writes up to @var{size} bytes from
558 @code{write} in a loop, iterating until all the data is written.
560 Once @code{write} returns, the data is enqueued to be written and can be
562 storage immediately.  You can use @code{fsync} when you need to be sure
567 @code{fdatasync} which guarantees integrity only for the file data and
570 You can use the @code{O_FSYNC} open mode to make @code{write} always
573 In the case of an error, @code{write} returns @math{-1}.  The following
574 @code{errno} error conditions are defined for this function:
576 @table @code
578 Normally, @code{write} blocks until the write operation is complete.
579 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
587 error code for this: @code{EWOULDBLOCK}.  In @theglibc{},
588 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
592 file can also fail with @code{EAGAIN} if the kernel cannot find enough
607 The @code{write} operation was interrupted by a signal while it was
609 @code{write} to return @code{EINTR}; it may instead result in a
610 successful @code{write} which writes fewer bytes than requested.
614 For many devices, and for disk files, this error code indicates
622 isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
631 Unless you have arranged to prevent @code{EINTR} failures, you should
632 check @code{errno} after each failing call to @code{write}, and if the
633 error was @code{EINTR}, you should simply repeat the call.
635 macro @code{TEMP_FAILURE_RETRY}, as follows:
641 Please note that there is no function named @code{write64}.  This is not
644 internally the @code{write} function can be used for all cases.
648 descriptors, semaphores or whatever) at the time @code{write} is
650 until the program ends.  To avoid this, calls to @code{write} should be
654 The @code{write} function is the underlying primitive for all of the
655 functions that write to streams, such as @code{fputc}.
664 The @code{pwrite} function is similar to the @code{write} function.  The
670 @code{filedes}.  Instead the data is written to the file starting at
674 However, on Linux, if a file is opened with @code{O_APPEND},  @code{pwrite}
676 @code{offset}.
678 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
679 @code{pwrite} function is in fact @code{pwrite64} and the type
680 @code{off_t} has 64 bits, which makes it possible to handle files up to
683 The return value of @code{pwrite} describes the number of written bytes.
684 In the error case it returns @math{-1} like @code{write} does and the
687 @table @code
706 This function is similar to the @code{pwrite} function.  The difference
707 is that the @var{offset} parameter is of type @code{off64_t} instead of
708 @code{off_t} which makes it possible on 32 bit machines to address
710 file descriptor @code{filedes} must be opened using @code{open64} since
711 otherwise the large offsets possible with @code{off64_t} will lead to
714 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
716 @code{pwrite} and so transparently replaces the 32 bit interface.
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
725 @code{write} operation.  @xref{File Positioning}, for more information
729 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
737 The @code{lseek} function is used to change the file position of the
741 interpreted, in the same way as for the @code{fseek} function, and it must
742 be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
743 @code{SEEK_END}.
745 @vtable @code
763 The return value from @code{lseek} is normally the resulting file
765 You can use this feature together with @code{SEEK_CUR} to read the
769 current end of file with @code{SEEK_END} is not sufficient.  Another
772 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
775 does not by itself make the file longer; @code{lseek} never changes the
786 invalid, @code{lseek} returns a value of @math{-1}.  The following
787 @code{errno} error conditions are defined for this function:
789 @table @code
801 @code{ESPIPE} if the object is not seekable.)
804 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
805 @code{lseek} function is in fact @code{lseek64} and the type
806 @code{off_t} has 64 bits which makes it possible to handle files up to
811 descriptors, semaphores or whatever) at the time @code{lseek} is
813 until the program ends.  To avoid this calls to @code{lseek} should be
817 The @code{lseek} function is the underlying primitive for the
818 @code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
819 @code{rewind} functions, which operate on streams instead of file
826 This function is similar to the @code{lseek} function.  The difference
827 is that the @var{offset} parameter is of type @code{off64_t} instead of
828 @code{off_t} which makes it possible on 32 bit machines to address
830 file descriptor @code{filedes} must be opened using @code{open64} since
831 otherwise the large offsets possible with @code{off64_t} will lead to
834 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
836 @code{lseek} and so transparently replaces the 32 bit interface.
840 more than once, or if you duplicate a descriptor with @code{dup}.
841 Descriptors that come from separate calls to @code{open} have independent
842 file positions; using @code{lseek} on one descriptor has no effect on the
860 error-checking code necessary for a real program has been omitted here
889 @theglibc{}, this type is no narrower than @code{int}.
891 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
892 is transparently replaced by @code{off64_t}.
897 This type is used similar to @code{off_t}.  The difference is that even
898 on 32 bit machines, where the @code{off_t} type would have 32 bits,
899 @code{off64_t} has 64 bits and so is able to address files up to
902 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
903 available under the name @code{off_t}.
910 @vtable @code
912 An alias for @code{SEEK_SET}.
915 An alias for @code{SEEK_CUR}.
918 An alias for @code{SEEK_END}.
928 @code{fdopen} function.  You can get the underlying file descriptor for
929 an existing stream with the @code{fileno} function.  These functions are
936 The @code{fdopen} function returns a new stream for the file descriptor
940 @code{fopen} function (@pxref{Opening Streams}), except that
942 distinction between text and binary files.  Also, @code{"w"} and
943 @code{"w+"} do not cause truncation of the file; these have an effect only
953 In some other systems, @code{fdopen} may fail to detect that the modes
955 @code{opentype}.  @Theglibc{} always checks for this.
958 For an example showing the use of the @code{fdopen} function,
967 @code{fileno} returns @math{-1}.
973 The @code{fileno_unlocked} function is equivalent to the @code{fileno}
975 is @code{FSETLOCKING_INTERNAL}.
983 file descriptors belonging to the standard streams @code{stdin},
984 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
987 @vtable @code
990 This macro has value @code{0}, which is the file descriptor for
996 This macro has value @code{1}, which is the file descriptor for
1002 This macro has value @code{2}, which is the file descriptor for
1025 stream from the descriptor with @code{fdopen} and then do all I/O with
1041 make a stream from a descriptor using @code{fdopen}, when you get a
1042 descriptor from a stream with @code{fileno}, when you copy a descriptor
1043 with @code{dup} or @code{dup2}, and when descriptors are inherited
1044 during @code{fork}.  For files that don't support random access, such as
1105 You can use @code{fflush} to clean a stream in most
1108 You can skip the @code{fflush} if you know the stream
1120 @code{fflush} does clean the stream, but leaves the file pointer at an
1124 Closing an output-only stream also does @code{fflush}, so this is a
1144 with multiple calls to @code{read} and @code{write}, it is inefficient
1151 @code{sys/uio.h}.
1153 These functions are controlled with arrays of @code{iovec} structures,
1159 The @code{iovec} structure describes a buffer.  It contains two fields:
1161 @table @code
1180 The @code{readv} function reads data from @var{filedes} and scatters it
1185 Note that @code{readv} is not guaranteed to fill all the buffers.
1186 It may stop at any point, for the same reasons @code{read} would.
1190 errors are the same as in @code{read}.
1202 The @code{writev} function gathers data from the buffers described in
1204 them to @code{filedes}.  As each buffer is written, it moves on to the
1207 Like @code{readv}, @code{writev} may stop midstream under the same
1208 conditions @code{write} would.
1211 error.  The possible errors are the same as in @code{write}.
1223 This function is similar to the @code{readv} function, with the difference
1224 it adds an extra @var{offset} parameter of type @code{off_t} similar to
1225 @code{pread}.  The data is read from the file starting at position
1229 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1230 @code{preadv} function is in fact @code{preadv64} and the type
1231 @code{off_t} has 64 bits, which makes it possible to handle files up to
1236 errors are the same as in @code{readv} and @code{pread}.
1247 This function is similar to the @code{preadv} function with the difference
1248 is that the @var{offset} parameter is of type @code{off64_t} instead of
1249 @code{off_t}.  It makes it possible on 32 bit machines to address
1251 file descriptor @code{filedes} must be opened using @code{open64} since
1252 otherwise the large offsets possible with @code{off64_t} will lead to
1255 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1257 @code{preadv} and so transparently replaces the 32 bit interface.
1268 This function is similar to the @code{writev} function, with the difference
1269 it adds an extra @var{offset} parameter of type @code{off_t} similar to
1270 @code{pwrite}.  The data is written to the file starting at position
1274 However, on Linux, if a file is opened with @code{O_APPEND},  @code{pwrite}
1276 @code{offset}.
1278 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1279 @code{pwritev} function is in fact @code{pwritev64} and the type
1280 @code{off_t} has 64 bits, which makes it possible to handle files up to
1285 errors are the same as in @code{writev} and @code{pwrite}.
1296 This function is similar to the @code{pwritev} function with the difference
1297 is that the @var{offset} parameter is of type @code{off64_t} instead of
1298 @code{off_t}.  It makes it possible on 32 bit machines to address
1300 file descriptor @code{filedes} must be opened using @code{open64} since
1301 otherwise the large offsets possible with @code{off64_t} will lead to
1304 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1306 @code{pwritev} and so transparently replaces the 32 bit interface.
1315 This function is similar to the @code{preadv} function, with the
1316 difference it adds an extra @var{flags} parameter of type @code{int}.
1318 is used and updated (like the @code{readv} function).
1323 @vtable @code
1328 @var{fd} must be opened using @code{O_DIRECT}.
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.
1337 Use nonblocking mode for this operation; that is, this call to @code{preadv2}
1338 will fail and set @code{errno} to @code{EAGAIN} if the operation would block.
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
1345 @code{preadv2} function is in fact @code{preadv64v2} and the type
1346 @code{off_t} has 64 bits, which makes it possible to handle files up to
1351 errors are the same as in @code{preadv} with the addition of:
1353 @table @code
1357 @c The default sysdeps/posix code will return it for any flags value
1371 This function is similar to the @code{preadv2} function with the difference
1372 is that the @var{offset} parameter is of type @code{off64_t} instead of
1373 @code{off_t}.  It makes it possible on 32 bit machines to address
1375 file descriptor @code{filedes} must be opened using @code{open64} since
1376 otherwise the large offsets possible with @code{off64_t} will lead to
1379 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1381 @code{preadv2} and so transparently replaces the 32 bit interface.
1391 This function is similar to the @code{pwritev} function, with the
1392 difference it adds an extra @var{flags} parameter of type @code{int}.
1394 should is used and updated (like the @code{writev} function).
1397 Linux, the supported flags are the same as those for @code{preadv2}.
1399 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1400 @code{pwritev2} function is in fact @code{pwritev64v2} and the type
1401 @code{off_t} has 64 bits, which makes it possible to handle files up to
1406 errors are the same as in @code{preadv2}.
1415 This function is similar to the @code{pwritev2} function with the difference
1416 is that the @var{offset} parameter is of type @code{off64_t} instead of
1417 @code{off_t}.  It makes it possible on 32 bit machines to address
1419 file descriptor @code{filedes} must be opened using @code{open64} since
1420 otherwise the large offsets possible with @code{off64_t} will lead to
1423 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1425 @code{pwritev2} and so transparently replaces the 32 bit interface.
1449 @code{read} and @code{write}) and an explicit offset (like @code{pread}
1450 and @code{pwrite}).  If the @var{inputpos} pointer is null, the file
1453 @var{inputpos} is not null, then @code{*@var{inputpos}} is used as the
1454 starting point of the copy operation, and @code{*@var{inputpos}} is
1461 The @code{copy_file_range} function returns the number of bytes copied.
1467 If no bytes can be copied, to report an error, @code{copy_file_range}
1468 returns the value @math{-1} and sets @code{errno}.  The table below
1471 @table @code
1496 @code{off_t} could represent.
1503 writing, or @var{outputfd} has been opened with @code{O_APPEND}.
1506 In addition, @code{copy_file_range} can fail with the error codes
1507 which are used by @code{read}, @code{pread}, @code{write}, and
1508 @code{pwrite}.
1510 The @code{copy_file_range} function is a cancellation point.  In case of
1512 @code{*@var{inputpos}}) is indeterminate.
1522 This is more efficient than @code{read} or @code{write}, as only the regions
1548 anonymous mappings as well (see the @code{MAP_HUGETLB} flag below).
1556 The @code{mmap} function creates a new mapping, connected to bytes
1562 @code{NULL} expresses no preference.  Any previous mapping at that
1564 changed, unless you use the @code{MAP_FIXED} flag.
1567 permitted.  They include @code{PROT_READ}, @code{PROT_WRITE}, and
1568 @code{PROT_EXEC}.  The special flag @code{PROT_NONE} reserves a region
1569 of address space for future use.  The @code{mprotect} function can be
1573 One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified.
1577 @vtable @code
1586 the entire mmapped region if you use this mode with @code{PROT_WRITE}.
1594 @code{msync}, described below, if it is important that other processes
1614 @code{malloc} for large blocks.  This is not an issue with @theglibc{},
1615 as the included @code{malloc} automatically uses @code{mmap} where appropriate.
1629 @code{MAP_HUGETLB} mappings are affected by memory fragmentation, and
1635 The @code{MAP_HUGETLB} flag is specific to Linux.
1647 @code{mmap} returns the address of the new mapping, or
1648 @code{MAP_FAILED} for an error.
1652 @table @code
1659 If @code{MAP_HUGETLB} was specified, the file or system does not support
1694 The @code{mmap64} function is equivalent to the @code{mmap} function but
1695 the @var{offset} parameter is of type @code{off64_t}.  On 32-bit systems
1698 call to @code{open64} or @code{fopen64} and @code{freopen64} where the
1699 descriptor is retrieved with @code{fileno}.
1701 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
1702 function is actually available under the name @code{mmap}.  I.e., the
1711 @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
1723 @table @code
1748 @vtable @code
1753 Normally @code{msync} only makes sure that accesses to a file with
1758 This tells @code{msync} to begin the synchronization, but not to wait for
1765 @code{msync} returns @math{0} for success and @math{-1} for
1768 @table @code
1786 in the same @code{mmap} statement.  A new mapping with the same
1789 One option is possible, @code{MREMAP_MAYMOVE}.  If it is given in
1796 @table @code
1812 @code{MREMAP_MAYMOVE} is not given and the extension would collide with
1824 not support mapping at all.  Thus, programs using @code{mmap} should
1838 @vtable @code
1873 Undo the effect of a previous @code{MADV_HUGEPAGE} advice.  This flag
1880 @vtable @code
1883 This corresponds with BSD's @code{MADV_NORMAL}.
1886 This corresponds with BSD's @code{MADV_RANDOM}.
1889 This corresponds with BSD's @code{MADV_SEQUENTIAL}.
1892 This corresponds with BSD's @code{MADV_WILLNEED}.
1895 This corresponds with BSD's @code{MADV_DONTNEED}.
1899 @code{madvise} returns @math{0} for success and @math{-1} for
1901 @table @code
1938 In @theglibc{} it must be a string smaller than @code{NAME_MAX} bytes starting
1941 The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}.
1943 @code{shm_open} returns the file descriptor on success or @math{-1} on error.
1944 On failure @code{errno} is set.
1956 This function is the inverse of @code{shm_open} and removes the object with
1957 the given @var{name} previously created by @code{shm_open}.
1959 @code{shm_unlink} returns @math{0} on success or @math{-1} on error.
1960 On failure @code{errno} is set.
1966 The @code{memfd_create} function returns a file descriptor which can be
1967 used to create memory mappings using the @code{mmap} function.  It is
1968 similar to the @code{shm_open} function in the sense that these mappings
1970 @code{memfd_create} does not correspond to a named object; the
1972 appear in @file{/proc}), and separate invocations of @code{memfd_create}
1979 increased with the @code{ftruncate} function.  @xref{File Size}.
1983 @vtable @code
1986 The descriptor is created with the @code{O_CLOEXEC} flag.
1990 The descriptor supports the addition of seals using the @code{fcntl}
1996 use a larger page size.  See @code{MAP_HUGETLB} above for details.
1998 This flag is incompatible with @code{MFD_ALLOW_SEALING}.
2001 @code{memfd_create} returns a file descriptor on success, and @math{-1}
2004 The following @code{errno} error conditions are defined for this
2007 @table @code
2040 You cannot normally use @code{read} for this purpose, because this
2046 A better solution is to use the @code{select} function.  This blocks the
2054 accepted (@pxref{Accepting Connections}).  @code{accept} for server
2055 sockets blocks and interacts with @code{select} just as @code{read} does
2058 @cindex file descriptor sets, for @code{select}
2059 The file descriptor sets for the @code{select} function are specified
2060 as @code{fd_set} objects.  Here is the description of the data type
2065 The @code{fd_set} data type represents file descriptor sets for the
2066 @code{select} function.  It is actually a bit array.
2072 @code{fd_set} object can hold information about.  On systems with a
2073 fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
2076 controls the number of bits in an @code{fd_set}; if you get a file
2077 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
2078 that descriptor into an @code{fd_set}.
2120 Next, here is the description of the @code{select} function itself.
2128 The @code{select} function blocks the calling process until there is
2139 A file descriptor is considered ready for reading if a @code{read}
2143 can be accepted with @code{accept}; @pxref{Accepting Connections}.  A
2153 The @code{select} function checks only the first @var{nfds} file
2154 descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
2160 the time in @code{struct timeval} format; see @ref{Time Types}.
2161 Specify zero as the time (a @code{struct timeval} containing all
2165 The normal return value from @code{select} is the total number of ready file
2169 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
2171 If @code{select} returns because the timeout period expires, it returns
2174 Any signal will cause @code{select} to return immediately.  So if your
2175 program uses signals, you can't rely on @code{select} to keep waiting
2177 particular amount of time, you must check for @code{EINTR} and repeat
2178 the @code{select} with a newly calculated timeout based on the current
2181 If an error occurs, @code{select} returns @code{-1} and does not modify
2182 the argument file descriptor sets.  The following @code{errno} error
2185 @table @code
2198 @strong{Portability Note:}  The @code{select} function is a BSD Unix
2201 Here is an example showing how you can use @code{select} to establish a
2202 timeout period for reading from a file descriptor.  The @code{input_timeout}
2210 There is another example showing the use of @code{select} to multiplex
2219 executed synchronously.  I.e., even if a @code{write} system call
2235 A prototype for @code{sync} can be found in @file{unistd.h}.
2239 committed, rather than all data in the system.  For this, @code{sync} is overkill.
2245 The @code{fsync} function can be used to make sure all data associated with
2250 A prototype for @code{fsync} can be found in @file{unistd.h}.
2254 descriptors, semaphores or whatever) at the time @code{fsync} is
2256 until the program ends.  To avoid this, calls to @code{fsync} should be
2261 it is @math{-1} and the global variable @code{errno} is set to the
2263 @table @code
2282 When a call to the @code{fdatasync} function returns, it is ensured
2286 Not all systems implement the @code{fdatasync} operation.  On systems
2287 missing this functionality @code{fdatasync} is emulated by a call to
2288 @code{fsync} since the performed actions are a superset of those
2289 required by @code{fdatasync}.
2291 The prototype for @code{fdatasync} is in @file{unistd.h}.
2294 it is @math{-1} and the global variable @code{errno} is set to the
2296 @table @code
2314 @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
2326 @code{struct aiocb} (@dfn{AIO control block}).  It is defined in
2331 The POSIX.1b standard mandates that the @code{struct aiocb} structure
2336 @table @code
2344 like terminals where an @code{lseek} call would lead to an error.
2358 This element specifies the length of the buffer pointed to by @code{aio_buf}.
2361 If the platform has defined @code{_POSIX_PRIORITIZED_IO} and
2362 @code{_POSIX_PRIORITY_SCHEDULING}, the AIO requests are
2364 @code{aio_reqprio} element can then be used to lower the priority of the
2369 operation terminates.  If the @code{sigev_notify} element is
2370 @code{SIGEV_NONE}, no notification is sent.  If it is @code{SIGEV_SIGNAL},
2371 the signal determined by @code{sigev_signo} is sent.  Otherwise,
2372 @code{sigev_notify} must be @code{SIGEV_THREAD}.  In this case, a thread
2374 @code{sigev_notify_function}.
2377 This element is only used by the @code{lio_listio} and
2378 @code{lio_listio64} functions.  Since these functions allow an
2383 @vtable @code
2386 @code{aio_offset} and store the next @code{aio_nbytes} bytes in the
2387 buffer pointed to by @code{aio_buf}.
2390 Start a write operation.  Write @code{aio_nbytes} bytes starting at
2391 @code{aio_buf} into the file starting at position @code{aio_offset}.
2395 an array of @code{struct aiocb} values contains holes, i.e., some of the
2397 @code{lio_listio} function.
2401 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
2402 32 bit machine, this type is in fact @code{struct aiocb64}, since the LFS
2403 interface transparently replaces the @code{struct aiocb} definition.
2408 types but otherwise is equivalent to @code{struct aiocb}.  Particularly,
2413 @table @code
2421 like terminals where an @code{lseek} call would lead to an error.
2435 This element specifies the length of the buffer pointed to by @code{aio_buf}.
2438 If for the platform @code{_POSIX_PRIORITIZED_IO} and
2439 @code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are
2441 @code{aio_reqprio} element can then be used to lower the priority of the
2446 operation terminates.  If the @code{sigev_notify} element is
2447 @code{SIGEV_NONE} no notification is sent.  If it is @code{SIGEV_SIGNAL},
2448 the signal determined by @code{sigev_signo} is sent.  Otherwise,
2449 @code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
2451 @code{sigev_notify_function}.
2454 This element is only used by the @code{lio_listio} and
2455 @code{lio_listio64} functions.  Since these functions allow an
2458 control block.  See the description of @code{struct aiocb} for a description
2462 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
2463 32 bit machine, this type is available under the name @code{struct
2636 The first @code{aiocbp->aio_nbytes} bytes of the file for which
2637 @code{aiocbp->aio_fildes} is a descriptor are written to the buffer
2638 starting at @code{aiocbp->aio_buf}.  Reading starts at the absolute
2639 position @code{aiocbp->aio_offset} in the file.
2642 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2646 request according to the @code{aiocbp->aio_sigevent} value.
2648 When @code{aio_read} returns, the return value is zero if no error
2651 @code{errno} to one of the following values:
2653 @table @code
2658 The @code{aio_read} function is not implemented.
2660 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
2664 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
2669 If @code{aio_read} returns zero, the current status of the request
2670 can be queried using @code{aio_error} and @code{aio_return} functions.
2671 As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
2672 the operation has not yet completed.  If @code{aio_error} returns zero,
2674 interpreted as an error code.  If the function terminated, the result of
2675 the operation can be obtained using a call to @code{aio_return}.  The
2676 returned value is the same as an equivalent call to @code{read} would
2677 have returned.  Possible error codes returned by @code{aio_error} are:
2679 @table @code
2681 The @code{aiocbp->aio_fildes} descriptor is not valid.
2686 The @code{aiocbp->aio_offset} value is invalid.
2689 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2690 function is in fact @code{aio_read64} since the LFS interface transparently
2697 This function is similar to the @code{aio_read} function.  The only
2699 be opened in the large file mode.  Internally, @code{aio_read64} uses
2700 functionality equivalent to @code{lseek64} (@pxref{File Position
2702 as opposed to the @code{lseek} functionality used in @code{aio_read}.
2704 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2705 function is available under the name @code{aio_read} and so transparently
2719 The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
2720 @code{aiocbp->aio_buf} are written to the file for which
2721 @code{aiocbp->aio_fildes} is a descriptor, starting at the absolute
2722 position @code{aiocbp->aio_offset} in the file.
2725 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2729 request according to the @code{aiocbp->aio_sigevent} value.
2731 When @code{aio_write} returns, the return value is zero if no error
2734 @code{errno} to one of the following values.
2736 @table @code
2741 The @code{aio_write} function is not implemented.
2743 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
2747 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqprio} value is
2752 In the case @code{aio_write} returns zero, the current status of the
2753 request can be queried using the @code{aio_error} and @code{aio_return}
2754 functions.  As long as the value returned by @code{aio_error} is
2755 @code{EINPROGRESS} the operation has not yet completed.  If
2756 @code{aio_error} returns zero, the operation successfully terminated,
2757 otherwise the value is to be interpreted as an error code.  If the
2759 to @code{aio_return}.  The returned value is the same as an equivalent
2760 call to @code{read} would have returned.  Possible error codes returned
2761 by @code{aio_error} are:
2763 @table @code
2765 The @code{aiocbp->aio_fildes} descriptor is not valid.
2770 The @code{aiocbp->aio_offset} value is invalid.
2773 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2774 function is in fact @code{aio_write64} since the LFS interface transparently
2781 This function is similar to the @code{aio_write} function.  The only
2783 be opened in the large file mode.  Internally @code{aio_write64} uses
2784 functionality equivalent to @code{lseek64} (@pxref{File Position
2786 as opposed to the @code{lseek} functionality used in @code{aio_write}.
2788 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2789 function is available under the name @code{aio_write} and so transparently
2796 operations.  It is therefore similar to a combination of @code{readv} and
2797 @code{writev}.
2807 The @code{lio_listio} function can be used to enqueue an arbitrary
2812 @code{lio_listio} gets the @var{nent} requests from the array pointed to
2814 @code{aio_lio_opcode} member in each element of @var{list}.  If this
2815 field is @code{LIO_READ} a read operation is enqueued, similar to a call
2816 of @code{aio_read} for this element of the array (except that the way
2818 the @code{aio_lio_opcode} member is @code{LIO_WRITE} a write operation
2819 is enqueued.  Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
2822 @code{struct aiocb} elements from which only a few need to be handled at
2823 a time.  Another situation is where the @code{lio_listio} call was
2828 @code{list} must have values suitable for the operation as described in
2829 the documentation for @code{aio_read} and @code{aio_write} above.
2831 The @var{mode} argument determines how @code{lio_listio} behaves after
2832 having enqueued all the requests.  If @var{mode} is @code{LIO_WAIT} it
2834 @code{LIO_NOWAIT} and in this case the function returns immediately after
2837 @var{sig} parameter.  If @var{sig} is @code{NULL} no notification is
2839 described in the description for @code{aio_read} or @code{aio_write}.
2841 If @var{mode} is @code{LIO_WAIT}, the return value of @code{lio_listio}
2843 function returns @math{-1} and @code{errno} is set accordingly.  To find
2844 out which request or requests failed one has to use the @code{aio_error}
2847 In case @var{mode} is @code{LIO_NOWAIT}, the function returns @math{0} if
2849 can be found using @code{aio_error} and @code{aio_return} as described
2850 above.  If @code{lio_listio} returns @math{-1} in this mode, the
2851 global variable @code{errno} is set accordingly.  If a request did not
2852 yet terminate, a call to @code{aio_error} returns @code{EINPROGRESS}.  If
2855 using @code{aio_return}.
2857 Possible values for @code{errno} are:
2859 @table @code
2870 @code{AIO_LISTIO_MAX}.
2875 The @code{lio_listio} function is not supported.
2878 If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
2880 @code{aio_error} is @code{ECANCELED}.
2882 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2883 function is in fact @code{lio_listio64} since the LFS interface
2890 This function is similar to the @code{lio_listio} function.  The only
2892 be opened in the large file mode.  Internally, @code{lio_listio64} uses
2893 functionality equivalent to @code{lseek64} (@pxref{File Position
2895 writing, as opposed to the @code{lseek} functionality used in
2896 @code{lio_listio}.
2898 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2899 function is available under the name @code{lio_listio} and so
2910 @code{aio_read} and @code{aio_write} and with @code{lio_listio} when the
2911 mode is @code{LIO_NOWAIT}), one sometimes needs to know whether a
2919 @code{struct aiocb} variable pointed to by @var{aiocbp}.  If the
2921 @code{EINPROGRESS}.  Once the request has terminated the value
2922 @code{aio_error} returns is either @math{0} if the request completed
2924 @code{errno} variable if the request would have been done using
2925 @code{read}, @code{write}, or @code{fsync}.
2927 The function can return @code{ENOSYS} if it is not implemented.  It
2928 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2931 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2932 function is in fact @code{aio_error64} since the LFS interface
2939 This function is similar to @code{aio_error} with the only difference
2940 that the argument is a reference to a variable of type @code{struct
2943 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2944 function is available under the name @code{aio_error} and so
2955 by @code{aio_error} is @code{EINPROGRESS} the return value of this function is
2961 returned by the @code{read}, @code{write}, or @code{fsync} call.
2963 The function can return @code{ENOSYS} if it is not implemented.  It
2964 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2967 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2968 function is in fact @code{aio_return64} since the LFS interface
2975 This function is similar to @code{aio_return} with the only difference
2976 that the argument is a reference to a variable of type @code{struct
2979 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2980 function is available under the name @code{aio_return} and so
2996 The @code{aio_fsync} and @code{aio_fsync64} functions are only available
2997 if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
3007 @code{aiocbp->aio_fildes} into the synchronized I/O completion state
3008 (@pxref{Synchronizing I/O}).  The @code{aio_fsync} function returns
3010 @code{aiocbp->aio_sigevent} will happen only after all requests for this
3015 If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
3016 to @code{fdatasync}.  Otherwise @var{op} should be @code{O_SYNC} and
3017 the synchronization happens as with @code{fsync}.
3020 @code{aio_error} with the reference to the object pointed to by
3021 @var{aiocbp} returns @code{EINPROGRESS}.  Once the synchronization is
3022 done @code{aio_error} return @math{0} if the synchronization was not
3024 @code{fsync} or @code{fdatasync} function would have set the
3025 @code{errno} variable.  In this case nothing can be assumed about the
3030 @code{errno} is set to one of the following values:
3032 @table @code
3036 The file descriptor @code{@var{aiocbp}->aio_fildes} is not valid.
3039 parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
3044 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
3045 function is in fact @code{aio_fsync64} since the LFS interface
3052 This function is similar to @code{aio_fsync} with the only difference
3053 that the argument is a reference to a variable of type @code{struct
3056 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
3057 function is available under the name @code{aio_fsync} and so
3063 specific set terminated.  This could be achieved by the @code{aio_*}
3068 be slow.  On the other hand letting the @code{aio_*} functions notify the
3073 @code{aio_suspend} should be used.
3083 completed at the time @code{aio_suspend} is called, the function returns
3085 comparing the error status of the request with @code{EINPROGRESS}.  If
3086 an element of @var{list} is @code{NULL}, the entry is simply ignored.
3089 @var{timeout} is @code{NULL}, the process is not woken until a request
3090 has finished.  If @var{timeout} is not @code{NULL}, the process remains
3092 @code{aio_suspend} returns with an error.
3096 @math{-1} and @code{errno} is set to one of the following values:
3098 @table @code
3103 A signal interrupted the @code{aio_suspend} function.  This signal might
3107 The @code{aio_suspend} function is not implemented.
3110 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
3111 function is in fact @code{aio_suspend64} since the LFS interface
3118 This function is similar to @code{aio_suspend} with the only difference
3119 that the argument is a reference to a variable of type @code{struct
3122 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
3123 function is available under the name @code{aio_suspend} and so
3154 The @code{aio_cancel} function can be used to cancel one or more
3155 outstanding requests.  If the @var{aiocbp} parameter is @code{NULL}, the
3157 the file descriptor @var{fildes} (i.e., whose @code{aio_fildes} member
3158 is @var{fildes}).  If @var{aiocbp} is not @code{NULL}, @code{aio_cancel}
3163 on the @code{struct sigevent} object which controls this, nothing
3167 After a request is successfully canceled, a call to @code{aio_error} with
3169 @code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
3171 still @code{EINPROGRESS}.
3173 The return value of the function is @code{AIO_CANCELED} if there were
3176 return value is @code{AIO_NOTCANCELED}.  In this case @code{aio_error}
3178 @var{aiocbp} is @code{NULL}) weren't successfully canceled.  If all
3179 requests already terminated at the time @code{aio_cancel} is called the
3180 return value is @code{AIO_ALLDONE}.
3182 If an error occurred during the execution of @code{aio_cancel} the
3183 function returns @math{-1} and sets @code{errno} to one of the following
3186 @table @code
3190 @code{aio_cancel} is not implemented.
3193 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
3194 function is in fact @code{aio_cancel64} since the LFS interface
3201 This function is similar to @code{aio_cancel} with the only difference
3202 that the argument is a reference to a variable of type @code{struct
3205 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
3206 function is available under the name @code{aio_cancel} and so
3229 this struct and pass it to the implementation using the @code{aio_init}
3232 @table @code
3260 Before calling @code{aio_init}, the members of a variable of
3261 type @code{struct aioinit} must be initialized.  Then a reference to
3262 this variable is passed as the parameter to @code{aio_init} which itself
3274 @cindex @code{fcntl} function
3278 like.  All of these operations are performed by the function @code{fcntl}.
3280 The second argument to the @code{fcntl} function is a command that
3283 @file{fcntl.h}.  Many of these flags are also used by the @code{open}
3290 The @code{fcntl} function performs the operation specified by
3298 @vtable @code
3322 Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
3333 Like @code{F_OFD_SETLK}, but block until lock is acquired.
3337 Get process or process group ID to receive @code{SIGIO} signals.
3341 Set process or process group ID to receive @code{SIGIO} signals.
3346 commands @code{F_SETLKW} (and the LFS analogous @code{F_SETLKW64}) and
3347 @code{F_OFD_SETLKW}.  This is a problem if the thread allocates some
3349 @code{fcntl} is called.  If the thread gets canceled these resources stay
3350 allocated until the program ends.  To avoid this calls to @code{fcntl} should
3372 You can perform this operation using the @code{fcntl} function with the
3373 @code{F_DUPFD} command, but there are also convenient functions
3374 @code{dup} and @code{dup2} for duplicating descriptors.
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
3387 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
3396 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
3402 valid descriptor number, then @code{dup2} is equivalent to:
3409 However, @code{dup2} does this atomically; there is no instant in the
3410 middle of calling @code{dup2} at which @var{new} is closed and not yet a
3416 This macro is used as the @var{command} argument to @code{fcntl}, to
3425 The @var{next-filedes} argument is of type @code{int} and specifies that
3429 The return value from @code{fcntl} with this command is normally the value
3431 error.  The following @code{errno} error conditions are defined for
3434 @table @code
3445 more information about the @code{RLIMIT_NOFILE} limit.
3448 @code{ENFILE} is not a possible error code for @code{dup2} because
3449 @code{dup2} does not create a new opening of a file; duplicate
3450 descriptors do not count toward the limit which @code{ENFILE}
3451 indicates.  @code{EMFILE} is possible because it refers to the limit on
3455 Here is an example showing how to use @code{dup2} to do redirection.
3456 Typically, redirection of the standard streams (like @code{stdin}) is
3458 @code{exec} functions (@pxref{Executing a File}) to execute a new
3461 corresponding file descriptors, before its @code{main} function is
3495 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
3497 @code{exec@dots{}} functions (@pxref{Executing a File}).
3505 This macro is used as the @var{command} argument to @code{fcntl}, to
3509 The normal return value from @code{fcntl} with this command is a
3513 In case of an error, @code{fcntl} returns @math{-1}.  The following
3514 @code{errno} error conditions are defined for this command:
3516 @table @code
3525 This macro is used as the @var{command} argument to @code{fcntl}, to
3527 @var{filedes} argument.  This requires a third @code{int} argument to
3534 The normal return value from @code{fcntl} with this command is an
3536 The flags and error conditions are the same as for the @code{F_GETFD}
3541 the @code{fcntl} function.  The value is an integer constant usable
3548 an @code{exec} function is invoked; see @ref{Executing a File}.  When
3549 a file descriptor is allocated (as with @code{open} or @code{dup}),
3551 descriptor will survive into the new program after @code{exec}.
3555 current flags with @code{F_GETFD} and modify the value.  Don't assume
3558 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
3562 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
3564    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
3591 specified with the @var{flags} argument to @code{open};
3600 file: reading, writing, or both.  They are set by @code{open} and are
3601 returned by @code{fcntl}, but cannot be changed.
3604 @ref{Open-time Flags}, control details of what @code{open} will do.
3605 These flags are not preserved after the @code{open} call.
3608 @ref{Operating Modes}, affect how operations such as @code{read} and
3609 @code{write} are done.  They are set by @code{open}, and can be fetched or
3610 changed with @code{fcntl}.
3619 * Open-time Flags::             Details of @code{open}.
3654 For example, such descriptors can be used with the @code{fexecve}
3658 possible to use @code{O_EXEC} explicitly, or specify no access modes
3662 The portable file access modes @code{O_RDONLY}, @code{O_WRONLY}, and
3663 @code{O_RDWR} may not correspond to individual bits.  To determine the
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}
3676 If a non-standard file access mode is used (such as @code{O_PATH} or
3677 @code{O_EXEC}), masking with @code{O_ACCMODE} may give incorrect
3680 @code{O_ACCMODE} first).
3682 On @gnuhurdsystems{} (but not on other systems), @code{O_RDONLY} and
3683 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
3685 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
3688 @code{fchmod}.  On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
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.
3710 The open-time flags specify options affecting how @code{open} will behave.
3712 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
3714 @code{open}.
3720 @dfn{File name translation flags} affect how @code{open} looks up the
3726 @dfn{Open-time action flags} specify extra operations that @code{open} will
3743 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
3747 The @code{O_EXCL} flag has a special meaning in combination with
3748 @code{O_TMPFILE}; see below.
3754 a directory.  The @code{errno} variable is set to @code{ENOTDIR} for
3761 refers to a symbolic link.  The @code{errno} variable is set to
3762 @code{ELOOP} for this error condition.
3767 If this flag is specified, functions in the @code{open} family create an
3769 @code{open} family of functions (@pxref{Opening and Closing Files}) is
3772 file).  The @code{O_TMPFILE} flag must be combined with @code{O_WRONLY}
3773 or @code{O_RDWR}, and the @var{mode} argument is required.
3775 The temporary file can later be given a name using @code{linkat},
3779 name can be given to the file, the @code{O_EXCL} flag can be specified
3780 along with @code{O_TMPFILE}.
3784 @code{EINVAL}.  If the underlying file system does not support the
3785 @code{O_TMPFILE} flag, an @code{EOPNOTSUPP} error is the result.
3787 The @code{O_TMPFILE} flag is a GNU extension.
3793 This prevents @code{open} from blocking for a ``long time'' to open the
3797 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
3800 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
3802 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
3804 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
3805 then call @code{fcntl} to turn the bit off.
3815 controlling terminal and @code{O_NOCTTY} is zero.  However, @gnulinuxsystems{}
3816 and some other systems use a nonzero value for @code{O_NOCTTY} and set the
3818 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
3836 the file it refers to.  (@code{fstat} on the new file descriptor will
3837 return the information returned by @code{lstat} on the link's name.)
3848 The open-time action flags tell @code{open} to do additional operations
3850 as part of @code{open} instead of in separate calls is that @code{open}
3857 requires that you open the file for writing to use @code{O_TRUNC}.  In
3862 no good reason for truncation to be done by @code{open}, instead of by
3863 calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
3864 Unix before @code{ftruncate} was invented, and is retained for backward
3873 Acquire a shared lock on the file, as with @code{flock}.
3876 If @code{O_CREAT} is specified, the locking is done atomically when
3883 Acquire an exclusive lock on the file, as with @code{flock}.
3884 @xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
3891 descriptor work.  These flags are set by @code{open} and can be fetched
3892 and changed with @code{fcntl}.
3897 @code{write} operations write the data at the end of the file, extending
3910 @code{read} requests on the file can return immediately with a failure
3912 Likewise, @code{write} requests can also return immediately with a
3915 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
3921 This is an obsolete name for @code{O_NONBLOCK}, provided for
3930 The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
3939 @code{write} call will make sure the data is reliably stored on disk before
3947 This is another name for @code{O_FSYNC}.  They have the same value.
3952 If this bit is set, @code{read} will not update the access time of the
3963 The @code{fcntl} function can fetch or change file status flags.
3967 This macro is used as the @var{command} argument to @code{fcntl}, to
3971 The normal return value from @code{fcntl} with this command is a
3974 you can mask off other bits in the returned flags with @code{O_ACCMODE}
3977 In case of an error, @code{fcntl} returns @math{-1}.  The following
3978 @code{errno} error conditions are defined for this command:
3980 @table @code
3988 This macro is used as the @var{command} argument to @code{fcntl}, to set
3990 @var{filedes} argument.  This command requires a third @code{int}
4000 The normal return value from @code{fcntl} with this command is an
4002 error conditions are the same as for the @code{F_GETFL} command.
4006 flags with @code{F_GETFL} and modify the value.  Don't assume that the
4009 here is a function to set or clear the flag @code{O_NONBLOCK} without
4014 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
4016    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
4045 The remaining @code{fcntl} commands are used to support @dfn{record
4062 The @code{read} and @code{write} functions do not actually check to see
4065 must do explicit @code{fcntl} calls to request and clear locks at the
4074 @code{fork} (@pxref{Creating a Process}).
4076 When making a lock, use a @code{struct flock} to specify what kind of
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
4086 @table @code
4088 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
4089 @code{F_UNLCK}.
4092 This corresponds to the @var{whence} argument to @code{fseek} or
4093 @code{lseek}, and specifies what the offset is relative to.  Its value
4094 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
4099 @code{l_whence} member.
4103 @code{0} is treated specially; it means the region extends to the end of
4108 process holding the lock.  It is filled in by calling @code{fcntl} with
4109 the @code{F_GETLK} command, but is ignored when making a lock.  If the
4118 This macro is used as the @var{command} argument to @code{fcntl}, to
4120 requires a third argument of type @w{@code{struct flock *}} to be passed
4121 to @code{fcntl}, so that the form of the call is:
4129 @code{*@var{lockp}}.  Existing locks are not reported if they are
4131 specify a lock type of @code{F_WRLCK} if you want to find out about both
4132 read and write locks, or @code{F_RDLCK} if you want to find out about
4136 @var{lockp} argument, but @code{fcntl} only returns information about
4137 one of them.  The @code{l_whence} member of the @var{lockp} structure is
4138 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
4142 update the @code{l_type} to a value of @code{F_UNLCK}.
4144 The normal return value from @code{fcntl} with this command is an
4146 error.  The following @code{errno} error conditions are defined for
4149 @table @code
4161 This macro is used as the @var{command} argument to @code{fcntl}, to
4163 third argument of type @w{@code{struct flock *}} to be passed to
4164 @code{fcntl}, so that the form of the call is:
4172 by specifying a lock type of @code{F_UNLCK}.
4174 If the lock cannot be set, @code{fcntl} returns immediately with a value
4176 to release locks.  If @code{fcntl} succeeds, it returns a value other
4179 The following @code{errno} error conditions are defined for this
4182 @table @code
4186 file.  Some systems use @code{EAGAIN} in this case, and other systems
4187 use @code{EACCES}; your program should treat them alike, after
4188 @code{F_SETLK}.  (@gnulinuxhurdsystems{} always use @code{EAGAIN}.)
4212 This macro is used as the @var{command} argument to @code{fcntl}, to
4214 @code{F_SETLK} command, but causes the process to block (or wait)
4217 This command requires a third argument of type @code{struct flock *}, as
4218 for the @code{F_SETLK} command.
4220 The @code{fcntl} return values and errors are the same as for the
4221 @code{F_SETLK} command, but these additional @code{errno} error conditions
4224 @table @code
4239 The following macros are defined for use as values for the @code{l_type}
4240 member of the @code{flock} structure.  The values are integer constants.
4242 @vtable @code
4286 Using @code{fcntl} to apply an open file description lock on a region that
4291 @code{fork}, or @code{clone} with @code{CLONE_FILES} set
4295 instance of an open file, usually created by a call to @code{open}) and
4300 Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file
4304 descriptor cloned by @code{dup} will never conflict with open file
4307 involved, the original lock may be modified by a @code{F_OFD_SETLK} or
4308 @code{F_OFD_SETLKW} command in this situation however.
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
4320 In contrast to process-associated locks, any @code{struct flock} used as
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,
4324 the @code{l_pid} field in @code{struct flock} will be set to @math{-1}
4327 When the same @code{struct flock} is reused as an argument to a
4328 @code{F_OFD_SETLK} or @code{F_OFD_SETLKW} request after being used for an
4329 @code{F_OFD_GETLK} request, it is necessary to inspect and reset the
4330 @code{l_pid} field to @math{0}.
4335 This macro is used as the @var{command} argument to @code{fcntl}, to
4337 requires a third argument of type @w{@code{struct flock *}} to be passed
4338 to @code{fcntl}, so that the form of the call is:
4346 @code{*@var{lockp}}.  Existing locks are not reported if they are
4348 specify a lock type of @code{F_WRLCK} if you want to find out about both
4349 read and write locks, or @code{F_RDLCK} if you want to find out about
4353 @var{lockp} argument, but @code{fcntl} only returns information about
4356 The @code{l_whence} member of the @var{lockp} structure are set to
4357 @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields are set
4361 is to update the @code{l_type} field to the value @code{F_UNLCK}.
4363 The normal return value from @code{fcntl} with this command is either @math{0}
4364 on success or @math{-1}, which indicates an error. The following @code{errno}
4367 @table @code
4380 This macro is used as the @var{command} argument to @code{fcntl}, to
4382 third argument of type @w{@code{struct flock *}} to be passed to
4383 @code{fcntl}, so that the form of the call is:
4391 can remove a lock by specifying a lock type of @code{F_UNLCK}.
4393 If the lock cannot be set, @code{fcntl} returns immediately with a value
4395 to release locks.  If @code{fcntl} succeeds, it returns @math{0}.
4397 The following @code{errno} error conditions are defined for this
4400 @table @code
4428 This macro is used as the @var{command} argument to @code{fcntl}, to
4430 @code{F_OFD_SETLK} command, but causes the process to wait until the request
4433 This command requires a third argument of type @code{struct flock *}, as
4434 for the @code{F_OFD_SETLK} command.
4436 The @code{fcntl} return values and errors are the same as for the
4437 @code{F_OFD_SETLK} command, but these additional @code{errno} error conditions
4440 @table @code
4451 its own @code{open} of the file, to obtain its own open file description.
4482 If we, however, were to replace the @code{F_OFD_SETLK} and
4483 @code{F_OFD_SETLKW} commands with their process-associated lock
4493 If you set the @code{O_ASYNC} status flag on a file descriptor
4494 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
4497 @code{F_SETOWN} command to the @code{fcntl} function.  If the file
4498 descriptor is a socket, this also selects the recipient of @code{SIGURG}
4500 see @ref{Out-of-Band Data}.  (@code{SIGURG} is sent in any situation
4501 where @code{select} would report the socket as having an ``exceptional
4504 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
4514 This macro is used as the @var{command} argument to @code{fcntl}, to
4516 group to which @code{SIGIO} signals are sent.  (For a terminal, this is
4518 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
4523 The following @code{errno} error condition is defined for this command:
4525 @table @code
4533 This macro is used as the @var{command} argument to @code{fcntl}, to
4535 @code{SIGIO} signals are sent.  This command requires a third argument
4536 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
4546 The return value from @code{fcntl} with this command is @math{-1}
4548 @code{errno} error conditions are defined for this command:
4550 @table @code
4567 devices and objects in terms of a few file primitives - @code{read},
4568 @code{write} and @code{lseek}.  However, most devices also have a few
4578 cannot move in byte increments, @code{lseek} is inapplicable).
4596 Instead these minor operations, known as @dfn{IOCTL}s, are assigned code
4597 numbers and multiplexed through the @code{ioctl} function, defined in
4598 @code{sys/ioctl.h}.  The code numbers themselves are defined in many
4605 The @code{ioctl} function performs the generic I/O operation