Both functions of this @code{ftw} family take as one of the arguments a
reference to a callback function. The functions must be of these types.
+@comment ftw.h
+@comment GNU
@deftp {Data Type} __ftw_func_t
@smallexample
The last parameter is a flag given more information about the current
file. It can have the following values:
-@vindex FTW_F
-@vindex FTW_D
-@vindex FTW_NS
-@vindex FTW_DNR
-@vindex FTW_SL
-@table @code
+@vtable @code
@item FTW_F
The current item is a normal file or files which do not fit into one of
the following categories. This means especially special files, sockets
This value is only available if the program is compiled with
@code{_BSD_SOURCE} or @code{_XOPEN_EXTENDED} defined before including
the first header. The original SVID systems do not have symbolic links.
-@end table
+@end vtable
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+type is in fact @code{__ftw64_func_t} since this mode also changes
+@code{struct stat} to be @code{struct stat64}.
@end deftp
+For the LFS interface and the use in the function @code{ftw64} the
+header @file{ftw.h} defines another function type.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __ftw64_func_t
+
+@smallexample
+int (*) (const char *, const struct stat64 *, int)
+@end smallexample
+
+This type is used just like @code{__ftw_func_t} for the callback
+function, but this time called from @code{ftw64}. The second parameter
+to the function is this time a pointer to a variable of type
+@code{struct stat64} which is able to represent the larger values.
+@end deftp
+
+@comment ftw.h
+@comment GNU
@deftp {Data Type} __nftw_func_t
@smallexample
The last parameter of the callback function is a pointer to a structure
with some extra information as described below.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+type is in fact @code{__nftw64_func_t} since this mode also changes
+@code{struct stat} to be @code{struct stat64}.
@end deftp
+For the LFS interface there is also a variant of this data type
+available which has to be used with the @code{nftw64} function.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __nftw64_func_t
+
+@smallexample
+int (*) (const char *, const struct stat64 *, int, struct FTW *)
+@end smallexample
+
+This type is used just like @code{__nftw_func_t} for the callback
+function, but this time called from @code{nftw64}. The second parameter
+to the function is this time a pointer to a variable of type
+@code{struct stat64} which is able to represent the larger values.
+@end deftp
+
+@comment ftw.h
+@comment XPG4.2
@deftp {Data Type} {struct FTW}
The contained information helps to interpret the name parameter and
gives some information about current state of the traversal of the
@code{stat} on an item) the function return @math{-1}. If a callback
function returns a value other than @math{0} this value is returned as
the return value of @code{ftw}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{ftw64}. I.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment ftw.h
+@comment Unix98
+@deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors})
+This function is similar to @code{ftw} but it can work on filesystems
+with large files since the information about the files is reported using
+a variable of type @code{struct stat64} which is passed by reference to
+the callback function.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is available under the name @code{ftw} and
+transparently replaces the old implementation.
@end deftypefun
@comment ftw.h
argument which is @math{0} or a combination of any of the following
values, combined using bitwise OR.
-@table @code
+@vtable @code
@item FTW_PHYS
While traversing the directory symbolic links are not followed. I.e.,
if this flag is given symbolic links are reported using the
subdirectories before the callback function is called for the directory
itself (depth-first processing). This also means the type flag given to
the callback function is @code{FTW_DP} and not @code{FTW_D}.
-@end table
+@end vtable
The return value is computed in the same way as for @code{ftw}.
@code{nftw} return @math{0} if no failure occurred in @code{nftw} and
internal errors such as memory problems @math{-1} is returned and
@var{errno} is set accordingly. If the return value of a callback
invocation is nonzero this very same value is returned.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{nftw64}. I.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment ftw.h
+@comment Unix98
+@deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag})
+This function is similar to @code{nftw} but it can work on filesystems
+with large files since the information about the files is reported using
+a variable of type @code{struct stat64} which is passed by reference to
+the callback function.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is available under the name @code{nftw} and
+transparently replaces the old implementation.
@end deftypefun
attributes of the file. @xref{File Times}.
@c !!! st_rdev
-@item unsigned int st_blocks
+@item blkcnt_t st_blocks
This is the amount of disk space that the file occupies, measured in
units of 512-byte blocks.
in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
Here is a list of them.
+The extensions for the Large File Support (LFS) require even on 32 bits
+machine types which can handle file sizes up to @math{2^63}. Therefore
+a new definition of @code{struct stat} is necessary.
+
+@comment sys/stat.h
+@comment LFS
+@deftp {Data Type} {struct stat64}
+The members of this type are the same and have the same names as those
+in @code{struct stat}. The only difference is that the members
+@code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
+type to support larger values.
+
+@table @code
+@item mode_t st_mode
+Specifies the mode of the file. This includes file type information
+(@pxref{Testing File Type}) and the file permission bits
+(@pxref{Permission Bits}).
+
+@item ino64_t st_ino
+The file serial number, which distinguishes this file from all other
+files on the same device.
+
+@item dev_t st_dev
+Identifies the device containing the file. The @code{st_ino} and
+@code{st_dev}, taken together, uniquely identify the file. The
+@code{st_dev} value is not necessarily consistent across reboots or
+system crashes, however.
+
+@item nlink_t st_nlink
+The number of hard links to the file. This count keeps track of how
+many directories have entries for this file. If the count is ever
+decremented to zero, then the file itself is discarded as soon as no
+process still holds it open. Symbolic links are not counted in the
+total.
+
+@item uid_t st_uid
+The user ID of the file's owner. @xref{File Owner}.
+
+@item gid_t st_gid
+The group ID of the file. @xref{File Owner}.
+
+@item off64_t st_size
+This specifies the size of a regular file in bytes. For files that
+are really devices and the like, this field isn't usually meaningful.
+For symbolic links, this specifies the length of the file name the link
+refers to.
+
+@item time_t st_atime
+This is the last access time for the file. @xref{File Times}.
+
+@item unsigned long int st_atime_usec
+This is the fractional part of the last access time for the file.
+@xref{File Times}.
+
+@item time_t st_mtime
+This is the time of the last modification to the contents of the file.
+@xref{File Times}.
+
+@item unsigned long int st_mtime_usec
+This is the fractional part of the time of last modification to the
+contents of the file. @xref{File Times}.
+
+@item time_t st_ctime
+This is the time of the last modification to the attributes of the file.
+@xref{File Times}.
+
+@item unsigned long int st_ctime_usec
+This is the fractional part of the time of last modification to the
+attributes of the file. @xref{File Times}.
+
+@c !!! st_rdev
+@item blkcnt64_t st_blocks
+This is the amount of disk space that the file occupies, measured in
+units of 512-byte blocks.
+
+@item unsigned int st_blksize
+The optimal block size for reading of writing this file, in bytes. You
+might use this size for allocating the buffer space for reading of
+writing the file. (This is unrelated to @code{st_blocks}.)
+@end table
+@end deftp
+
@comment sys/types.h
@comment POSIX.1
@deftp {Data Type} mode_t
This is an arithmetic data type used to represent file serial numbers.
(In Unix jargon, these are sometimes called @dfn{inode numbers}.)
In the GNU system, this type is equivalent to @code{unsigned long int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{ino64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} ino64_t
+This is an arithmetic data type used to represent file serial numbers
+for the use in LFS. In the GNU system, this type is equivalent to
+@code{unsigned long longint}.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{ino_t}.
@end deftp
@comment sys/types.h
In the GNU system, this is equivalent to @code{unsigned short int}.
@end deftp
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} blkcnt_t
+This is an arithmetic data type used to represent block counts.
+In the GNU system, this is equivalent to @code{unsigned long int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{blkcnt64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} blkcnt64_t
+This is an arithmetic data type used to represent block counts for the
+use in LFS. In the GNU system, this is equivalent to @code{unsigned
+long long int}.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{blkcnt_t}.
+@end deftp
+
@node Reading Attributes
@subsection Reading the Attributes of a File
@item ENOENT
The file named by @var{filename} doesn't exist.
@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{stat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
+This function is similar to @code{stat} but it is also able to work on
+file larger then @math{2^31} bytes on 32 bits systems. To be able to do
+this the result is stored in a variable of type @code{struct stat64} to
+which @var{buf} must point.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{stat} and so transparently
+replaces the interface for small fiels on 32 bits machines.
@end deftypefun
@comment sys/stat.h
@item EBADF
The @var{filedes} argument is not a valid file descriptor.
@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{fstat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf})
+This function is similar to @code{fstat} but it is prepared to work on
+large files on 32 bits platforms. For large files the file descriptor
+@var{filedes} should be returned by @code{open64} or @code{creat64}.
+The @var{buf} pointer points to a variable of type @code{struct stat64}
+which is able to represent the larger values.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{fstat} and so transparently
+replaces the interface for small fiels on 32 bits machines.
@end deftypefun
@comment sys/stat.h
follow symbolic links. If @var{filename} is the name of a symbolic
link, @code{lstat} returns information about the link itself; otherwise,
@code{lstat} works like @code{stat}. @xref{Symbolic Links}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{lstat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf})
+This function is similar to @code{lstat} but it is also able to work on
+file larger then @math{2^31} bytes on 32 bits systems. To be able to do
+this the result is stored in a variable of type @code{struct stat64} to
+which @var{buf} must point.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{lstat} and so transparently
+replaces the interface for small fiels on 32 bits machines.
@end deftypefun
@node Testing File Type
terminates abnormally).
This function is reentrant.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{tmpfile64}. I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} tmpfile64 (void)
+This function is similar to @code{tmpfile} but the stream it returns a
+pointer for is opened using @code{tmpfile64}. Therefore this stream can be
+used even on files larger then @math{2^31} bytes on 32 bits machines.
+
+Please note that the return type is still @code{FILE *}. There is no
+special @code{FILE} type for the LFS interface.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{tmpfile}
+and so transparently replaces the old interface.
@end deftypefun
@comment stdio.h
@end deftypefun
@comment fcntl.h
-@comment LFS
+@comment Unix98
@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
@end deftypefn
@comment fcntl.h
-@comment LFS
+@comment Unix98
@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
@end deftypefun
@comment unistd.h
-@comment LFS
+@comment Unix98
@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
@end deftypefun
@comment unistd.h
-@comment LFS
+@comment Unix98
@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
@end deftypefun
@comment unistd.h
-@comment LFS
+@comment Unix98
@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
@end deftypefun
@comment unistd.h
-@comment LFS
+@comment Unix98
@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
@end deftypefun
@comment unistd.h
-@comment LFS
+@comment Unix98
@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
@deftp {Data Type} off_t
This is an arithmetic data type used to represent file sizes.
In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{off64_t}.
@end deftp
@comment sys/types.h
-@comment LFS
+@comment Unix98
@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.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{off_t}.
@end deftp
These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
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.
+executed in parallel. The functionality is available if the
+@file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
These functions are part of the library with realtime functions named
@file{librt}. They are not actually part of the @file{libc} binary.
@code{lio_listio} function.
@end vtable
@end table
+
+When the sourcs are compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this type is in fact @code{struct aiocb64} since the LFS
+interface transparently replaces the @code{struct aiocb} definition.
+@end deftp
+
+For use with the AIO functions defined in the LFS there is a similar type
+defined which replaces the types of the appropriate members with larger
+types but otherwise is equivalent to @code{struct aiocb}. Especially
+all member names are the same.
+
+@comment aio.h
+@comment POSIX.1b
+@deftp {Data Type} {struct aiocb64}
+@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 off64_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. See the description of @code{struct aiocb} for a description
+of the possible values.
+@end table
+
+When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this type is available under the name @code{struct
+aiocb64} since the LFS replaces transparently the old interface.
@end deftp
@menu
-* Asynchronous Reads:: Asynchronous Read Operations.
+* Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
+* Status of AIO Operations:: Getting the Status of AIO Operations.
+* Synchronizing AIO Operations:: Getting into a consistent state.
* Cancel AIO Operations:: Cancelation of AIO Operations.
+* Configuration of AIO:: How to optimize the AIO implementation.
@end menu
-@node Asynchronous Reads
-@subsection Asynchronous Read Operations
+@node Asynchronous Reads/Writes
+@subsection Asynchronous Read and Write 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
+call immediately 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.
+The first @code{aiocbp->aio_nbytes} bytes of the file for which
+@code{aiocbp->aio_fildes} is an descriptor are written to the buffer
+starting at @code{aiocbp->aio_buf}. @code{aiocbp->aio_fildes} is an
+descriptor. Reading starts 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
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
+early error is found the function returns @math{-1} and sets
@code{errno} to one of the following values.
@table @code
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
+In the case @code{aio_read} returns 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
@item EINVAL
The @code{aiocbp->aio_offset} value is invalid.
@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_read64} since the LFS interface transparently
+replaces the normal implementation.
@end deftypefun
@comment aio.h
-@comment POSIX.1b
+@comment Unix98
@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}.
+functionality equivalent to @code{lseek64} (@pxref{File Position
+Primitive}) to position the file descriptor correctly for the reading,
+as opposed to @code{lseek} funcationality 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
+replaces the interface for small files on 32 bits machines.
@end deftypefun
+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})
+This function initiates an asynchronous write operation. The function
+call immediately 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_write} returns the return value is zero if no error
+occurred that can be found before the process is enqueued. If such an
+early error is found the function returns @math{-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_write} 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_write} returns 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
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_write64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_write64 (struct aiocb *@var{aiocbp})
+This function is similar to the @code{aio_write} 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_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} funcationality 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
+replaces the interface for small files on 32 bits machines.
+@end deftypefun
+
+Beside these functions with the more or less traditional interface
+POSIX.1b also defines a function with can initiate more than one
+operation at once and which can handled freely mixed read and write
+operation. 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})
+The @code{lio_listio} function can be used to enqueue an arbitrary
+number of read and write requests at one time. The requests can all be
+meant for the same file, all for different files or every solution in
+between.
+
+@code{lio_listio} gets the @var{nent} requests from the array pointed to
+by @var{list}. What operation has to be performed is determined by the
+@code{aio_lio_opcode} member in each element of @var{list}. If this
+field is @code{LIO_READ} an read operation is queued, similar to a call
+of @code{aio_read} for this element of the array (except that the way
+the termination is signalled is different, as we will see below). If
+the @code{aio_lio_opcode} member is @code{LIO_WRITE} an write operation
+is enqueued. Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
+in which case this element of @var{list} is simply ignored. This
+``operation'' is useful in situations where one has a fixed array of
+@code{struct aiocb} elements from which only a few need to be handled at
+a time. Another situation is where the @code{lio_listio} call was
+cancelled before all requests are processed (@pxref{Cancel AIO
+Operations}) and the remaining requests have to be reissued.
+
+The the other members of each element of the array pointed to by
+@code{list} must have values suitable for the operation as described in
+the documentation for @code{aio_read} and @code{aio_write} above.
+
+The @var{mode} argument determines how @code{lio_listio} behaves after
+having enqueued all the requests. If @var{mode} is @code{LIO_WAIT} it
+waits until all requests terminated. Otherwise @var{mode} must be
+@code{LIO_NOWAIT} and in this case the function returns immeditely after
+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
+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
+out which request or requests failed one has to use the @code{aio_error}
+function on all the elements of the array @var{list}.
+
+In case @var{mode} is @code{LIO_NOWAIT} the function return @math{0} if
+all requests were enqueued correctly. The current state of the requests
+can be found using @code{aio_error} and @code{aio_return} as described
+above. In case @code{lio_listio} returns @math{-1} in this mode the
+global variable @code{errno} is set accordingly. If a request did not
+yet terminate a call to @code{aio_error} returns @code{EINPROGRESS}. If
+the value is different the request is finished and the error value (or
+@math{0}) is returned and the result of the operation can be retrieved
+using @code{aio_return}.
+
+Possible values for @code{errno} are:
+
+@table @code
+@item EAGAIN
+The resources necessary to queue all the requests are not available in
+the moment. The error status for each element of @var{list} must be
+checked which request failed.
+
+Another reason could be that the systemwide limit of AIO requests is
+exceeded. This cannot be the case for the implementation on GNU systems
+since no arbitrary limits exist.
+@item EINVAL
+The @var{mode} parameter is invalid or @var{nent} is larger than
+@code{AIO_LISTIO_MAX}.
+@item EIO
+One or more of the request's I/O operations failed. The error status of
+each request should be checked which one failed.
+@item ENOSYS
+The @code{lio_listio} function is not supported.
+@end table
+
+If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
+an request the error status for this request returned by
+@code{aio_error} is @code{ECANCELED}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{lio_listio64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig})
+This function is similar to the @code{aio_listio} function. The only
+difference is that only @w{32 bits} 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} funcationality used in
+@code{lio_listio}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{lio_listio} and so
+transparently replaces the interface for small files on 32 bits
+machines.
+@end deftypefun
+
+@node Status of AIO Operations
+@subsection Getting the Status of AIO Operations
+
+As already decsribes in the documentation of the functions in the last
+section it must be possible to get information about the status of a I/O
+request. When the operation is performed really asynchronous (as with
+@code{aio_read} and @code{aio_write} and with @code{aio_listio} when the
+mode is @code{LIO_NOWAIT}) one sometimes needs to know whether a
+specific request already terminated and if yes, what the result was..
+The following two function allow to get this kind of information.
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_error (const struct aiocb *@var{aiocbp})
+This function determines the error state of the request described by the
+@code{struct aiocb} variable pointed to by @var{aiocbp}. If the the
+request has not yet terminated the value returned is always
+@code{EINPROGRESS}. Once the request has terminated the value
+@code{aio_error} returns is either @math{0} if the request completed
+successfully or it returns the the value which would be stored in the
+@code{errno} variable if the request would have been done using
+@code{read}, @code{write}, or @code{fsync}.
+
+The function can return @code{ENOSYS} if it is not implemented. It
+could also return @code{EINVAL} if the @var{aiocbp} parameter does not
+refer to an asynchronous operation whose return status is not yet known.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_error64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
+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
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_error} and so
+transparently replaces the interface for small files on 32 bits
+machines.
+@end deftypefun
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun ssize_t aio_return (const struct aiocb *@var{aiocbp})
+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
+undefined.
+
+Once the request is finished this function can used used exactly once to
+retriece the return value. Following calls might lead to undefined
+behaviour. The return value itself is the value which would have been
+returned by the @code{read}, @code{write}, or @code{fsync} call.
+
+The function can return @code{ENOSYS} if it is not implemented. It
+could also return @code{EINVAL} if the @var{aiocbp} parameter does not
+refer to an asynchronous operation whose return status is not yet known.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_return64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_return64 (const struct aiocb64 *@var{aiocbp})
+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
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_return} and so
+transparently replaces the interface for small files on 32 bits
+machines.
+@end deftypefun
+
+@node Synchronizing AIO Operations
+@subsection Getting into a Consistent State
+
+When dealing with asynchronous operations it is sometimes necessary to
+get into a consistent state. This would mean for AIO that ones wants to
+know whether a certain request or a group of request were processed.
+This could be done by waiting for the notification sent by the system
+after the operation terminated but this sometimes would been a wasting
+resources (mainly computation time). Instead POSIX.1b defines two
+functions which will help with most kinds of consistency.
+
+The @code{aio_fsync} and @code{aio_fsync64} functions are only available
+if in @file{unistd.h} the symbol @code{_POSIX_SYNCHRONIZED_IO} is
+defined.
+
+@cindex synchronizing
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
+Calling this function forces all I/O operations operating queued at the
+time of the function call operating on the file desriptor
+@code{aiocbp->aio_fildes} into the synchronized I/O completion state
+(@pxref{Synchronizing I/O}). The @code{aio_fsync} function return
+immediately but the notification through the method described in
+@code{aiocbp->aio_sigevent} will happen only after all requests for this
+file descriptor terminated and the file is synchronized. This also
+means that requests for this very same file descriptor which are queued
+after the synchronization request are not effected.
+
+If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
+to @code{fdatasync}. Otherwise @var{op} should be @code{O_SYNC} and
+thee synchronization happens as with @code{fsync}.
+
+As long as the synchronization hasn't happened a call to
+@code{aio_error} with the reference to the object pointed to by
+@var{aiocbp} returns @code{EINPROGRESS}. Once the synchronizatio is
+done @code{aio_error} return @math{0} if the synchronization wasn
+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.
+
+The return value of this function is @math{0} if the request was
+successfully filed. Otherwise the return value is @math{-1} and
+@code{errno} is set to one of the following values:
+
+@table @code
+@item EAGAIN
+The request coulnd't be enqueued due to temporary lack of resources.
+@item EBADF
+The file descriptor @code{aiocbp->aio_fildes} is not valid or not open
+for writing.
+@item EINVAL
+The implementation does not support I/O synchronization or the @var{op}
+parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
+@item ENOSYS
+This function is not implemented.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_return64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
+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
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_fsync} and so
+transparently replaces the interface for small files on 32 bits
+machines.
+@end deftypefun
+
+Another method of synchronization is to until one or more requests of a
+specific set terminated. This could be achieved by the @code{aio_*}
+functions to notify the initiating process about the termination but in
+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
+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
+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})
+When calling this function the calling thread is suspended until at
+least one of the requests pointed to by the @var{nent} elements of the
+array @var{list} has completed. If any of the requests already has
+completed at the time @code{aio_suspend} is called the function returns
+immediately. Whether a request has terminated or not is done by
+comparing the error status of the request with @code{EINPROGRESS}. If
+an element of @var{list} is @code{NULL} the entry is simply ignored.
+
+If no request has finished the calling process is suspended. If
+@var{timeout} is @code{NULL} the process is not waked until a request
+finished. If @var{timeout} is not @code{NULL} the process remains
+suspended at as long as specified in @var{timeout}. In this case
+@code{aio_suspend} returns with an error.
+
+The return value of the function is @math{0} is one or more requests
+from the @var{list} have terminated. Otherwise the function returns
+@math{-1} and @code{errno} is set to one of the following values:
+
+@table @code
+@item EAGAIN
+None of the requests from the @var{list} completed in the time specified
+by @var{timeout}.
+@item EINTR
+A signal interrupted the @code{aio_suspend} function. This signal might
+also be sent by the AIO implementation while signalling the termination
+of one of the requests.
+@item ENOSYS
+The @code{aio_suspend} function is not implemented.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_suspend64} since the LFS interface
+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})
+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
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_suspend} and so
+transparently replaces the interface for small files on 32 bits
+machines.
+@end deftypefun
@node Cancel AIO Operations
@subsection Cancelation of AIO Operations
+When one or more requests are asynchronously processed it might be
+useful in some situations to cancel a selected operation, e.g., if it
+becomes obvious that the written data is not anymore accurate and would
+have to be overwritten soon. As an example assume an application, which
+writes data in files in a situation where new incoming data would have
+to be written in a file which will be updated by an enqueued request.
+The POSIX AIO implementation provides such a function but this function
+is not capable to force the cancelation of the request. It is up to the
+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})
+The @code{aio_cancel} function can be used to cancel one or more
+outstanding requests. If the @var{aiocbp} parameter is @code{NULL} the
+function tries to cancel all outstanding requests which would process
+the file descriptor @var{fildes} (i.e.,, whose @code{aio_fildes} member
+is @var{fildes}). If @var{aiocbp} is not @code{NULL} the very specific
+request pointed to by @var{aiocbp} is tried to be canceled.
+
+For requests which were successfully canceled the normal notification
+about the termination of the request should take place. I.e., depending
+on the @code{struct sigevent} object which controls this, nothing
+happens, a signal is sent or a thread is started. If the request cannot
+be canceled it terminates the usual way after performing te operation.
+
+After a request is successfully canceled a call to @code{aio_error} with
+a reference to this request as the parameter will return
+@code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
+If the request wasn't canceled and is still running the error status is
+still @code{EINPROGRESS}.
+
+The return value of the function is @code{AIO_CANCELED} if there were
+requests which haven't terminated and which successfully were canceled.
+If there is one or more request 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
+@var{aiocbp} is @code{NULL}) wasn't successfully canceled. If all
+requests already terminated at the time @code{aio_cancel} is called the
+return value is @code{AIO_ALLDONE}.
+
+If an error occurred during the execution of @code{aio_cancel} the
+function returns @math{-1} and sets @code{errno} to one of the following
+values.
+
+@table @code
+@item EBADF
+The file descriptor @var{fildes} is not valid.
+@item ENOSYS
+@code{aio_cancel} is not implemented.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_cancel64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb *@var{aiocbp})
+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
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_cancel} and so
+transparently replaces the interface for small files on 32 bits
+machines.
+@end deftypefun
+
+@node Configuration of AIO
+@subsection How to optimize the AIO implementation
+
+The POSIX standard does not specify how the AIO functions are
+implemented. They could be system calls but it is also possible to
+emulate them at userlevel.
+
+At least the available implementatio at the point of this writing is a
+userlevel implementation which uses threads for handling the enqueued
+requests. This implementation requires to make some decisions about
+limitations but hard limitations are something which better should be
+avoided the GNU C library implementation provides a mean to tune the AIO
+implementation individually for each use.
+
+@comment aio.h
+@comment GNU
+@deftp {Data Type} {struct aioinit}
+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}
+function.
+
+@table @code
+@item int aio_threads
+This member specifies the maximal number of threads which must be used
+at any one time.
+@item int aio_num
+This number provides an esitmate on the maximal number of simultaneously
+enqueued requests.
+@item int aio_locks
+@c What?
+@item int aio_usedba
+@c What?
+@item int aio_debug
+@c What?
+@item int aio_numusers
+@c What?
+@item int aio_reserved[2]
+@c What?
+@end table
+@end deftp
+
+@comment aio.h
+@comment GNU
+@deftypefun void aio_init (const struct aioinit *@var{init})
+This function must be called before any other AIO function. Calling it
+is completely voluntarily since it only is meant to help the AIO
+implementation to perform better.
+
+Before calling the @code{aio_init} function 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.
+@end deftypefun
@node Control Operations
@section Control Operations on Files
meaningful in other systems.
If the open fails, @code{fopen} returns a null pointer.
+
+When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is in fact @code{fopen64} since the LFS
+interface replaces transparently the old interface.
@end deftypefun
You can have multiple streams (or file descriptors) pointing to the same
Locks}.
@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
+This function is similar to @code{fopen} but the stream it returns a
+pointer for is opened using @code{open64}. Therefore this stream can be
+used even on files larger then @math{2^31} bytes on 32 bits machines.
+
+Please note that the return type is still @code{FILE *}. There is no
+special @code{FILE} type for the LFS interface.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fopen}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
@comment ISO
@deftypevr Macro int FOPEN_MAX
The value of this macro is an integer constant expression that
hard-coded. In the GNU C library, you can simply close the standard
streams and open new ones with @code{fopen}. But other systems lack
this ability, so using @code{freopen} is more portable.
+
+When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is in fact @code{freopen64} since the LFS
+interface replaces transparently the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+This function is similar to @code{freopen}. The only difference is that
+on 32 bits machine the stream returned is able to read beyond the
+@math{2^31} bytes limits imposed by the normal interface. It should be
+noted that the stream pointed to by @var{stream} need not be opened
+using @code{fopen64} or @code{freopen64} since its mode is not important
+for this function.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{freopen}
+and so transparently replaces the old interface.
@end deftypefun
The function is an extension defined in the Unix Single Specification
version 2.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{ftello64}. I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun off64_t ftello64 (FILE *@var{stream})
+This function is similar to @code{ftello} with the only difference that
+the return value is of type @code{off64_t}. This also requires that the
+stream @var{stream} was opened using either @code{fopen64},
+@code{freopen64}, or @code{tmpfile64} since otherwise the underlying
+file operations to position the file pointer beyond the @math{2^31}
+bytes limit might fail.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{ftello}
+and so transparently replaces the old interface.
@end deftypefun
@comment stdio.h
The function is an extension defined in the Unix Single Specification
version 2.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{fseeko64}. I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
+This function is similar to @code{fseeko} with the only difference that
+the @var{offset} parameter is of type @code{off64_t}. This also
+requires that the stream @var{stream} was opened using either
+@code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
+the underlying file operations to position the file pointer beyond the
+@math{2^31} bytes limit might fail.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fseeko}
+and so transparently replaces the old interface.
@end deftypefun
@strong{Portability Note:} In non-POSIX systems, @code{ftell},
In the GNU system, @code{fpos_t} is equivalent to @code{off_t} or
@code{long int}. In other systems, it might have a different internal
representation.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bits machine
+this type is in fact equivalent to @code{off64_t} since the LFS
+interface transparently replaced the old interface.
+@end deftp
+
+@comment stdio.h
+@comment Unix98
+@deftp {Data Type} fpos64_t
+This is the type of an object that can encode information about the
+file position of a stream, for use by the functions @code{fgetpos64} and
+@code{fsetpos64}.
+
+In the GNU system, @code{fpos64_t} is equivalent to @code{off64_t} or
+@code{long long int}. In other systems, it might have a different internal
+representation.
@end deftp
@comment stdio.h
@var{position}. If successful, @code{fgetpos} returns zero; otherwise
it returns a nonzero value and stores an implementation-defined positive
value in @code{errno}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system the function is in fact @code{fgetpos64}. I.e., the LFS
+interface transparently replaced the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
+This function is similar to @code{fgetpos} but the file position is
+returned in a variable of type @code{fpos64_t} to which @var{position}
+points.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fgetpos}
+and so transparently replaces the old interface.
@end deftypefun
@comment stdio.h
@comment ISO
-@deftypefun int fsetpos (FILE *@var{stream}, const fpos_t @var{position})
+@deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
This function sets the file position indicator for the stream @var{stream}
to the position @var{position}, which must have been set by a previous
call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
that were ``pushed back'' by the use of @code{ungetc}, and returns a value
of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores
an implementation-defined positive value in @code{errno}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system the function is in fact @code{fsetpos64}. I.e., the LFS
+interface transparently replaced the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
+This function is similar to @code{fsetpos} but the file position used
+for positioning is provided in a variable of type @code{fpos64_t} to
+which @var{position} points.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fsetpos}
+and so transparently replaces the old interface.
@end deftypefun
@node Stream Buffering