AuroraMiddleware/glibc
1
0
Fork 0
mirror of https://sourceware.org/git/glibc.git synced 2024-11-21 12:30:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update.

Browse Source 
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.
This commit is contained in:
Ulrich Drepper 1998-06-13 00:49:55 +00:00
parent ecdc196cac
commit a3a4a74e6a
12 changed files with 1141 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
ChangeLog
View File

@ -1,3 +1,20 @@
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.
1998-06-11 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/generic/getenv.c: Fix last change.

8
configure vendored
View File

@ -1119,14 +1119,14 @@ while test $# -gt 0; do
done
# Add the default directories.
default_sysnames=sysdeps/generic
if test "$elf" = yes; then
sysnames="$names sysdeps/generic/elf sysdeps/generic"
else
sysnames="$names sysdeps/generic"
default_sysnames="sysdeps/generic/elf $default_sysnames"
fi
sysnames="$names $default_sysnames"
# The other names were emitted during the scan.
echo "$ac_t""sysdeps/generic" 1>&6
echo "$ac_t""$default_sysnames" 1>&6
### Locate tools.

4
manual/arith.texi
View File

@ -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.

285
manual/filesys.texi
View File

@ -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

669
manual/llio.texi
View File

@ -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

126
manual/stdio.texi
View File

@ -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
@ -220,6 +224,21 @@ programs (which can easily happen). It may be advantageous to use the
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
@ -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

64
manual/time.texi
View File

@ -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.

6
resource/sys/resource.h
View File

@ -52,11 +52,11 @@ extern int getrlimit64 __P ((enum __rlimit_resource __resource,
Return 0 if successful, -1 if not (and sets errno). */
#ifndef __USE_FILE_OFFSET64
extern int setrlimit __P ((enum __rlimit_resource __resource,
struct rlimit *__rlimits));
__const struct rlimit *__rlimits));
#else
# ifdef __REDIRECT
extern int __REDIRECT (setrlimit, __P ((enum __rlimit_resource __resource,
struct rlimit *__rlimits)),
__const struct rlimit *__rlimits)),
setrlimit64);
# else
# define setrlimit setrlimit64
@ -64,7 +64,7 @@ extern int __REDIRECT (setrlimit, __P ((enum __rlimit_resource __resource,
#endif
#ifdef __USE_LARGEFILE64
extern int setrlimit64 __P ((enum __rlimit_resource __resource,
struct rlimit64 *__rlimits));
__const struct rlimit64 *__rlimits));
#endif
/* Return resource usage information on process indicated by WHO

4
sysdeps/generic/setrlimit.c
View File

@ -1,4 +1,4 @@
/* Copyright (C) 1991, 1995, 1996, 1997 Free Software Foundation, Inc.
/* Copyright (C) 1991, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
This file is part of the GNU C Library.
The GNU C Library is free software; you can redistribute it and/or
@ -26,7 +26,7 @@
int
setrlimit (resource, rlimits)
enum __rlimit_resource resource;
struct rlimit *rlimits;
const struct rlimit *rlimits;
{
__set_errno (ENOSYS);
return -1;

4
sysdeps/generic/setrlimit64.c
View File

@ -1,4 +1,4 @@
/* Copyright (C) 1991, 1995, 1996, 1997 Free Software Foundation, Inc.
/* Copyright (C) 1991, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
This file is part of the GNU C Library.
The GNU C Library is free software; you can redistribute it and/or
@ -26,7 +26,7 @@
int
setrlimit64 (resource, rlimits)
enum __rlimit_resource resource;
struct rlimit64 *rlimits;
const struct rlimit64 *rlimits;
{
struct rlimit rlimits32;

4
sysdeps/mach/hurd/setrlimit.c
View File

@ -1,4 +1,4 @@
/* Copyright (C) 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
/* Copyright (C) 1991, 92, 93, 94, 97, 98 Free Software Foundation, Inc.
This file is part of the GNU C Library.
The GNU C Library is free software; you can redistribute it and/or
@ -29,7 +29,7 @@
int
setrlimit (resource, rlimits)
enum __rlimit_resource resource;
struct rlimit *rlimits;
const struct rlimit *rlimits;
{
struct rlimit lim;

4
sysdeps/unix/sysv/setrlimit.c
View File

@ -1,5 +1,5 @@
/* setrlimit function for systems with ulimit system call (SYSV).
Copyright (C) 1991, 1992, 1996, 1997 Free Software Foundation, Inc.
Copyright (C) 1991, 1992, 1996, 1997, 1998 Free Software Foundation, Inc.
This file is part of the GNU C Library.
The GNU C Library is free software; you can redistribute it and/or
@ -29,7 +29,7 @@
int
setrlimit (resource, rlimits)
enum __rlimit_resource resource;
struct rlimit *rlimits;
const struct rlimit *rlimits;
{
if (rlimits == NULL)
{