diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | manual/llio.texi | 359 | ||||
| -rw-r--r-- | manual/sysinfo.texi | 2 |
3 files changed, 361 insertions, 4 deletions
@@ -2,7 +2,9 @@ * libc.map: Don't export argp's fmtstream handling functions. - * manual/sysinfo.h: Document fstab and mtab handling functions. + * manual/sysinfo.texi: Document fstab and mtab handling functions. + * manual/llio.texi: Document more LFS functions and start documenting + the AIO functions. 1998-06-03 03:09 Geoff Keating <geoffk@ozemail.com.au> diff --git a/manual/llio.texi b/manual/llio.texi index 9895615..56f90b6 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -43,6 +43,7 @@ directly.) * Waiting for I/O:: How to check for input or output on multiple file descriptors. * Synchronizing I/O:: Making sure all I/O actions completed. +* Asynchronous I/O:: Perform I/O in parallel. * Control Operations:: Various other operations on file descriptors. * Duplicating Descriptors:: Fcntl commands for duplicating @@ -138,6 +139,13 @@ or @code{O_CREAT} is set and the file does not already exist. @c !!! umask +If on a 32 bits machine the sources are translated with +@code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file +descriptor opened in the large file mode which enables the file handling +functions to use files up to @math{2^63} in size and offset from +@math{-2^63} to @math{2^63}. This happens transparently for the user +since all of the lowlevel file handling functions are equally replaced. + This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{open} is @@ -151,6 +159,23 @@ and @code{freopen} functions, that create streams. @end deftypefun @comment fcntl.h +@comment LFS +@deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +This function is similar to @code{open}. It returns a file descriptor +which can be used to access the file named by @var{filename}. The only +the difference is that on 32 bits systems the file is opened in the +large file mode. I.e., file length and file offsets can exceed 31 bits. + +To use this file descriptor one must not use the normal operations but +instead the counterparts named @code{*64}, e.g., @code{read64}. + +When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this +function is actually available under the name @code{open}. I.e., the +new, extended API using 64 bit file sizes and offsets transparently +replaces the old API. +@end deftypefun + +@comment fcntl.h @comment POSIX.1 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode}) This function is obsolete. The call: @@ -165,6 +190,30 @@ is equivalent to: @smallexample open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode}) @end smallexample + +If on a 32 bits machine the sources are translated with +@code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file +descriptor opened in the large file mode which enables the file handling +functions to use files up to @math{2^63} in size and offset from +@math{-2^63} to @math{2^63}. This happens transparently for the user +since all of the lowlevel file handling functions are equally replaced. +@end deftypefn + +@comment fcntl.h +@comment LFS +@deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode}) +This function is similar to @code{creat}. It returns a file descriptor +which can be used to access the file named by @var{filename}. The only +the difference is that on 32 bits systems the file is opened in the +large file mode. I.e., file length and file offsets can exceed 31 bits. + +To use this file descriptor one must not use the normal operations but +instead the counterparts named @code{*64}, e.g., @code{read64}. + +When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this +function is actually available under the name @code{open}. I.e., the +new, extended API using 64 bit file sizes and offsets transparently +replaces the old API. @end deftypefn @comment unistd.h @@ -217,6 +266,12 @@ When the file is accessed by NFS, these errors from @code{write} can sometimes not be detected until @code{close}. @xref{I/O Primitives}, for details on their meaning. @end table + +Please note that there is @emph{no} separate @code{close64} function. +This is not necessary since this function does not determine nor depend +on the more of the file. The kernel which performs the @code{close} +operation knows for which mode the descriptor is used and can handle +this situation. @end deftypefun To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead @@ -235,13 +290,18 @@ function. The prototypes for these functions are in @file{unistd.h}. @comment unistd.h @comment X/Open -@deftypefun int truncate (const char *@var{name}, size_t @var{length}) +@deftypefun int truncate (const char *@var{name}, off_t @var{length}) The @code{truncation} function truncates the file named by @var{name} to at most @var{length} bytes. I.e., if the file was larger before the extra bytes are stripped of. If the file was small or equal to @var{length} in size before nothing is done. The file must be writable by the user to perform this operation. +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{truncate} function is in fact @code{truncate64} and the type +@code{off_t} has 64 bits which makes it possible to handle files up to +@math{2^63} bytes. + The return value is zero is everything went ok. Otherwise the return value is @math{-1} and the global variable @var{errno} is set to: @table @code @@ -263,8 +323,21 @@ it is only of marginally additional utility. See below. @end deftypefun @comment unistd.h +@comment LFS +@deftypefun int truncate64 (const char *@var{name}, off64_t @var{length}) +This function is similar to the @code{truncate} function. The +difference is that the @var{length} argument is even on 32 bits machines +64 bits wide which allows to handle file with a size up to @math{2^63} +bytes. + +When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a +32 bits machine this function is actually available under the name +@code{truncate} and so transparently replaces the 32 bits interface. +@end deftypefun + +@comment unistd.h @comment POSIX -@deftypefun int ftruncate (int @var{fd}, size_t @var{length}) +@deftypefun int ftruncate (int @var{fd}, off_t @var{length}) The @code{ftruncate} function is similar to the @code{truncate} function. The main difference is that it takes a descriptor for an opened file instead of a file name to identify the object. The file @@ -279,6 +352,11 @@ is no reliable way to increase the file size but if it is possible it is probably the fastest way. The function also operates on POSIX shared memory segments if these are implemented by the system. +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{ftruncate} function is in fact @code{ftruncate64} and the type +@code{off_t} has 64 bits which makes it possible to handle files up to +@math{2^63} bytes. + On success the function returns zero. Otherwise it returns @math{-1} and set @var{errno} to one of these values: @table @code @@ -291,6 +369,19 @@ The file is on a read-only file system. @end table @end deftypefun +@comment unistd.h +@comment LFS +@deftypefun int ftruncate64 (int @var{id}, off64_t @var{length}) +This function is similar to the @code{ftruncate} function. The +difference is that the @var{length} argument is even on 32 bits machines +64 bits wide which allows to handle file with a size up to @math{2^63} +bytes. + +When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a +32 bits machine this function is actually available under the name +@code{ftruncate} and so transparently replaces the 32 bits interface. +@end deftypefun + @node I/O Primitives @section Input and Output Primitives @@ -382,6 +473,11 @@ orphaned. @xref{Job Control}, for more information about job control, and @ref{Signal Handling}, for information about signals. @end table +Please note that there is no function named @code{read64}. This is not +necessary since this function does not directly modify or handle the +possibly wide file offset. Since the kernel handles this state +internally the @code{read} function can be used for all cases. + This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{read} is @@ -407,6 +503,11 @@ is not read from the current position of the file descriptor position @var{offset}. The position of the file descriptor itself is not effected by the operation. The value is the same as before the call. +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{pread} function is in fact @code{pread64} and the type +@code{off_t} has 64 bits which makes it possible to handle files up to +@math{2^63} bytes. + The return value of @code{pread} describes the number of bytes read. In the error case it returns @math{-1} like @code{read} does and the error codes are also the same. Only there are a few more error codes: @@ -423,6 +524,22 @@ The function is an extension defined in the Unix Single Specification version 2. @end deftypefun +@comment unistd.h +@comment LFS +@deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) +This function is similar to the @code{pread} function. The difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t} which makes it possible on 32 bits machines to address +files larger then @math{2^31} bytes and up to @math{2^63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a +32 bits machine this function is actually available under the name +@code{pread} and so transparently replaces the 32 bits interface. +@end deftypefun + @cindex writing to a file descriptor @comment unistd.h @comment POSIX.1 @@ -512,6 +629,11 @@ macro @code{TEMP_FAILURE_RETRY}, as follows: nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count)); @end smallexample +Please note that there is no function named @code{write64}. This is not +necessary since this function does not directly modify or handle the +possibly wide file offset. Since the kernel handles this state +internally the @code{write} function can be used for all cases. + This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{write} is @@ -537,6 +659,11 @@ is not written to the current position of the file descriptor position @var{offset}. The position of the file descriptor itself is not effected by the operation. The value is the same as before the call. +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{pwrite} function is in fact @code{pwrite64} and the type +@code{off_t} has 64 bits which makes it possible to handle files up to +@math{2^63} bytes. + The return value of @code{pwrite} describes the number of written bytes. In the error case it returns @math{-1} like @code{write} does and the error codes are also the same. Only there are a few more error codes: @@ -553,6 +680,22 @@ The function is an extension defined in the Unix Single Specification version 2. @end deftypefun +@comment unistd.h +@comment LFS +@deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) +This function is similar to the @code{pwrite} function. The difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t} which makes it possible on 32 bits machines to address +files larger then @math{2^31} bytes and up to @math{2^63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a +32 bits machine this function is actually available under the name +@code{pwrite} and so transparently replaces the 32 bits interface. +@end deftypefun + @node File Position Primitive @section Setting the File Position of a Descriptor @@ -638,6 +781,11 @@ only for pipes and FIFOs, but in the GNU system, you always get @code{ESPIPE} if the object is not seekable.) @end table +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{lseek} function is in fact @code{lseek64} and the type +@code{off_t} has 64 bits which makes it possible to handle files up to +@math{2^63} bytes. + This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{lseek} is @@ -652,6 +800,22 @@ The @code{lseek} function is the underlying primitive for the descriptors. @end deftypefun +@comment unistd.h +@comment LFS +@deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence}) +This function is similar to the @code{lseek} function. The difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t} which makes it possible on 32 bits machines to address +files larger then @math{2^31} bytes and up to @math{2^63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the sources are defined using @code{_FILE_OFFSET_BITS == 64} on a +32 bits machine this function is actually available under the name +@code{lseek} and so transparently replaces the 32 bits interface. +@end deftypefun + You can have multiple descriptors for the same file if you open the file more than once, or if you duplicate a descriptor with @code{dup}. Descriptors that come from separate calls to @code{open} have independent @@ -706,6 +870,15 @@ 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}. @end deftp +@comment sys/types.h +@comment LFS +@deftp {Data Type} off64_t +This type is used similar to @code{off_t}. The difference is that even +on 32 bits machines, where the @code{off_t} type would 32 bits, +@code{off64_t} has 64 bits and so is able to address files up to +@math{2^63} bytes in length. +@end deftp + These aliases for the @samp{SEEK_@dots{}} constants exist for the sake of compatibility with older BSD systems. They are defined in two different header files: @file{fcntl.h} and @file{sys/file.h}. @@ -1211,6 +1384,188 @@ No synchronization is possible since the system does not implement this. @end deftypefun +@node Asynchronous I/O +@section Perform I/O Operations in Parallel + +The POSIX.1b standard defines a new set of I/O operations which can +reduce the time an application spends waiting at I/O significantly. The +new functions allow a program to initiate one or more I/O operations and +then immediately resume the normal word while the I/O operations are +executed in parallel. + +These functions are part of the library with realtime functions named +@file{librt}. They are not actually part of the @file{libc} binary. +The implementation of these functions can be done using support in the +kernel )if available) or using a implementation based on threads at +userlevel. In the later case it might be necessary to link applications +linked with @file{librt} also with the thread library @file{libthread}. + +All AIO operations operate on files which previously were opened. There +might be arbitrary many operations for one file running. The +asynchronous I/O operations are controlled using a data structure named +@code{struct aiocb} (@dfn{AIO control block}). It is defined in +@file{aio.h} as follows. + +@comment aio.h +@comment POSIX.1b +@deftp {Data Type} {struct aiocb} +The POSIX.1b standard mandates that the @code{struct aiocb} structure +contains at least the members described in the following table. There +might be more elements which are used by the implementation but +depending on these elements is not portable and is highly deprecated. + +@table @code +@item int aio_fildes +This element specifies the file descriptor which is used for the +operation. It must be a legal descriptor since otherwise the operation +fails for obvious reasons. + +The device on which the file is opened must allow the seek operation. +I.e., it is not possible to use any of the AIO operations on devices +like terminals where an @code{lseek} call would lead to an error. + +@item off_t aio_offset +This element specified at which offset in the file the operation (input +or output) is performed. Since the operation are carried in arbitrary +order and more than one operation for one file descriptor can be +started, one cannot expect a current read/write position of the file +descriptor. + +@item volatile void *aio_buf +This is a pointer to the buffer with the data to be written or the place +where the ead data is stored. + +@item size_t aio_nbytes +This element specifies the length of the buffer pointed to by @code{aio_buf}. + +@item int aio_reqprio +If for the platform @code{_POSIX_PRIORITIZED_IO} and +@code{_POSIX_PRIORITY_SCHEDULING} is defined the AIO requests are +processed based on the current scheduling priority. The +@code{aio_reqprio} element can then be used to lower the priority of the +AIO operation. + +@item struct sigevent aio_sigevent +This element specifies how the calling process is notified once the +operation terminated. If the @code{sigev_notify} element is +@code{SIGEV_NONE} no notification is send. If it is @code{SIGEV_SIGNAL} +the signal determined by @code{sigev_signo} is send. Otherwise +@code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread +which starts executing the function pointeed to by +@code{sigev_notify_function}. + +@item int aio_lio_opcode +This element is only used by the @code{lio_listio} and +@code{[lio_listio64} functions. Since these functions allow to start an +arbitrary number of operations at once and since each operationcan be +input or output (or nothing) the information must be stored in the +control block. The possible values are: + +@vtable @code +@item LIO_READ +Start a read operation. Read from the file at position +@code{aio_offset} and store the next @code{aio_nbytes} bytes in the +buffer pointed to by @code{aio_buf}. + +@item LIO_WRITE +Start a write operation. Write @code{aio_nbytes} bytes starting at +@code{aio_buf} into the file starting at position @code{aio_offset}. + +@item LIO_NOP +Do nothing for this control block. This value is useful sometimes when +an array of @code{struct aiocb} values contains holes, i.e., some of the +values must not be handled allthough the whole array is presented to the +@code{lio_listio} function. +@end vtable +@end table +@end deftp + +@menu +* Asynchronous Reads:: Asynchronous Read Operations. +* Cancel AIO Operations:: Cancelation of AIO Operations. +@end menu + +@node Asynchronous Reads +@subsection Asynchronous Read Operations + +@comment aio.h +@comment POSIX.1b +@deftypefun int aio_read (struct aiocb *@var{aiocbp}) +This function initiates an asynchronous read operation. The function +call immedaitely returns after the operation was enqueued or if before +this happens an error was encoutered. + +The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at +@code{aiocbp->aio_buf} are written to the file for which +@code{aiocbp->aio_fildes} is an descriptor, starting at the absolute +position @code{aiocbp->aio_offset} in the file. + +If prioritized I/O is supported by the platform the +@code{aiocbp->aio_reqprio} value is used to adjust the priority before +the request is actually enqueued. + +The calling process is notified about the termination of the read +request according to the @code{aiocbp->aio_sigevent} value. + +When @code{aio_read} returns the return value is zero if no error +occurred that can be found before the process is enqueued. If such an +earlier error is found the function returns @code{-1} and sets +@code{errno} to one of the following values. + +@table @code +@item EAGAIN +The request was not enqueued due to (temporarily) exceeded resource +limitations. +@item ENOSYS +The @code{aio_read} function is not implemented. +@item EBADF +The @code{aiocbp->aio_fildes} descriptor is not valid. This condition +need not be recognized before enqueueing the request and so this error +might also be signaled asynchrously. +@item EINVAL +The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is +invalid. This condition need not be recognized before enqueueing the +request and so this error might also be signaled asynchrously. +@end table + +In the case @code{aio_read} return zero the current status of the +request can be queried using @code{aio_error} and @code{aio_return} +questions. As long as the value returned by @code{aio_error} is +@code{EINPROGRESS} the operation has not yet completed. If +@code{aio_error} returns zero the operation successfully terminated, +otherwise the value is to be interpreted as an error code. If the +function terminated the result of the operation can be get using a call +to @code{aio_return}. The returned value is the same as an equivalent +call to @code{read} would have returned. Possible error code returned +by @code{aio_error} are: + +@table @code +@item EBADF +The @code{aiocbp->aio_fildes} descriptor is not valid. +@item ECANCELED +The operation was canceled before the operation was finished +(@pxref{Cancel AIO Operations}) +@item EINVAL +The @code{aiocbp->aio_offset} value is invalid. +@end table +@end deftypefun + +@comment aio.h +@comment POSIX.1b +@deftypefun int aio_read64 (struct aiocb *@var{aiocbp}) +This function is similar to the @code{aio_read} function. The only +difference is that only @w{32 bits} machines the file descriptor should +be opened in the large file mode. Internally @code{aio_read64} uses +functionality equivalent to @code{lseek64} to position the file +descriptor correctly for the reading, as opposed to @code{lseek} +funcationality used in @code{aio_read}. +@end deftypefun + + +@node Cancel AIO Operations +@subsection Cancelation of AIO Operations + + @node Control Operations @section Control Operations on Files diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi index cb9b954..993cbda 100644 --- a/manual/sysinfo.texi +++ b/manual/sysinfo.texi @@ -481,7 +481,7 @@ This function takes for the @var{stream} parameter a file handle which previously was returned from the @code{setmntent} call. @code{endmntent} closes the stream and frees all resources. -The return value is @code[1} unless an error occurred in which case it +The return value is @code{1} unless an error occurred in which case it is @code{0}. @end deftypefun |