* 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
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:
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
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}.
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
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
@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
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
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
@code{pwrite} and so transparently replaces the 32 bit interface.
@end deftypefun
-@comment sys/uio.h
-@comment BSD
-@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
-@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
-
-@comment unistd.h
-@comment BSD
-@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
-@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
-
-@comment sys/uio.h
-@comment BSD
-@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
-@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
-
-@comment unistd.h
-@comment BSD
-@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
-@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
-
-@comment sys/uio.h
-@comment GNU
-@deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
-@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}. 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.
-@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
-
-@comment unistd.h
-@comment GNU
-@deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
-@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
-
-
-@comment sys/uio.h
-@comment GNU
-@deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
-@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}. The supported
-@var{flags} are dependent of the underlying system and for Linux it supports
-the same ones as 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
-
-@comment unistd.h
-@comment GNU
-@deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
-@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 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}.
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
@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
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}.
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
@pindex unistd.h
@vtable @code
-@comment unistd.h
-@comment POSIX.1
@item 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
+@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
+@standards{POSIX.1, unistd.h}
This macro has value @code{2}, which is the file descriptor for
standard error output.
@end vtable
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.
-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 efficiently.
+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:
+
+@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.
@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
causing any changes to the pages to be lost, as well as swapped
out pages to be discarded.
+@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:
@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
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
and leaving such information uncommitted does not prevent a successful
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
@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
@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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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:
@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
@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)
member of the @code{flock} structure. The values are integer constants.
@vtable @code
-@comment fcntl.h
-@comment POSIX.1
@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
@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
@item F_UNLCK
+@standards{POSIX.1, fcntl.h}
This macro is used to specify that the region is unlocked.
@end vtable
@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