Update.

1998-06-12 23:34  Ulrich Drepper  <drepper@cygnus.com>

	* manual/arith.texi: Fix problem with @math and texinfo.tex.

	* manual/filesys.texi: Document LFS functions.
	* manual/llio.texi: Likewise.
	* manual/stdio.texi: Likewise.
	* manual/time.texi: Likewise.

	* manual/llio.texi: Document AIO functions.

	* resource/sys/resource.h: Mark second argument of setrlimit as const.
	* sysdeps/generic/setrlimit.c: Likewise.
	* sysdeps/generic/setrlimit64.c: Likewise.
	* sysdeps/mach/hurd/setrlimit.c: Likewise.
	* sysdeps/unix/sysv/setrlimit.c: Likewise.

5 files changed, 1109 insertions, 39 deletions

diff --git a/manual/arith.texi b/manual/arith.texi
index 23d3aaabdd..57b3ac9329 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -836,8 +836,8 @@ are NaN, one of the values is returned.
 @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
 @cindex butterfly
 The name of the function @code{fma} means floating-point multiply-add.
-I.e., the operation performed is @math{(@var{x} @mul{} @var{y}) +
-@var{z}}.  The speciality of this function is that the intermediate
+I.e., the operation performed is @math{(@var{x} @mul{} @var{y}) + @var{z}}.
+The speciality of this function is that the intermediate
 result is not rounded and the addition is performed with the full
 precision of the multiplcation.
 
diff --git a/manual/filesys.texi b/manual/filesys.texi
index d9f4d5086a..ddb028624d 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -577,6 +577,8 @@ required definitions can be found in the @file{ftw.h} header.
 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
@@ -592,12 +594,7 @@ for the file named by the first parameter.
 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
@@ -617,9 +614,32 @@ file does not exist.  The situation for @code{nftw} is different.
 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
@@ -643,8 +663,31 @@ not exist.
 
 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
@@ -713,6 +756,23 @@ function calls returned @math{0} and all actions performed by 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
@@ -731,7 +791,7 @@ The second difference is that @code{nftw} takes an additional fourth
 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
@@ -752,7 +812,7 @@ If this option is given the function visits first all files and
 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
@@ -760,6 +820,23 @@ all callback function call return values are also @math{0}.  For
 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
 
 
@@ -1312,7 +1389,7 @@ This is the fractional part of the time of last modification to the
 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.
 
@@ -1346,6 +1423,88 @@ integer types that you know and love.)  These typedef names are defined
 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
@@ -1360,6 +1519,20 @@ GNU system, this is equivalent to @code{unsigned int}.
 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
@@ -1376,6 +1549,27 @@ This is an arithmetic data type used to represent file link counts.
 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
 
@@ -1404,6 +1598,23 @@ are defined for this function:
 @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
@@ -1421,6 +1632,24 @@ on failure.  The following @code{errno} error conditions are defined for
 @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
@@ -1430,6 +1659,23 @@ The @code{lstat} function is like @code{stat}, except that it does not
 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
@@ -2328,6 +2574,25 @@ some other @w{ISO C} systems the file may fail to be deleted if the program
 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
diff --git a/manual/llio.texi b/manual/llio.texi
index 56f90b6f86..6180a060fb 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -159,7 +159,7 @@ and @code{freopen} functions, that create streams.
 @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
@@ -200,7 +200,7 @@ since all of the lowlevel file handling functions are equally replaced.
 @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
@@ -323,7 +323,7 @@ it is only of marginally additional utility.  See below.
 @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
@@ -370,7 +370,7 @@ The file is on a read-only file system.
 @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
@@ -525,7 +525,7 @@ version 2.
 @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
@@ -681,7 +681,7 @@ version 2.
 @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
@@ -801,7 +801,7 @@ descriptors.
 @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
@@ -868,15 +868,21 @@ character.
 @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
@@ -1391,7 +1397,8 @@ 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.
+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.
@@ -1478,27 +1485,97 @@ values must not be handled allthough the whole array is presented to the
 @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
@@ -1509,7 +1586,7 @@ 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
+early error is found the function returns @math{-1} and sets
 @code{errno} to one of the following values.
 
 @table @code
@@ -1528,7 +1605,7 @@ 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
+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
@@ -1548,23 +1625,569 @@ The operation was canceled before the operation was finished
 @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
