* Stream/Descriptor Precautions:: Precautions needed if you use both
descriptors and streams.
* Scatter-Gather:: Fast I/O to discontinuous buffers.
+* Copying File Data:: Copying data between files.
* Memory-mapped I/O:: Using files like memory.
* Waiting for I/O:: How to check for input or output
on multiple file descriptors.
@pindex unistd.h
@pindex fcntl.h
-@comment fcntl.h
-@comment POSIX.1
@deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
+@standards{POSIX.1, fcntl.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
The @code{open} function creates and returns a new file descriptor for
the file named by @var{filename}. Initially, the file position
@table @code
@item EACCES
The file exists but is not readable/writable as requested by the @var{flags}
-argument, the file does not exist and the directory is unwritable so
+argument, or the file does not exist and the directory is unwritable so
it cannot be created.
@item EEXIST
If on a 32 bit machine the sources are translated with
@code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
descriptor opened in the large file mode which enables the file handling
-functions to use files up to @math{2^63} bytes in size and offset from
-@math{-2^63} to @math{2^63}. This happens transparently for the user
-since all of the lowlevel file handling functions are equally replaced.
+functions to use files up to @twoexp{63} bytes in size and offset from
+@minus{}@twoexp{63} to @twoexp{63}. This happens transparently for the user
+since all of the low-level file handling functions are equally replaced.
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
and @code{freopen} functions, that create streams.
@end deftypefun
-@comment fcntl.h
-@comment Unix98
@deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
+@standards{Unix98, fcntl.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
This function is similar to @code{open}. It returns a file descriptor
which can be used to access the file named by @var{filename}. The only
replaces the old API.
@end deftypefun
-@comment fcntl.h
-@comment POSIX.1
@deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
+@standards{POSIX.1, fcntl.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
This function is obsolete. The call:
If on a 32 bit machine the sources are translated with
@code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
descriptor opened in the large file mode which enables the file handling
-functions to use files up to @math{2^63} in size and offset from
-@math{-2^63} to @math{2^63}. This happens transparently for the user
-since all of the lowlevel file handling functions are equally replaced.
+functions to use files up to @twoexp{63} in size and offset from
+@minus{}@twoexp{63} to @twoexp{63}. This happens transparently for the user
+since all of the low-level file handling functions are equally replaced.
@end deftypefn
-@comment fcntl.h
-@comment Unix98
@deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
+@standards{Unix98, fcntl.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
This function is similar to @code{creat}. It returns a file descriptor
which can be used to access the file named by @var{filename}. The only
-the difference is that on 32 bit systems the file is opened in the
+difference is that on 32 bit systems the file is opened in the
large file mode. I.e., file length and file offsets can exceed 31 bits.
To use this file descriptor one must not use the normal operations but
replaces the old API.
@end deftypefn
-@comment unistd.h
-@comment POSIX.1
@deftypefun int close (int @var{filedes})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
The function @code{close} closes the file descriptor @var{filedes}.
Closing a file has the following consequences:
@file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftp {Data Type} ssize_t
+@standards{POSIX.1, unistd.h}
This data type is used to represent the sizes of blocks that can be
read or written in a single operation. It is similar to @code{size_t},
but must be a signed type.
@end deftp
@cindex reading from a file descriptor
-@comment unistd.h
-@comment POSIX.1
@deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{read} function reads up to @var{size} bytes from the file
with descriptor @var{filedes}, storing the results in the @var{buffer}.
@item EINTR
@code{read} was interrupted by a signal while it was waiting for input.
-@xref{Interrupted Primitives}. A signal will not necessary cause
+@xref{Interrupted Primitives}. A signal will not necessarily cause
@code{read} to return @code{EINTR}; it may instead result in a
successful @code{read} which returns fewer bytes than requested.
functions that read from streams, such as @code{fgetc}.
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c This is usually a safe syscall. The sysdeps/posix fallback emulation
@c is not MT-Safe because it uses lseek, read and lseek back, but is it
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
@code{pread} function is in fact @code{pread64} and the type
@code{off_t} has 64 bits, which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
The return value of @code{pread} describes the number of bytes read.
In the error case it returns @math{-1} like @code{read} does and the
The value given for @var{offset} is negative and therefore illegal.
@item ESPIPE
-The file descriptor @var{filedes} is associate with a pipe or a FIFO and
+The file descriptor @var{filedes} is associated with a pipe or a FIFO and
this device does not allow positioning of the file pointer.
@end table
version 2.
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c This is usually a safe syscall. The sysdeps/posix fallback emulation
@c is not MT-Safe because it uses lseek64, read and lseek64 back, but is
This function is similar to the @code{pread} function. The difference
is that the @var{offset} parameter is of type @code{off64_t} instead of
@code{off_t} which makes it possible on 32 bit machines to address
-files larger than @math{2^31} bytes and up to @math{2^63} bytes. The
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode.
@end deftypefun
@cindex writing to a file descriptor
-@comment unistd.h
-@comment POSIX.1
@deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Some say write is thread-unsafe on Linux without O_APPEND. In the VFS layer
+@c the vfs_write() does no locking around the acquisition of a file offset and
+@c therefore multiple threads / kernel tasks may race and get the same offset
+@c resulting in data loss.
+@c
+@c See:
+@c http://thread.gmane.org/gmane.linux.kernel/397980
+@c http://lwn.net/Articles/180387/
+@c
+@c The counter argument is that POSIX only says that the write starts at the
+@c file position and that the file position is updated *before* the function
+@c returns. What that really means is that any expectation of atomic writes is
+@c strictly an invention of the interpretation of the reader. Data loss could
+@c happen if two threads start the write at the same time. Only writes that
+@c come after the return of another write are guaranteed to follow the other
+@c write.
+@c
+@c The other side of the coin is that POSIX goes on further to say in
+@c "2.9.7 Thread Interactions with Regular File Operations" that threads
+@c should never see interleaving sets of file operations, but it is insane
+@c to do anything like that because it kills performance, so you don't get
+@c those guarantees in Linux.
+@c
+@c So we mark it thread safe, it doesn't blow up, but you might loose
+@c data, and we don't strictly meet the POSIX requirements.
+@c
+@c The fix for file offsets racing was merged in 3.14, the commits were:
+@c 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4, and
+@c d7a15f8d0777955986a2ab00ab181795cab14b01. Therefore after Linux 3.14 you
+@c should get mostly MT-safe writes.
The @code{write} function writes up to @var{size} bytes from
@var{buffer} to the file with descriptor @var{filedes}. The data in
@var{buffer} is not necessarily a character string and a null character is
functions that write to streams, such as @code{fputc}.
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c This is usually a safe syscall. The sysdeps/posix fallback emulation
@c is not MT-Safe because it uses lseek, write and lseek back, but is it
position @var{offset}. The position of the file descriptor itself is
not affected by the operation. The value is the same as before the call.
+However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite}
+appends data to the end of the file, regardless of the value of
+@code{offset}.
+
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
@code{pwrite} function is in fact @code{pwrite64} and the type
@code{off_t} has 64 bits, which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
The return value of @code{pwrite} describes the number of written bytes.
In the error case it returns @math{-1} like @code{write} does and the
version 2.
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c This is usually a safe syscall. The sysdeps/posix fallback emulation
@c is not MT-Safe because it uses lseek64, write and lseek64 back, but
This function is similar to the @code{pwrite} function. The difference
is that the @var{offset} parameter is of type @code{off64_t} instead of
@code{off_t} which makes it possible on 32 bit machines to address
-files larger than @math{2^31} bytes and up to @math{2^63} bytes. The
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode.
@code{pwrite} and so transparently replaces the 32 bit interface.
@end deftypefun
-
@node File Position Primitive
@section Setting the File Position of a Descriptor
@cindex file positioning on a file descriptor
@cindex positioning a file descriptor
@cindex seeking on a file descriptor
-@comment unistd.h
-@comment POSIX.1
@deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{lseek} function is used to change the file position of the
file with descriptor @var{filedes}.
be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
@code{SEEK_END}.
-@table @code
+@vtable @code
@item SEEK_SET
Specifies that @var{offset} is a count of characters from the beginning
of the file.
current end. If you set the position past the current end, and
actually write data, you will extend the file with zeros up to that
position.
-@end table
+@end vtable
The return value from @code{lseek} is normally the resulting file
position, measured in bytes from the beginning of the file.
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
@code{lseek} function is in fact @code{lseek64} and the type
@code{off_t} has 64 bits which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors.
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is similar to the @code{lseek} function. The difference
is that the @var{offset} parameter is of type @code{off64_t} instead of
@code{off_t} which makes it possible on 32 bit machines to address
-files larger than @math{2^31} bytes and up to @math{2^63} bytes. The
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode.
@file{foo}, and then four more characters starting with the 1028'th
character.
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} off_t
+@standards{POSIX.1, sys/types.h}
This is a signed integer type used to represent file sizes. In
@theglibc{}, this type is no narrower than @code{int}.
is transparently replaced by @code{off64_t}.
@end deftp
-@comment sys/types.h
-@comment Unix98
@deftp {Data Type} off64_t
+@standards{Unix98, sys/types.h}
This type is used similar to @code{off_t}. The difference is that even
on 32 bit machines, where the @code{off_t} type would have 32 bits,
@code{off64_t} has 64 bits and so is able to address files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
available under the name @code{off_t}.
of compatibility with older BSD systems. They are defined in two
different header files: @file{fcntl.h} and @file{sys/file.h}.
-@table @code
+@vtable @code
@item L_SET
An alias for @code{SEEK_SET}.
@item L_XTND
An alias for @code{SEEK_END}.
-@end table
+@end vtable
@node Descriptors and Streams
@section Descriptors and Streams
declared in the header file @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment POSIX.1
@deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
+@standards{POSIX.1, stdio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
The @code{fdopen} function returns a new stream for the file descriptor
@var{filedes}.
null pointer is returned instead.
In some other systems, @code{fdopen} may fail to detect that the modes
-for file descriptor do not permit the access specified by
+for file descriptors do not permit the access specified by
@code{opentype}. @Theglibc{} always checks for this.
@end deftypefun
For an example showing the use of the @code{fdopen} function,
see @ref{Creating a Pipe}.
-@comment stdio.h
-@comment POSIX.1
@deftypefun int fileno (FILE *@var{stream})
+@standards{POSIX.1, stdio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function returns the file descriptor associated with the stream
@var{stream}. If an error is detected (for example, if the @var{stream}
@code{fileno} returns @math{-1}.
@end deftypefun
-@comment stdio.h
-@comment GNU
@deftypefun int fileno_unlocked (FILE *@var{stream})
+@standards{GNU, stdio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fileno_unlocked} function is equivalent to the @code{fileno}
function except that it does not implicitly lock the stream if the state
@code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
-@table @code
+@vtable @code
@item STDIN_FILENO
-@vindex STDIN_FILENO
+@standards{POSIX.1, unistd.h}
This macro has value @code{0}, which is the file descriptor for
standard input.
@cindex standard input file descriptor
-@comment unistd.h
-@comment POSIX.1
@item STDOUT_FILENO
-@vindex STDOUT_FILENO
+@standards{POSIX.1, unistd.h}
This macro has value @code{1}, which is the file descriptor for
standard output.
@cindex standard output file descriptor
-@comment unistd.h
-@comment POSIX.1
@item STDERR_FILENO
-@vindex STDERR_FILENO
+@standards{POSIX.1, unistd.h}
This macro has value @code{2}, which is the file descriptor for
standard error output.
-@end table
+@end vtable
@cindex standard error file descriptor
@node Stream/Descriptor Precautions
These functions are controlled with arrays of @code{iovec} structures,
which describe the location and size of each buffer.
-@comment sys/uio.h
-@comment BSD
@deftp {Data Type} {struct iovec}
+@standards{BSD, sys/uio.h}
The @code{iovec} structure describes a buffer. It contains two fields:
@end table
@end deftp
-@comment sys/uio.h
-@comment BSD
@deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
+@standards{BSD, sys/uio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c The fallback sysdeps/posix implementation, used even on GNU/Linux
@c with old kernels that lack a full readv/writev implementation, may
@end deftypefun
-@comment sys/uio.h
-@comment BSD
@deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
+@standards{BSD, sys/uio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c The fallback sysdeps/posix implementation, used even on GNU/Linux
@c with old kernels that lack a full readv/writev implementation, may
@end deftypefun
-@c Note - I haven't read this anywhere. I surmised it from my knowledge
-@c of computer science. Thus, there could be subtleties I'm missing.
+@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
+@standards{BSD, sys/uio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pread, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{readv} function, with the difference
+it adds an extra @var{offset} parameter of type @code{off_t} similar to
+@code{pread}. The data is written to the file starting at position
+@var{offset}. The position of the file descriptor itself is not affected
+by the operation. The value is the same as before the call.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{preadv} function is in fact @code{preadv64} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is a count of bytes (@emph{not} buffers) read, @math{0}
+indicating end-of-file, or @math{-1} indicating an error. The possible
+errors are the same as in @code{readv} and @code{pread}.
+@end deftypefun
+
+@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
+@standards{BSD, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pread64, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{preadv} function with the difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t}. It makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{preadv} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
+@standards{BSD, sys/uio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwrite, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{writev} function, with the difference
+it adds an extra @var{offset} parameter of type @code{off_t} similar to
+@code{pwrite}. The data is written to the file starting at position
+@var{offset}. The position of the file descriptor itself is not affected
+by the operation. The value is the same as before the call.
+
+However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite}
+appends data to the end of the file, regardless of the value of
+@code{offset}.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{pwritev} function is in fact @code{pwritev64} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is a count of bytes (@emph{not} buffers) written, @math{0}
+indicating end-of-file, or @math{-1} indicating an error. The possible
+errors are the same as in @code{writev} and @code{pwrite}.
+@end deftypefun
+
+@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
+@standards{BSD, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwrite64, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{pwritev} function with the difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t}. It makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{pwritev} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+@deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
+@standards{GNU, sys/uio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls preadv.
+
+This function is similar to the @code{preadv} function, with the
+difference it adds an extra @var{flags} parameter of type @code{int}.
+Additionally, if @var{offset} is @math{-1}, the current file position
+is used and updated (like the @code{readv} function).
+
+The supported @var{flags} are dependent of the underlying system. For
+Linux it supports:
+
+@vtable @code
+@item RWF_HIPRI
+High priority request. This adds a flag that tells the file system that
+this is a high priority request for which it is worth to poll the hardware.
+The flag is purely advisory and can be ignored if not supported. The
+@var{fd} must be opened using @code{O_DIRECT}.
+
+@item RWF_DSYNC
+Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag.
+
+@item RWF_SYNC
+Per-IO synchronization as if the file was opened with @code{O_SYNC} flag.
+
+@item RWF_NOWAIT
+Use nonblocking mode for this operation; that is, this call to @code{preadv2}
+will fail and set @code{errno} to @code{EAGAIN} if the operation would block.
+@end vtable
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{preadv2} function is in fact @code{preadv64v2} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is a count of bytes (@emph{not} buffers) read, @math{0}
+indicating end-of-file, or @math{-1} indicating an error. The possible
+errors are the same as in @code{preadv} with the addition of:
+
+@table @code
+
+@item EOPNOTSUPP
+
+@c The default sysdeps/posix code will return it for any flags value
+@c different than 0.
+An unsupported @var{flags} was used.
+
+@end table
+
+@end deftypefun
+
+@deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
+@standards{GNU, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls preadv.
+
+This function is similar to the @code{preadv2} function with the difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t}. It makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{preadv2} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+
+@deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
+@standards{GNU, sys/uio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwritev.
+
+This function is similar to the @code{pwritev} function, with the
+difference it adds an extra @var{flags} parameter of type @code{int}.
+Additionally, if @var{offset} is @math{-1}, the current file position
+should is used and updated (like the @code{writev} function).
+
+The supported @var{flags} are dependent of the underlying system. For
+Linux, the supported flags are the same as those for @code{preadv2}.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{pwritev2} function is in fact @code{pwritev64v2} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is a count of bytes (@emph{not} buffers) write, @math{0}
+indicating end-of-file, or @math{-1} indicating an error. The possible
+errors are the same as in @code{preadv2}.
+@end deftypefun
+
+@deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
+@standards{GNU, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwritev.
+
+This function is similar to the @code{pwritev2} function with the difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t}. It makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{pwritev2} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+@node Copying File Data
+@section Copying data between two files
+@cindex copying files
+@cindex file copy
+
+A special function is provided to copy data between two files on the
+same file system. The system can optimize such copy operations. This
+is particularly important on network file systems, where the data would
+otherwise have to be transferred twice over the network.
+
+Note that this function only copies file data, but not metadata such as
+file permissions or extended attributes.
+
+@deftypefun ssize_t copy_file_range (int @var{inputfd}, off64_t *@var{inputpos}, int @var{outputfd}, off64_t *@var{outputpos}, ssize_t @var{length}, unsigned int @var{flags})
+@standards{GNU, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function copies up to @var{length} bytes from the file descriptor
+@var{inputfd} to the file descriptor @var{outputfd}.
+
+The function can operate on both the current file position (like
+@code{read} and @code{write}) and an explicit offset (like @code{pread}
+and @code{pwrite}). If the @var{inputpos} pointer is null, the file
+position of @var{inputfd} is used as the starting point of the copy
+operation, and the file position is advanced during it. If
+@var{inputpos} is not null, then @code{*@var{inputpos}} is used as the
+starting point of the copy operation, and @code{*@var{inputpos}} is
+incremented by the number of copied bytes, but the file position remains
+unchanged. Similar rules apply to @var{outputfd} and @var{outputpos}
+for the output file position.
+
+The @var{flags} argument is currently reserved and must be zero.
+
+The @code{copy_file_range} function returns the number of bytes copied.
+This can be less than the specified @var{length} in case the input file
+contains fewer remaining bytes than @var{length}, or if a read or write
+failure occurs. The return value is zero if the end of the input file
+is encountered immediately.
+
+If no bytes can be copied, to report an error, @code{copy_file_range}
+returns the value @math{-1} and sets @code{errno}. The following
+@code{errno} error conditions are specific to this function:
-Note that if the buffers are small (under about 1kB), high-level streams
-may be easier to use than these functions. However, @code{readv} and
-@code{writev} are more efficient when the individual buffers themselves
-(as opposed to the total output), are large. In that case, a high-level
-stream would not be able to cache the data effectively.
+@table @code
+@item EISDIR
+At least one of the descriptors @var{inputfd} or @var{outputfd} refers
+to a directory.
+
+@item EINVAL
+At least one of the descriptors @var{inputfd} or @var{outputfd} refers
+to a non-regular, non-directory file (such as a socket or a FIFO).
+
+The input or output positions before are after the copy operations are
+outside of an implementation-defined limit.
+
+The @var{flags} argument is not zero.
+
+@item EFBIG
+The new file size would exceed the process file size limit.
+@xref{Limits on Resources}.
+
+The input or output positions before are after the copy operations are
+outside of an implementation-defined limit. This can happen if the file
+was not opened with large file support (LFS) on 32-bit machines, and the
+copy operation would create a file which is larger than what
+@code{off_t} could represent.
+
+@item EBADF
+The argument @var{inputfd} is not a valid file descriptor open for
+reading.
+
+The argument @var{outputfd} is not a valid file descriptor open for
+writing, or @var{outputfd} has been opened with @code{O_APPEND}.
+
+@item EXDEV
+The input and output files reside on different file systems.
+@end table
+
+In addition, @code{copy_file_range} can fail with the error codes
+which are used by @code{read}, @code{pread}, @code{write}, and
+@code{pwrite}.
+
+The @code{copy_file_range} function is a cancellation point. In case of
+cancellation, the input location (the file position or the value at
+@code{*@var{inputpos}}) is indeterminate.
+@end deftypefun
@node Memory-mapped I/O
@section Memory-mapped I/O
Memory mapping only works on entire pages of memory. Thus, addresses
for mapping must be page-aligned, and length values will be rounded up.
-To determine the size of a page the machine uses one should use
+To determine the default size of a page the machine uses one should use:
@vindex _SC_PAGESIZE
@smallexample
size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
@end smallexample
-@noindent
-These functions are declared in @file{sys/mman.h}.
+On some systems, mappings can use larger page sizes
+for certain files, and applications can request larger page sizes for
+anonymous mappings as well (see the @code{MAP_HUGETLB} flag below).
+
+The following functions are declared in @file{sys/mman.h}:
-@comment sys/mman.h
-@comment POSIX
@deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset})
+@standards{POSIX, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{mmap} function creates a new mapping, connected to bytes
address is automatically removed. The address you give may still be
changed, unless you use the @code{MAP_FIXED} flag.
-@vindex PROT_READ
-@vindex PROT_WRITE
-@vindex PROT_EXEC
@var{protect} contains flags that control what kind of access is
permitted. They include @code{PROT_READ}, @code{PROT_WRITE}, and
-@code{PROT_EXEC}, which permit reading, writing, and execution,
-respectively. Inappropriate access will cause a segfault (@pxref{Program
-Error Signals}).
-
-Note that most hardware designs cannot support write permission without
-read permission, and many do not distinguish read and execute permission.
-Thus, you may receive wider permissions than you ask for, and mappings of
-write-only files may be denied even if you do not use @code{PROT_READ}.
+@code{PROT_EXEC}. The special flag @code{PROT_NONE} reserves a region
+of address space for future use. The @code{mprotect} function can be
+used to change the protection flags. @xref{Memory Protection}.
@var{flags} contains flags that control the nature of the map.
One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified.
@item MAP_ANONYMOUS
@itemx MAP_ANON
This flag tells the system to create an anonymous mapping, not connected
-to a file. @var{filedes} and @var{off} are ignored, and the region is
+to a file. @var{filedes} and @var{offset} are ignored, and the region is
initialized with zeros.
Anonymous maps are used as the basic primitive to extend the heap on some
@code{malloc} for large blocks. This is not an issue with @theglibc{},
as the included @code{malloc} automatically uses @code{mmap} where appropriate.
+@item MAP_HUGETLB
+@standards{Linux, sys/mman.h}
+This requests that the system uses an alternative page size which is
+larger than the default page size for the mapping. For some workloads,
+increasing the page size for large mappings improves performance because
+the system needs to handle far fewer pages. For other workloads which
+require frequent transfer of pages between storage or different nodes,
+the decreased page granularity may cause performance problems due to the
+increased page size and larger transfers.
+
+In order to create the mapping, the system needs physically contiguous
+memory of the size of the increased page size. As a result,
+@code{MAP_HUGETLB} mappings are affected by memory fragmentation, and
+their creation can fail even if plenty of memory is available in the
+system.
+
+Not all file systems support mappings with an increased page size.
+
+The @code{MAP_HUGETLB} flag is specific to Linux.
+
+@c There is a mechanism to select different hugepage sizes; see
+@c include/uapi/asm-generic/hugetlb_encode.h in the kernel sources.
+
@c Linux has some other MAP_ options, which I have not discussed here.
@c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to
@c user programs (and I don't understand the last two). MAP_LOCKED does
@item EINVAL
-Either @var{address} was unusable, or inconsistent @var{flags} were
-given.
+Either @var{address} was unusable (because it is not a multiple of the
+applicable page size), or inconsistent @var{flags} were given.
+
+If @code{MAP_HUGETLB} was specified, the file or system does not support
+large page sizes.
@item EACCES
@end deftypefun
-@comment sys/mman.h
-@comment LFS
@deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset})
+@standards{LFS, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c The page_shift auto detection when MMAP2_PAGE_SHIFT is -1 (it never
@c is) would be thread-unsafe.
replaces the old API.
@end deftypefun
-@comment sys/mman.h
-@comment POSIX
@deftypefun int munmap (void *@var{addr}, size_t @var{length})
+@standards{POSIX, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
@end deftypefun
-@comment sys/mman.h
-@comment POSIX
@deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags})
+@standards{POSIX, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
When using shared mappings, the kernel can write the file at any time
@end deftypefun
-@comment sys/mman.h
-@comment GNU
@deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag})
+@standards{GNU, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function can be used to change the size of an existing memory
have a fallback method to use should it fail. @xref{Mmap,,,standards,GNU
Coding Standards}.
-@comment sys/mman.h
-@comment POSIX
@deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice})
+@standards{POSIX, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function can be used to provide the system with @var{advice} about
The valid BSD values for @var{advice} are:
-@table @code
+@vtable @code
@item MADV_NORMAL
The region should receive no further special treatment.
causing any changes to the pages to be lost, as well as swapped
out pages to be discarded.
-@end table
+@item MADV_HUGEPAGE
+@standards{Linux, sys/mman.h}
+Indicate that it is beneficial to increase the page size for this
+mapping. This can improve performance for larger mappings because the
+system needs to handle far fewer pages. However, if parts of the
+mapping are frequently transferred between storage or different nodes,
+performance may suffer because individual transfers can become
+substantially larger due to the increased page size.
+
+This flag is specific to Linux.
+
+@item MADV_NOHUGEPAGE
+Undo the effect of a previous @code{MADV_HUGEPAGE} advice. This flag
+is specific to Linux.
+
+@end vtable
The POSIX names are slightly different, but with the same meanings:
-@table @code
+@vtable @code
@item POSIX_MADV_NORMAL
This corresponds with BSD's @code{MADV_NORMAL}.
@item POSIX_MADV_DONTNEED
This corresponds with BSD's @code{MADV_DONTNEED}.
-@end table
+@end vtable
@code{madvise} returns @math{0} for success and @math{-1} for
error. Errors include:
@end table
@end deftypefun
-@comment sys/mman.h
-@comment POSIX
@deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode})
+@standards{POSIX, sys/mman.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c shm_open @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
@c libc_once(where_is_shmfs) @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
@c mempcpy dup ok
@c unlink dup ok
-This function is inverse of @code{shm_open} and removes the object with
+This function is the inverse of @code{shm_open} and removes the object with
the given @var{name} previously created by @code{shm_open}.
@code{shm_unlink} returns @math{0} on success or @math{-1} on error.
On failure @code{errno} is set.
@end deftypefn
+@deftypefun int memfd_create (const char *@var{name}, unsigned int @var{flags})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+The @code{memfd_create} function returns a file descriptor which can be
+used to create memory mappings using the @code{mmap} function. It is
+similar to the @code{shm_open} function in the sense that these mappings
+are not backed by actual files. However, the descriptor returned by
+@code{memfd_create} does not correspond to a named object; the
+@var{name} argument is used for debugging purposes only (e.g., will
+appear in @file{/proc}), and separate invocations of @code{memfd_create}
+with the same @var{name} will not return descriptors for the same region
+of memory. The descriptor can also be used to create alias mappings
+within the same process.
+
+The descriptor initially refers to a zero-length file. Before mappings
+can be created which are backed by memory, the file size needs to be
+increased with the @code{ftruncate} function. @xref{File Size}.
+
+The @var{flags} argument can be a combination of the following flags:
+
+@vtable @code
+@item MFD_CLOEXEC
+@standards{Linux, sys/mman.h}
+The descriptor is created with the @code{O_CLOEXEC} flag.
+
+@item MFD_ALLOW_SEALING
+@standards{Linux, sys/mman.h}
+The descriptor supports the addition of seals using the @code{fcntl}
+function.
+
+@item MFD_HUGETLB
+@standards{Linux, sys/mman.h}
+This requests that mappings created using the returned file descriptor
+use a larger page size. See @code{MAP_HUGETLB} above for details.
+
+This flag is incompatible with @code{MFD_ALLOW_SEALING}.
+@end vtable
+
+@code{memfd_create} returns a file descriptor on success, and @math{-1}
+on failure.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EINVAL
+An invalid combination is specified in @var{flags}, or @var{name} is
+too long.
+
+@item EFAULT
+The @var{name} argument does not point to a string.
+
+@item EMFILE
+The operation would exceed the file descriptor limit for this process.
+
+@item ENFILE
+The operation would exceed the system-wide file descriptor limit.
+
+@item ENOMEM
+There is not enough memory for the operation.
+@end table
+@end deftypefun
+
@node Waiting for I/O
@section Waiting for Input or Output
@cindex waiting for input or output
as @code{fd_set} objects. Here is the description of the data type
and some macros for manipulating these objects.
-@comment sys/types.h
-@comment BSD
@deftp {Data Type} fd_set
+@standards{BSD, sys/types.h}
The @code{fd_set} data type represents file descriptor sets for the
@code{select} function. It is actually a bit array.
@end deftp
-@comment sys/types.h
-@comment BSD
@deftypevr Macro int FD_SETSIZE
+@standards{BSD, sys/types.h}
The value of this macro is the maximum number of file descriptors that a
@code{fd_set} object can hold information about. On systems with a
fixed maximum number, @code{FD_SETSIZE} is at least that number. On
that descriptor into an @code{fd_set}.
@end deftypevr
-@comment sys/types.h
-@comment BSD
@deftypefn Macro void FD_ZERO (fd_set *@var{set})
+@standards{BSD, sys/types.h}
@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
This macro initializes the file descriptor set @var{set} to be the
empty set.
@end deftypefn
-@comment sys/types.h
-@comment BSD
@deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
+@standards{BSD, sys/types.h}
@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
@c Setting a bit isn't necessarily atomic, so there's a potential race
@c here if set is not used exclusively.
evaluated more than once.
@end deftypefn
-@comment sys/types.h
-@comment BSD
@deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
+@standards{BSD, sys/types.h}
@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
@c Setting a bit isn't necessarily atomic, so there's a potential race
@c here if set is not used exclusively.
evaluated more than once.
@end deftypefn
-@comment sys/types.h
-@comment BSD
@deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set})
+@standards{BSD, sys/types.h}
@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
This macro returns a nonzero value (true) if @var{filedes} is a member
of the file descriptor set @var{set}, and zero (false) otherwise.
Next, here is the description of the @code{select} function itself.
-@comment sys/types.h
-@comment BSD
@deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout})
+@standards{BSD, sys/types.h}
@safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}}
@c The select syscall is preferred, but pselect6 may be used instead,
@c which requires converting timeout to a timespec and back. The
special functions which ensure that all operations finish before
they return.
-@comment unistd.h
-@comment X/Open
@deftypefun void sync (void)
+@standards{X/Open, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
A call to this function will not return as long as there is data which
has not been written to the device. All dirty buffers in the kernel will
committed, rather than all data in the system. For this, @code{sync} is overkill.
-@comment unistd.h
-@comment POSIX
@deftypefun int fsync (int @var{fildes})
+@standards{POSIX, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fsync} function can be used to make sure all data associated with
the open file @var{fildes} is written to the device associated with the
is enough to write all the file content data to the device.
Meta-information, like the modification time etc., are not that important
and leaving such information uncommitted does not prevent a successful
-recovering of the file in case of a problem.
+recovery of the file in case of a problem.
-@comment unistd.h
-@comment POSIX
@deftypefun int fdatasync (int @var{fildes})
+@standards{POSIX, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
When a call to the @code{fdatasync} function returns, it is ensured
that all of the file data is written to the device. For all pending I/O
@section Perform I/O Operations in Parallel
The POSIX.1b standard defines a new set of I/O operations which can
-significantly reduce the time an application spends waiting at I/O. The
+significantly reduce the time an application spends waiting for I/O. The
new functions allow a program to initiate one or more I/O operations and
then immediately resume normal work while the I/O operations are
executed in parallel. This functionality is available if the
@code{struct aiocb} (@dfn{AIO control block}). It is defined in
@file{aio.h} as follows.
-@comment aio.h
-@comment POSIX.1b
@deftp {Data Type} {struct aiocb}
+@standards{POSIX.1b, aio.h}
The POSIX.1b standard mandates that the @code{struct aiocb} structure
contains at least the members described in the following table. There
might be more elements which are used by the implementation, but
types but otherwise is equivalent to @code{struct aiocb}. Particularly,
all member names are the same.
-@comment aio.h
-@comment POSIX.1b
@deftp {Data Type} {struct aiocb64}
+@standards{POSIX.1b, aio.h}
@table @code
@item int aio_fildes
This element specifies the file descriptor which is used for the
@item struct sigevent aio_sigevent
This element specifies how the calling process is notified once the
-operation terminates. If the @code{sigev_notify}, element is
+operation terminates. If the @code{sigev_notify} element is
@code{SIGEV_NONE} no notification is sent. If it is @code{SIGEV_SIGNAL},
the signal determined by @code{sigev_signo} is sent. Otherwise,
@code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
-which starts executing the function pointed to by
+is created which starts executing the function pointed to by
@code{sigev_notify_function}.
@item int aio_lio_opcode
This element is only used by the @code{lio_listio} and
-@code{[lio_listio64} functions. Since these functions allow an
+@code{lio_listio64} functions. Since these functions allow an
arbitrary number of operations to start at once, and since each operation can be
input or output (or nothing), the information must be stored in the
control block. See the description of @code{struct aiocb} for a description
@node Asynchronous Reads/Writes
@subsection Asynchronous Read and Write Operations
-@comment aio.h
-@comment POSIX.1b
@deftypefun int aio_read (struct aiocb *@var{aiocbp})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
@c Calls aio_enqueue_request.
@c aio_enqueue_request @asulock @ascuheap @aculock @acsmem
replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int aio_read64 (struct aiocb64 *@var{aiocbp})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
This function is similar to the @code{aio_read} function. The only
difference is that on @w{32 bit} machines, the file descriptor should
be opened in the large file mode. Internally, @code{aio_read64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the reading,
-as opposed to @code{lseek} functionality used in @code{aio_read}.
+as opposed to the @code{lseek} functionality used in @code{aio_read}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
function is available under the name @code{aio_read} and so transparently
To write data asynchronously to a file, there exists an equivalent pair
of functions with a very similar interface.
-@comment aio.h
-@comment POSIX.1b
@deftypefun int aio_write (struct aiocb *@var{aiocbp})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
This function initiates an asynchronous write operation. The function
call immediately returns after the operation was enqueued or if before
@end table
In the case @code{aio_write} returns zero, the current status of the
-request can be queried using @code{aio_error} and @code{aio_return}
+request can be queried using the @code{aio_error} and @code{aio_return}
functions. As long as the value returned by @code{aio_error} is
@code{EINPROGRESS} the operation has not yet completed. If
@code{aio_error} returns zero, the operation successfully terminated,
otherwise the value is to be interpreted as an error code. If the
-function terminated, the result of the operation can be get using a call
+function terminated, the result of the operation can be obtained using a call
to @code{aio_return}. The returned value is the same as an equivalent
call to @code{read} would have returned. Possible error codes returned
by @code{aio_error} are:
replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int aio_write64 (struct aiocb64 *@var{aiocbp})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
This function is similar to the @code{aio_write} function. The only
difference is that on @w{32 bit} machines the file descriptor should
be opened in the large file mode. Internally @code{aio_write64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the writing,
-as opposed to @code{lseek} functionality used in @code{aio_write}.
+as opposed to the @code{lseek} functionality used in @code{aio_write}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
function is available under the name @code{aio_write} and so transparently
operations. It is therefore similar to a combination of @code{readv} and
@code{writev}.
-@comment aio.h
-@comment POSIX.1b
@deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
@c Call lio_listio_internal, that takes the aio_requests_mutex lock and
@c enqueues each request. Then, it waits for notification or prepares
having enqueued all the requests. In this case the caller gets a
notification of the termination of all requests according to the
@var{sig} parameter. If @var{sig} is @code{NULL} no notification is
-send. Otherwise a signal is sent or a thread is started, just as
+sent. Otherwise a signal is sent or a thread is started, just as
described in the description for @code{aio_read} or @code{aio_write}.
If @var{mode} is @code{LIO_WAIT}, the return value of @code{lio_listio}
is @math{0} when all requests completed successfully. Otherwise the
-function return @math{-1} and @code{errno} is set accordingly. To find
+function returns @math{-1} and @code{errno} is set accordingly. To find
out which request or requests failed one has to use the @code{aio_error}
function on all the elements of the array @var{list}.
transparently replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int lio_listio64 (int @var{mode}, struct aiocb64 *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
This function is similar to the @code{lio_listio} function. The only
difference is that on @w{32 bit} machines, the file descriptor should
be opened in the large file mode. Internally, @code{lio_listio64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the reading or
-writing, as opposed to @code{lseek} functionality used in
+writing, as opposed to the @code{lseek} functionality used in
@code{lio_listio}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
specific request already terminated and if so, what the result was.
The following two functions allow you to get this kind of information.
-@comment aio.h
-@comment POSIX.1b
@deftypefun int aio_error (const struct aiocb *@var{aiocbp})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function determines the error state of the request described by the
@code{struct aiocb} variable pointed to by @var{aiocbp}. If the
transparently replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is similar to @code{aio_error} with the only difference
that the argument is a reference to a variable of type @code{struct
machines.
@end deftypefun
-@comment aio.h
-@comment POSIX.1b
@deftypefun ssize_t aio_return (struct aiocb *@var{aiocbp})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function can be used to retrieve the return status of the operation
carried out by the request described in the variable pointed to by
@var{aiocbp}. As long as the error status of this request as returned
-by @code{aio_error} is @code{EINPROGRESS} the return of this function is
+by @code{aio_error} is @code{EINPROGRESS} the return value of this function is
undefined.
Once the request is finished this function can be used exactly once to
transparently replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun ssize_t aio_return64 (struct aiocb64 *@var{aiocbp})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is similar to @code{aio_return} with the only difference
that the argument is a reference to a variable of type @code{struct
When dealing with asynchronous operations it is sometimes necessary to
get into a consistent state. This would mean for AIO that one wants to
-know whether a certain request or a group of request were processed.
+know whether a certain request or a group of requests were processed.
This could be done by waiting for the notification sent by the system
after the operation terminated, but this sometimes would mean wasting
resources (mainly computation time). Instead POSIX.1b defines two
if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
@cindex synchronizing
-@comment aio.h
-@comment POSIX.1b
@deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
@c After fcntl to check that the FD is open, it calls
@c aio_enqueue_request.
-Calling this function forces all I/O operations operating queued at the
+Calling this function forces all I/O operations queued at the
time of the function call operating on the file descriptor
@code{aiocbp->aio_fildes} into the synchronized I/O completion state
(@pxref{Synchronizing I/O}). The @code{aio_fsync} function returns
successful. Otherwise the value returned is the value to which the
@code{fsync} or @code{fdatasync} function would have set the
@code{errno} variable. In this case nothing can be assumed about the
-consistency for the data written to this file descriptor.
+consistency of the data written to this file descriptor.
The return value of this function is @math{0} if the request was
successfully enqueued. Otherwise the return value is @math{-1} and
transparently replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
This function is similar to @code{aio_fsync} with the only difference
that the argument is a reference to a variable of type @code{struct
some situations this is not the ideal solution. In a program which
constantly updates clients somehow connected to the server it is not
always the best solution to go round robin since some connections might
-be slow. On the other hand letting the @code{aio_*} function notify the
+be slow. On the other hand letting the @code{aio_*} functions notify the
caller might also be not the best solution since whenever the process
-works on preparing data for on client it makes no sense to be
+works on preparing data for a client it makes no sense to be
interrupted by a notification since the new client will not be handled
before the current client is served. For situations like this
@code{aio_suspend} should be used.
-@comment aio.h
-@comment POSIX.1b
@deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c Take aio_requests_mutex, set up waitlist and requestlist, wait
@c for completion or timeout, and release the mutex.
transparently replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
This function is similar to @code{aio_suspend} with the only difference
that the argument is a reference to a variable of type @code{struct
implementation to decide whether it is possible to cancel the operation
or not. Therefore using this function is merely a hint.
-@comment aio.h
-@comment POSIX.1b
@deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp})
+@standards{POSIX.1b, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
@c After fcntl to check the fd is open, hold aio_requests_mutex, call
@c aio_find_req_fd, aio_remove_request, then aio_notify and
requests which haven't terminated and which were successfully canceled.
If there is one or more requests left which couldn't be canceled, the
return value is @code{AIO_NOTCANCELED}. In this case @code{aio_error}
-must be used to find out which of the, perhaps multiple, requests (in
+must be used to find out which of the, perhaps multiple, requests (if
@var{aiocbp} is @code{NULL}) weren't successfully canceled. If all
requests already terminated at the time @code{aio_cancel} is called the
return value is @code{AIO_ALLDONE}.
transparently replaces the normal implementation.
@end deftypefun
-@comment aio.h
-@comment Unix98
@deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp})
+@standards{Unix98, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
This function is similar to @code{aio_cancel} with the only difference
that the argument is a reference to a variable of type @code{struct
implemented. They could be system calls, but it is also possible to
emulate them at userlevel.
-At the point of this writing, the available implementation is a userlevel
+At the time of writing, the available implementation is a user-level
implementation which uses threads for handling the enqueued requests.
While this implementation requires making some decisions about
-limitations, hard limitations are something which is best avoided
+limitations, hard limitations are something best avoided
in @theglibc{}. Therefore, @theglibc{} provides a means
for tuning the AIO implementation according to the individual use.
-@comment aio.h
-@comment GNU
@deftp {Data Type} {struct aioinit}
+@standards{GNU, aio.h}
This data type is used to pass the configuration or tunable parameters
to the implementation. The program has to initialize the members of
this struct and pass it to the implementation using the @code{aio_init}
@end table
@end deftp
-@comment aio.h
-@comment GNU
@deftypefun void aio_init (const struct aioinit *@var{init})
+@standards{GNU, aio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c All changes to global objects are guarded by aio_requests_mutex.
This function must be called before any other AIO function. Calling it
is completely voluntary, as it is only meant to help the AIO
implementation perform better.
-Before calling the @code{aio_init}, function the members of a variable of
+Before calling @code{aio_init}, the members of a variable of
type @code{struct aioinit} must be initialized. Then a reference to
this variable is passed as the parameter to @code{aio_init} which itself
may or may not pay attention to the hints.
The function has no return value and no error cases are defined. It is
-a extension which follows a proposal from the SGI implementation in
+an extension which follows a proposal from the SGI implementation in
@w{Irix 6}. It is not covered by POSIX.1b or Unix98.
@end deftypefun
function; see @ref{Opening and Closing Files}.
@pindex fcntl.h
-@comment fcntl.h
-@comment POSIX.1
@deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
+@standards{POSIX.1, fcntl.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fcntl} function performs the operation specified by
@var{command} on the file descriptor @var{filedes}. Some commands
Briefly, here is a list of what the various commands are.
-@table @code
+@vtable @code
@item F_DUPFD
Duplicate the file descriptor (return another file descriptor pointing
to the same open file). @xref{Duplicating Descriptors}.
@item F_SETOWN
Set process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}.
-@end table
+@end vtable
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
while prototypes for @code{dup} and @code{dup2} are in the header file
@file{unistd.h}.
-@comment unistd.h
-@comment POSIX.1
@deftypefun int dup (int @var{old})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function copies descriptor @var{old} to the first available
descriptor number (the first number not currently open). It is
equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun int dup2 (int @var{old}, int @var{new})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function copies the descriptor @var{old} to descriptor number
@var{new}.
duplicate of @var{old}.
@end deftypefun
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_DUPFD
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
copy the file descriptor given as the first argument.
@file{fcntl.h}.
@pindex fcntl.h
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_GETFD
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should return the file descriptor flags associated
with the @var{filedes} argument.
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_SETFD
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set the file descriptor flags associated with the
@var{filedes} argument. This requires a third @code{int} argument to
the @code{fcntl} function. The value is an integer constant usable
as a bit mask value.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int FD_CLOEXEC
+@standards{POSIX.1, fcntl.h}
@cindex close-on-exec (file descriptor flag)
This flag specifies that the file descriptor should be closed when
an @code{exec} function is invoked; see @ref{Executing a File}. When
and allow execution of the file as a program.) The access modes are chosen
when the file is opened, and never change.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_RDONLY
+@standards{POSIX.1, fcntl.h}
Open the file for read access.
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_WRONLY
+@standards{POSIX.1, fcntl.h}
Open the file for write access.
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_RDWR
+@standards{POSIX.1, fcntl.h}
Open the file for both reading and writing.
@end deftypevr
But most programs will want to be portable to other POSIX.1 systems and
should use the POSIX.1 names above instead.
-@comment fcntl.h (optional)
-@comment GNU
@deftypevr Macro int O_READ
+@standards{GNU, fcntl.h (optional)}
Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU.
@end deftypevr
-@comment fcntl.h (optional)
-@comment GNU
@deftypevr Macro int O_WRITE
+@standards{GNU, fcntl.h (optional)}
Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU.
@end deftypevr
-@comment fcntl.h (optional)
-@comment GNU
@deftypevr Macro int O_EXEC
+@standards{GNU, fcntl.h (optional)}
Open the file for executing. Only defined on GNU.
@end deftypevr
access modes are not stored as distinct bit flags. The portable way to
extract the file access mode bits is with @code{O_ACCMODE}.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_ACCMODE
+@standards{POSIX.1, fcntl.h}
This macro stands for a mask that can be bitwise-ANDed with the file
status flag value to produce a value representing the file access mode.
The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
Here are the file name translation flags.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_CREAT
+@standards{POSIX.1, fcntl.h}
If set, the file will be created if it doesn't already exist.
@c !!! mode arg, umask
@cindex create on open (file status flag)
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_EXCL
+@standards{POSIX.1, fcntl.h}
If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
if the specified file already exists. This is guaranteed to never
clobber an existing file.
+
+The @code{O_EXCL} flag has a special meaning in combination with
+@code{O_TMPFILE}; see below.
+@end deftypevr
+
+@deftypevr Macro int O_TMPFILE
+@standards{GNU, fcntl.h}
+If this flag is specified, functions in the @code{open} family create an
+unnamed temporary file. In this case, the pathname argument to the
+@code{open} family of functions (@pxref{Opening and Closing Files}) is
+interpreted as the directory in which the temporary file is created
+(thus determining the file system which provides the storage for the
+file). The @code{O_TMPFILE} flag must be combined with @code{O_WRONLY}
+or @code{O_RDWR}, and the @var{mode} argument is required.
+
+The temporary file can later be given a name using @code{linkat},
+turning it into a regular file. This allows the atomic creation of a
+file with the specific file attributes (mode and extended attributes)
+and file contents. If, for security reasons, it is not desirable that a
+name can be given to the file, the @code{O_EXCL} flag can be specified
+along with @code{O_TMPFILE}.
+
+Not all kernels support this open flag. If this flag is unsupported, an
+attempt to create an unnamed temporary file fails with an error of
+@code{EINVAL}. If the underlying file system does not support the
+@code{O_TMPFILE} flag, an @code{EOPNOTSUPP} error is the result.
+
+The @code{O_TMPFILE} flag is a GNU extension.
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_NONBLOCK
+@standards{POSIX.1, fcntl.h}
@cindex non-blocking open
This prevents @code{open} from blocking for a ``long time'' to open the
file. This is only meaningful for some kinds of files, usually devices
such as serial ports; when it is not meaningful, it is harmless and
-ignored. Often opening a port to a modem blocks until the modem reports
+ignored. Often, opening a port to a modem blocks until the modem reports
carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
return immediately without a carrier.
then call @code{fcntl} to turn the bit off.
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_NOCTTY
+@standards{POSIX.1, fcntl.h}
If the named file is a terminal device, don't make it the controlling
terminal for the process. @xref{Job Control}, for information about
what it means to be the controlling terminal.
The following three file name translation flags exist only on
@gnuhurdsystems{}.
-@comment fcntl.h (optional)
-@comment GNU
@deftypevr Macro int O_IGNORE_CTTY
+@standards{GNU, fcntl.h (optional)}
Do not recognize the named file as the controlling terminal, even if it
refers to the process's existing controlling terminal device. Operations
on the new file descriptor will never induce job control signals.
@xref{Job Control}.
@end deftypevr
-@comment fcntl.h (optional)
-@comment GNU
@deftypevr Macro int O_NOLINK
+@standards{GNU, fcntl.h (optional)}
If the named file is a symbolic link, open the link itself instead of
the file it refers to. (@code{fstat} on the new file descriptor will
return the information returned by @code{lstat} on the link's name.)
@cindex symbolic link, opening
@end deftypevr
-@comment fcntl.h (optional)
-@comment GNU
@deftypevr Macro int O_NOTRANS
+@standards{GNU, fcntl.h (optional)}
If the named file is specially translated, do not invoke the translator.
Open the bare file the translator itself sees.
@end deftypevr
as part of @code{open} instead of in separate calls is that @code{open}
can do them @i{atomically}.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_TRUNC
+@standards{POSIX.1, fcntl.h}
Truncate the file to zero length. This option is only useful for
regular files, not special files such as directories or FIFOs. POSIX.1
requires that you open the file for writing to use @code{O_TRUNC}. In
The remaining operating modes are BSD extensions. They exist only
on some systems. On other systems, these macros are not defined.
-@comment fcntl.h (optional)
-@comment BSD
@deftypevr Macro int O_SHLOCK
+@standards{BSD, fcntl.h (optional)}
Acquire a shared lock on the file, as with @code{flock}.
@xref{File Locks}.
the lock on the new file first.
@end deftypevr
-@comment fcntl.h (optional)
-@comment BSD
@deftypevr Macro int O_EXLOCK
+@standards{BSD, fcntl.h (optional)}
Acquire an exclusive lock on the file, as with @code{flock}.
@xref{File Locks}. This is atomic like @code{O_SHLOCK}.
@end deftypevr
descriptor work. These flags are set by @code{open} and can be fetched
and changed with @code{fcntl}.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_APPEND
+@standards{POSIX.1, fcntl.h}
The bit that enables append mode for the file. If set, then all
@code{write} operations write the data at the end of the file, extending
it, regardless of the current file position. This is the only reliable
resulting in your data appearing someplace before the real end of file.
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int O_NONBLOCK
+@standards{POSIX.1, fcntl.h}
The bit that enables nonblocking mode for the file. If this bit is set,
@code{read} requests on the file can return immediately with a failure
status if there is no input immediately available, instead of blocking.
operating mode and a file name translation flag; @pxref{Open-time Flags}.
@end deftypevr
-@comment fcntl.h
-@comment BSD
@deftypevr Macro int O_NDELAY
+@standards{BSD, fcntl.h}
This is an obsolete name for @code{O_NONBLOCK}, provided for
compatibility with BSD. It is not defined by the POSIX.1 standard.
@end deftypevr
The remaining operating modes are BSD and GNU extensions. They exist only
on some systems. On other systems, these macros are not defined.
-@comment fcntl.h
-@comment BSD
@deftypevr Macro int O_ASYNC
+@standards{BSD, fcntl.h}
The bit that enables asynchronous input mode. If set, then @code{SIGIO}
signals will be generated when input is available. @xref{Interrupt Input}.
Asynchronous input mode is a BSD feature.
@end deftypevr
-@comment fcntl.h
-@comment BSD
@deftypevr Macro int O_FSYNC
+@standards{BSD, fcntl.h}
The bit that enables synchronous writing for the file. If set, each
@code{write} call will make sure the data is reliably stored on disk before
returning. @c !!! xref fsync
Synchronous writing is a BSD feature.
@end deftypevr
-@comment fcntl.h
-@comment BSD
@deftypevr Macro int O_SYNC
+@standards{BSD, fcntl.h}
This is another name for @code{O_FSYNC}. They have the same value.
@end deftypevr
-@comment fcntl.h
-@comment GNU
@deftypevr Macro int O_NOATIME
+@standards{GNU, fcntl.h}
If this bit is set, @code{read} will not update the access time of the
file. @xref{File Times}. This is used by programs that do backups, so
that backing a file up does not count as reading it.
The @code{fcntl} function can fetch or change file status flags.
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_GETFL
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
read the file status flags for the open file with descriptor
@var{filedes}.
@end table
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_SETFL
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to set
the file status flags for the open file corresponding to the
@var{filedes} argument. This command requires a third @code{int}
@code{fcntl} function are declared in the header file @file{fcntl.h}.
@pindex fcntl.h
-@comment fcntl.h
-@comment POSIX.1
@deftp {Data Type} {struct flock}
+@standards{POSIX.1, fcntl.h}
This structure is used with the @code{fcntl} function to describe a file
lock. It has these members:
@item off_t l_start
This specifies the offset of the start of the region to which the lock
-applies, and is given in bytes relative to the point specified by
+applies, and is given in bytes relative to the point specified by the
@code{l_whence} member.
@item off_t l_len
@end table
@end deftp
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_GETLK
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should get information about a lock. This command
requires a third argument of type @w{@code{struct flock *}} to be passed
@end table
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_SETLK
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set or clear a lock. This command requires a
third argument of type @w{@code{struct flock *}} to be passed to
by specifying a lock type of @code{F_UNLCK}.
If the lock cannot be set, @code{fcntl} returns immediately with a value
-of @math{-1}. This function does not block waiting for other processes
-to release locks. If @code{fcntl} succeeds, it return a value other
+of @math{-1}. This function does not block while waiting for other processes
+to release locks. If @code{fcntl} succeeds, it returns a value other
than @math{-1}.
The following @code{errno} error conditions are defined for this
@end table
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_SETLKW
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set or clear a lock. It is just like the
@code{F_SETLK} command, but causes the process to block (or wait)
The following macros are defined for use as values for the @code{l_type}
member of the @code{flock} structure. The values are integer constants.
-@table @code
-@comment fcntl.h
-@comment POSIX.1
-@vindex F_RDLCK
+@vtable @code
@item F_RDLCK
+@standards{POSIX.1, fcntl.h}
This macro is used to specify a read (or shared) lock.
-@comment fcntl.h
-@comment POSIX.1
-@vindex F_WRLCK
@item F_WRLCK
+@standards{POSIX.1, fcntl.h}
This macro is used to specify a write (or exclusive) lock.
-@comment fcntl.h
-@comment POSIX.1
-@vindex F_UNLCK
@item F_UNLCK
+@standards{POSIX.1, fcntl.h}
This macro is used to specify that the region is unlocked.
-@end table
+@end vtable
As an example of a situation where file locking is useful, consider a
program that can be run simultaneously by several different users, that
@end table
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_OFD_SETLK
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set or clear a lock. This command requires a
third argument of type @w{@code{struct flock *}} to be passed to
@end table
@end deftypevr
-@comment fcntl.h
-@comment POSIX.1
@deftypevr Macro int F_OFD_SETLKW
+@standards{POSIX.1, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set or clear a lock. It is just like the
@code{F_OFD_SETLK} command, but causes the process to wait until the request
The symbols in this section are defined in the header file
@file{fcntl.h}.
-@comment fcntl.h
-@comment BSD
@deftypevr Macro int F_GETOWN
+@standards{BSD, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should get information about the process or process
group to which @code{SIGIO} signals are sent. (For a terminal, this is
@end table
@end deftypevr
-@comment fcntl.h
-@comment BSD
@deftypevr Macro int F_SETOWN
+@standards{BSD, fcntl.h}
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set the process or process group to which
@code{SIGIO} signals are sent. This command requires a third argument
@code{sys/ioctl.h}. The code numbers themselves are defined in many
different headers.
-@comment sys/ioctl.h
-@comment BSD
@deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{})
+@standards{BSD, sys/ioctl.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{ioctl} function performs the generic I/O operation
projects / thirdparty / glibc.git / blobdiff