diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/arith.texi | 4 | ||||
| -rw-r--r-- | manual/filesys.texi | 285 | ||||
| -rw-r--r-- | manual/llio.texi | 669 | ||||
| -rw-r--r-- | manual/stdio.texi | 126 | ||||
| -rw-r--r-- | manual/time.texi | 64 |
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. |