diff --git a/manual/stdio.texi b/manual/stdio.texi
index 1108b0c1fe..4d054c02ef 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -209,6 +209,10 @@ Any other characters in @var{opentype} are simply ignored.  They may be
 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
@@ -221,6 +225,21 @@ file locking facilities to avoid simultaneous access.  @xref{File
 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
@@ -254,6 +273,25 @@ programs in which use of a standard stream for certain purposes is
 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
 
 
@@ -3098,6 +3136,25 @@ the return value is the current file position.
 
 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
@@ -3136,6 +3193,25 @@ The functionality and return value is the same as for @code{fseek}.
 
 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},
@@ -3272,6 +3348,22 @@ file position of a stream, for use by the functions @code{fgetpos} and
 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
@@ -3282,11 +3374,27 @@ stream @var{stream} in the @code{fpos_t} object pointed to by
 @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}
@@ -3294,6 +3402,22 @@ clears the end-of-file indicator on the stream, discards any characters
 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
diff --git a/manual/time.texi b/manual/time.texi
index 5da12c4513..a4d1f779d7 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -1645,11 +1645,28 @@ and store them in @code{*@var{rlp}}.
 
 The return value is @code{0} on success and @code{-1} on failure.  The
 only possible @code{errno} error condition is @code{EFAULT}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{getrlimit64}.  I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment Unix98
+@deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp})
+This function is similar to the @code{getrlimit} but its second
+parameter is a pointer to a variable of type @code{struct rlimit64}
+which allows this function to read values which wouldn't fit in the
+member of a @code{struct rlimit}.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{getrlimit}
+and so transparently replaces the old interface.
 @end deftypefun
 
 @comment sys/resource.h
 @comment BSD
-@deftypefun int setrlimit (int @var{resource}, struct rlimit *@var{rlp})
+@deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp})
 Store the current value and the maximum value of resource @var{resource}
 in @code{*@var{rlp}}.
 
@@ -1661,6 +1678,23 @@ following @code{errno} error condition is possible:
 You tried to change the maximum permissible limit value,
 but you don't have privileges to do so.
 @end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits system this function is in fact @code{setrlimit64}.  I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment Unix98
+@deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp})
+This function is similar to the @code{setrlimit} but its second
+parameter is a pointer to a variable of type @code{struct rlimit64}
+which allows this function to set values which wouldn't fit in the
+member of a @code{struct rlimit}.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{setrlimit}
+and so transparently replaces the old interface.
 @end deftypefun
 
 @comment sys/resource.h
@@ -1670,12 +1704,12 @@ This structure is used with @code{getrlimit} to receive limit values,
 and with @code{setrlimit} to specify limit values.  It has two fields:
 
 @table @code
-@item rlim_cur
+@item rlim_t rlim_cur
 The current value of the limit in question.
 This is also called the ``soft limit''.
 @cindex soft limit
 
-@item rlim_max
+@item rlim_t rlim_max
 The maximum permissible value of the limit in question.  You cannot set
 the current value of the limit to a larger number than this maximum.
 Only the super user can change the maximum permissible value.
@@ -1687,6 +1721,30 @@ In @code{getrlimit}, the structure is an output; it receives the current
 values.  In @code{setrlimit}, it specifies the new values.
 @end deftp
 
+For the LFS functions a similar type is defined in @file{sys/resource.h}.
+
+@comment sys/resource.h
+@comment Unix98
+@deftp {Data Type} {struct rlimit64}
+This structure is used with @code{getrlimit64} to receive limit values,
+and with @code{setrlimit64} to specify limit values.  It has two fields:
+
+@table @code
+@item rlim64_t rlim_cur
+The current value of the limit in question.
+This is also called the ``soft limit''.
+
+@item rlim64_t rlim_max
+The maximum permissible value of the limit in question.  You cannot set
+the current value of the limit to a larger number than this maximum.
+Only the super user can change the maximum permissible value.
+This is also called the ``hard limit''.
+@end table
+
+In @code{getrlimit64}, the structure is an output; it receives the current
+values.  In @code{setrlimit64}, it specifies the new values.
+@end deftp
+
 Here is a list of resources that you can specify a limit for.
 Those that are sizes are measured in bytes.