* Waiting for I/O:: How to check for input or output
on multiple file descriptors.
* Synchronizing I/O:: Making sure all I/O actions completed.
+* Asynchronous I/O:: Perform I/O in parallel.
* Control Operations:: Various other operations on file
descriptors.
* Duplicating Descriptors:: Fcntl commands for duplicating
@c !!! umask
+If on a 32 bits 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} 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.
+
This function is a cancelation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{open} is
@end deftypefun
@comment fcntl.h
+@comment LFS
+@deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
+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
+the difference is that on 32 bits 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
+instead the counterparts named @code{*64}, e.g., @code{read64}.
+
+When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
+function is actually available under the name @code{open}. I.e., the
+new, extended API using 64 bit file sizes and offsets transparently
+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})
This function is obsolete. The call:
@smallexample
open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
@end smallexample
+
+If on a 32 bits 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.
+@end deftypefn
+
+@comment fcntl.h
+@comment LFS
+@deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
+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 bits 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
+instead the counterparts named @code{*64}, e.g., @code{read64}.
+
+When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
+function is actually available under the name @code{open}. I.e., the
+new, extended API using 64 bit file sizes and offsets transparently
+replaces the old API.
@end deftypefn
@comment unistd.h
not be detected until @code{close}. @xref{I/O Primitives}, for details
on their meaning.
@end table
+
+Please note that there is @emph{no} separate @code{close64} function.
+This is not necessary since this function does not determine nor depend
+on the more of the file. The kernel which performs the @code{close}
+operation knows for which mode the descriptor is used and can handle
+this situation.
@end deftypefun
To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
@comment unistd.h
@comment X/Open
-@deftypefun int truncate (const char *@var{name}, size_t @var{length})
+@deftypefun int truncate (const char *@var{name}, off_t @var{length})
The @code{truncation} function truncates the file named by @var{name} to
at most @var{length} bytes. I.e., if the file was larger before the
extra bytes are stripped of. If the file was small or equal to
@var{length} in size before nothing is done. The file must be writable
by the user to perform this operation.
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{truncate} function is in fact @code{truncate64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@math{2^63} bytes.
+
The return value is zero is everything went ok. Otherwise the return
value is @math{-1} and the global variable @var{errno} is set to:
@table @code
@end deftypefun
@comment unistd.h
+@comment LFS
+@deftypefun int truncate64 (const char *@var{name}, off64_t @var{length})
+This function is similar to the @code{truncate} function. The
+difference is that the @var{length} argument is even on 32 bits machines
+64 bits wide which allows to handle file with a size up to @math{2^63}
+bytes.
+
+When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{truncate} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
+@comment unistd.h
@comment POSIX
-@deftypefun int ftruncate (int @var{fd}, size_t @var{length})
+@deftypefun int ftruncate (int @var{fd}, off_t @var{length})
The @code{ftruncate} function is similar to the @code{truncate}
function. The main difference is that it takes a descriptor for an
opened file instead of a file name to identify the object. The file
probably the fastest way. The function also operates on POSIX shared
memory segments if these are implemented by the system.
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{ftruncate} function is in fact @code{ftruncate64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@math{2^63} bytes.
+
On success the function returns zero. Otherwise it returns @math{-1}
and set @var{errno} to one of these values:
@table @code
@end table
@end deftypefun
+@comment unistd.h
+@comment LFS
+@deftypefun int ftruncate64 (int @var{id}, off64_t @var{length})
+This function is similar to the @code{ftruncate} function. The
+difference is that the @var{length} argument is even on 32 bits machines
+64 bits wide which allows to handle file with a size up to @math{2^63}
+bytes.
+
+When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{ftruncate} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
@node I/O Primitives
@section Input and Output Primitives
and @ref{Signal Handling}, for information about signals.
@end table
+Please note that there is no function named @code{read64}. This is not
+necessary since this function does not directly modify or handle the
+possibly wide file offset. Since the kernel handles this state
+internally the @code{read} function can be used for all cases.
+
This function is a cancelation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{read} is
position @var{offset}. The position of the file descriptor itself is
not effected 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{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.
+
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
error codes are also the same. Only there are a few more error codes:
version 2.
@end deftypefun
+@comment unistd.h
+@comment LFS
+@deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
+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 bits machines to address
+files larger then @math{2^31} bytes and up to @math{2^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 sources are defined using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{pread} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
@cindex writing to a file descriptor
@comment unistd.h
@comment POSIX.1
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
@end smallexample
+Please note that there is no function named @code{write64}. This is not
+necessary since this function does not directly modify or handle the
+possibly wide file offset. Since the kernel handles this state
+internally the @code{write} function can be used for all cases.
+
This function is a cancelation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{write} is
position @var{offset}. The position of the file descriptor itself is
not effected 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{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.
+
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
error codes are also the same. Only there are a few more error codes:
version 2.
@end deftypefun
+@comment unistd.h
+@comment LFS
+@deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
+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 bits machines to address
+files larger then @math{2^31} bytes and up to @math{2^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 sources are defined using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{pwrite} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
@node File Position Primitive
@section Setting the File Position of a Descriptor
@code{ESPIPE} if the object is not seekable.)
@end table
+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.
+
This function is a cancelation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{lseek} is
descriptors.
@end deftypefun
+@comment unistd.h
+@comment LFS
+@deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
+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 bits machines to address
+files larger then @math{2^31} bytes and up to @math{2^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 sources are defined using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{lseek} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
You can have multiple descriptors for the same file if you open the file
more than once, or if you duplicate a descriptor with @code{dup}.
Descriptors that come from separate calls to @code{open} have independent
In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
@end deftp
+@comment sys/types.h
+@comment LFS
+@deftp {Data Type} off64_t
+This type is used similar to @code{off_t}. The difference is that even
+on 32 bits machines, where the @code{off_t} type would 32 bits,
+@code{off64_t} has 64 bits and so is able to address files up to
+@math{2^63} bytes in length.
+@end deftp
+
These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
of compatibility with older BSD systems. They are defined in two
different header files: @file{fcntl.h} and @file{sys/file.h}.
@end deftypefun
+@node Asynchronous I/O
+@section Perform I/O Operations in Parallel
+
+The POSIX.1b standard defines a new set of I/O operations which can
+reduce the time an application spends waiting at I/O significantly. The
+new functions allow a program to initiate one or more I/O operations and
+then immediately resume the normal word while the I/O operations are
+executed in parallel.
+
+These functions are part of the library with realtime functions named
+@file{librt}. They are not actually part of the @file{libc} binary.
+The implementation of these functions can be done using support in the
+kernel )if available) or using a implementation based on threads at
+userlevel. In the later case it might be necessary to link applications
+linked with @file{librt} also with the thread library @file{libthread}.
+
+All AIO operations operate on files which previously were opened. There
+might be arbitrary many operations for one file running. The
+asynchronous I/O operations are controlled using a data structure named
+@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}
+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
+depending on these elements is not portable and is highly deprecated.
+
+@table @code
+@item int aio_fildes
+This element specifies the file descriptor which is used for the
+operation. It must be a legal descriptor since otherwise the operation
+fails for obvious reasons.
+
+The device on which the file is opened must allow the seek operation.
+I.e., it is not possible to use any of the AIO operations on devices
+like terminals where an @code{lseek} call would lead to an error.
+
+@item off_t aio_offset
+This element specified at which offset in the file the operation (input
+or output) is performed. Since the operation are carried in arbitrary
+order and more than one operation for one file descriptor can be
+started, one cannot expect a current read/write position of the file
+descriptor.
+
+@item volatile void *aio_buf
+This is a pointer to the buffer with the data to be written or the place
+where the ead data is stored.
+
+@item size_t aio_nbytes
+This element specifies the length of the buffer pointed to by @code{aio_buf}.
+
+@item int aio_reqprio
+If for the platform @code{_POSIX_PRIORITIZED_IO} and
+@code{_POSIX_PRIORITY_SCHEDULING} is defined the AIO requests are
+processed based on the current scheduling priority. The
+@code{aio_reqprio} element can then be used to lower the priority of the
+AIO operation.
+
+@item struct sigevent aio_sigevent
+This element specifies how the calling process is notified once the
+operation terminated. If the @code{sigev_notify} element is
+@code{SIGEV_NONE} no notification is send. If it is @code{SIGEV_SIGNAL}
+the signal determined by @code{sigev_signo} is send. Otherwise
+@code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
+which starts executing the function pointeed 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 to start an
+arbitrary number of operations at once and since each operationcan be
+input or output (or nothing) the information must be stored in the
+control block. The possible values are:
+
+@vtable @code
+@item LIO_READ
+Start a read operation. Read from the file at position
+@code{aio_offset} and store the next @code{aio_nbytes} bytes in the
+buffer pointed to by @code{aio_buf}.
+
+@item LIO_WRITE
+Start a write operation. Write @code{aio_nbytes} bytes starting at
+@code{aio_buf} into the file starting at position @code{aio_offset}.
+
+@item LIO_NOP
+Do nothing for this control block. This value is useful sometimes when
+an array of @code{struct aiocb} values contains holes, i.e., some of the
+values must not be handled allthough the whole array is presented to the
+@code{lio_listio} function.
+@end vtable
+@end table
+@end deftp
+
+@menu
+* Asynchronous Reads:: Asynchronous Read Operations.
+* Cancel AIO Operations:: Cancelation of AIO Operations.
+@end menu
+
+@node Asynchronous Reads
+@subsection Asynchronous Read Operations
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_read (struct aiocb *@var{aiocbp})
+This function initiates an asynchronous read operation. The function
+call immedaitely returns after the operation was enqueued or if before
+this happens an error was encoutered.
+
+The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
+@code{aiocbp->aio_buf} are written to the file for which
+@code{aiocbp->aio_fildes} is an descriptor, starting at the absolute
+position @code{aiocbp->aio_offset} in the file.
+
+If prioritized I/O is supported by the platform the
+@code{aiocbp->aio_reqprio} value is used to adjust the priority before
+the request is actually enqueued.
+
+The calling process is notified about the termination of the read
+request according to the @code{aiocbp->aio_sigevent} value.
+
+When @code{aio_read} returns the return value is zero if no error
+occurred that can be found before the process is enqueued. If such an
+earlier error is found the function returns @code{-1} and sets
+@code{errno} to one of the following values.
+
+@table @code
+@item EAGAIN
+The request was not enqueued due to (temporarily) exceeded resource
+limitations.
+@item ENOSYS
+The @code{aio_read} function is not implemented.
+@item EBADF
+The @code{aiocbp->aio_fildes} descriptor is not valid. This condition
+need not be recognized before enqueueing the request and so this error
+might also be signaled asynchrously.
+@item EINVAL
+The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
+invalid. This condition need not be recognized before enqueueing the
+request and so this error might also be signaled asynchrously.
+@end table
+
+In the case @code{aio_read} return zero the current status of the
+request can be queried using @code{aio_error} and @code{aio_return}
+questions. 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
+to @code{aio_return}. The returned value is the same as an equivalent
+call to @code{read} would have returned. Possible error code returned
+by @code{aio_error} are:
+
+@table @code
+@item EBADF
+The @code{aiocbp->aio_fildes} descriptor is not valid.
+@item ECANCELED
+The operation was canceled before the operation was finished
+(@pxref{Cancel AIO Operations})
+@item EINVAL
+The @code{aiocbp->aio_offset} value is invalid.
+@end table
+@end deftypefun
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_read64 (struct aiocb *@var{aiocbp})
+This function is similar to the @code{aio_read} function. The only
+difference is that only @w{32 bits} machines the file descriptor should
+be opened in the large file mode. Internally @code{aio_read64} uses
+functionality equivalent to @code{lseek64} to position the file
+descriptor correctly for the reading, as opposed to @code{lseek}
+funcationality used in @code{aio_read}.
+@end deftypefun
+
+
+@node Cancel AIO Operations
+@subsection Cancelation of AIO Operations
+
+
@node Control Operations
@section Control Operations on Files