mirror of
https://sourceware.org/git/glibc.git
synced 2024-11-27 03:33:33 +08:00
Update.
1999-05-29 Ulrich Drepper <drepper@cygnus.com> * manual/filesys.texi: Extend (f)truncate documentation. * manual/llio.texi: Remove duplicate (f)truncate definition. 1999-05-29 Andreas Jaeger <aj@arthur.rhein-neckar.de> * manual/stdio.texi (Formatted Output Functions): Mention semantics of snprintf in glibc 2.0. Reported by Ben Pfaff <pfaffben@msu.edu>. 1999-05-29 Ulrich Drepper <drepper@cygnus.com> * include/features.h (__GLIBC_MINOR__): Bump to 2.
This commit is contained in:
Ulrich Drepper
parent
0a1752b85e
commit
fb97136391
15
ChangeLog
15
ChangeLog
@ -1,3 +1,18 @@
|
||||
1999-05-29 Ulrich Drepper <drepper@cygnus.com>
|
||||
|
||||
* manual/filesys.texi: Extend (f)truncate documentation.
|
||||
* manual/llio.texi: Remove duplicate (f)truncate definition.
|
||||
|
||||
1999-05-29 Andreas Jaeger <aj@arthur.rhein-neckar.de>
|
||||
|
||||
* manual/stdio.texi (Formatted Output Functions): Mention
|
||||
semantics of snprintf in glibc 2.0.
|
||||
Reported by Ben Pfaff <pfaffben@msu.edu>.
|
||||
|
||||
1999-05-29 Ulrich Drepper <drepper@cygnus.com>
|
||||
|
||||
* include/features.h (__GLIBC_MINOR__): Bump to 2.
|
||||
|
||||
1999-05-27 Ulrich Drepper <drepper@cygnus.com>
|
||||
|
||||
* math/libm-test.c: Adjust a few more deltas for the poor ARM
|
||||
|
||||
@ -2526,15 +2526,23 @@ Using these functions on anything other than a regular file gives
|
||||
@emph{undefined} results. On many systems, such a call will appear to
|
||||
succeed, without actually accomplishing anything.
|
||||
|
||||
@comment unistd.h
|
||||
@comment X/Open
|
||||
@deftypefun int truncate (const char *@var{filename}, off_t @var{length})
|
||||
|
||||
The @code{truncate} function changes the size of @var{filename} to
|
||||
@var{length}. If @var{length} is shorter than the previous length, data at
|
||||
the end will be lost.
|
||||
@var{length}. If @var{length} is shorter than the previous length, data
|
||||
at the end will be lost. The file must be writable by the user to
|
||||
perform this operation.
|
||||
|
||||
If @var{length} is longer, holes will be added to the end. However, some
|
||||
systems do not support this feature and will leave the file unchanged.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
|
||||
@code{truncate} function is in fact @code{truncate64} and the type
|
||||
@code{off_t} has 64 bits which makes it possible to handle files up to
|
||||
@math{2^63} bytes in length.
|
||||
|
||||
The return value is @math{0} for success, or @math{-1} for an error. In
|
||||
addition to the usual file name errors, the following errors may occur:
|
||||
|
||||
@ -2562,9 +2570,35 @@ The operation was interrupted by a signal.
|
||||
|
||||
@end deftypefun
|
||||
|
||||
@comment unistd.h
|
||||
@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 64 bits wide even on 32
|
||||
bits machines which allows to handle file with a size up to @math{2^63}
|
||||
bytes.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
|
||||
32 bits machine this function is actually available under the name
|
||||
@code{truncate} and so transparently replaces the 32 bits interface.
|
||||
@end deftypefun
|
||||
|
||||
@comment unistd.h
|
||||
@comment POSIX
|
||||
@deftypefun int ftruncate (int @var{fd}, off_t @var{length})
|
||||
|
||||
This is like @code{truncate}, but it works on a file descriptor @var{fd}.
|
||||
This is like @code{truncate}, but it works on a file descriptor @var{fd}
|
||||
for an opened file instead of a file name to identify the object. The
|
||||
file must be opened for writing to successfully carry out the operation.
|
||||
|
||||
The POSIX standard leaves it implementation defined what happens if the
|
||||
specified new @var{length} of the file is bigger than the original size.
|
||||
The @code{ftruncate} function might simply leave the file alone and do
|
||||
nothing or it can increase the size to the desired size. In this later
|
||||
case the extended area should be zero-filled. So using @code{ftruncate}
|
||||
is no reliable way to increase the file size but if it is possible it is
|
||||
probably the fastest way. The function also operates on POSIX shared
|
||||
memory segments if these are implemented by the system.
|
||||
|
||||
@code{ftruncate} is especially useful in combination with @code{mmap}.
|
||||
Since the mapped region must have a fixed size one cannot enlarge the
|
||||
@ -2572,6 +2606,11 @@ file by writing something beyond the last mapped page. Instead one has
|
||||
to enlarge the file itself and then remap the file with the new size.
|
||||
The example below shows how this works.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
|
||||
@code{ftruncate} function is in fact @code{ftruncate64} and the type
|
||||
@code{off_t} has 64 bits which makes it possible to handle files up to
|
||||
@math{2^63} bytes in length.
|
||||
|
||||
The return value is @math{0} for success, or @math{-1} for an error. The
|
||||
following errors may occur:
|
||||
|
||||
@ -2608,6 +2647,19 @@ The operation was interrupted by a signal.
|
||||
|
||||
@end deftypefun
|
||||
|
||||
@comment unistd.h
|
||||
@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 64 bits wide even on 32
|
||||
bits machines which allows to handle file with a size up to @math{2^63}
|
||||
bytes.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
|
||||
32 bits machine this function is actually available under the name
|
||||
@code{ftruncate} and so transparently replaces the 32 bits interface.
|
||||
@end deftypefun
|
||||
|
||||
As announced here is a little example how to use @code{ftruncate} in
|
||||
combination with @code{mmap}:
|
||||
|
||||
|
||||
103
manual/llio.texi
103
manual/llio.texi
@ -280,109 +280,6 @@ of trying to close its underlying file descriptor with @code{close}.
|
||||
This flushes any buffered output and updates the stream object to
|
||||
indicate that it is closed.
|
||||
|
||||
|
||||
@node Truncating Files
|
||||
@section Change the size of a file
|
||||
|
||||
In some situations it is useful to explicitly determine the size of a
|
||||
file. Since the 4.2BSD days there is a function to truncate a file to
|
||||
at most a given number of bytes and POSIX defines one additional
|
||||
function. The prototypes for these functions are in @file{unistd.h}.
|
||||
|
||||
@comment unistd.h
|
||||
@comment X/Open
|
||||
@deftypefun int truncate (const char *@var{name}, off_t @var{length})
|
||||
The @code{truncation} function truncates the file named by @var{name} to
|
||||
at most @var{length} bytes. I.e., if the file was larger before the
|
||||
extra bytes are stripped of. If the file was small or equal to
|
||||
@var{length} in size before nothing is done. The file must be writable
|
||||
by the user to perform this operation.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
|
||||
@code{truncate} function is in fact @code{truncate64} and the type
|
||||
@code{off_t} has 64 bits which makes it possible to handle files up to
|
||||
@math{2^63} bytes in length.
|
||||
|
||||
The return value is zero is everything went ok. Otherwise the return
|
||||
value is @math{-1} and the global variable @var{errno} is set to:
|
||||
@table @code
|
||||
@item EACCES
|
||||
The file is not accessible to the user.
|
||||
@item EINVAL
|
||||
The @var{length} value is illegal.
|
||||
@item EISDIR
|
||||
The object named by @var{name} is a directory.
|
||||
@item ENOENT
|
||||
The file named by @var{name} does not exist.
|
||||
@item ENOTDIR
|
||||
One part of the @var{name} is not a directory.
|
||||
@end table
|
||||
|
||||
This function was introduced in 4.2BSD but also was available in later
|
||||
@w{System V} systems. It is not added to POSIX since the authors felt
|
||||
it is only of marginally additional utility. See below.
|
||||
@end deftypefun
|
||||
|
||||
@comment unistd.h
|
||||
@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 64 bits wide even on 32
|
||||
bits machines which allows to handle file with a size up to @math{2^63}
|
||||
bytes.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
|
||||
32 bits machine this function is actually available under the name
|
||||
@code{truncate} and so transparently replaces the 32 bits interface.
|
||||
@end deftypefun
|
||||
|
||||
@comment unistd.h
|
||||
@comment POSIX
|
||||
@deftypefun int ftruncate (int @var{fd}, off_t @var{length})
|
||||
The @code{ftruncate} function is similar to the @code{truncate}
|
||||
function. The main difference is that it takes a descriptor for an
|
||||
opened file instead of a file name to identify the object. The file
|
||||
must be opened for writing to successfully carry out the operation.
|
||||
|
||||
The POSIX standard leaves it implementation defined what happens if the
|
||||
specified new @var{length} of the file is bigger than the original size.
|
||||
The @code{ftruncate} function might simply leave the file alone and do
|
||||
nothing or it can increase the size to the desired size. In this later
|
||||
case the extended area should be zero-filled. So using @code{ftruncate}
|
||||
is no reliable way to increase the file size but if it is possible it is
|
||||
probably the fastest way. The function also operates on POSIX shared
|
||||
memory segments if these are implemented by the system.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
|
||||
@code{ftruncate} function is in fact @code{ftruncate64} and the type
|
||||
@code{off_t} has 64 bits which makes it possible to handle files up to
|
||||
@math{2^63} bytes in length.
|
||||
|
||||
On success the function returns zero. Otherwise it returns @math{-1}
|
||||
and set @var{errno} to one of these values:
|
||||
@table @code
|
||||
@item EBADF
|
||||
@var{fd} is no valid file descriptor or is not opened for writing.
|
||||
@item EINVAL
|
||||
The object referred to by @var{fd} does not permit this operation.
|
||||
@item EROFS
|
||||
The file is on a read-only file system.
|
||||
@end table
|
||||
@end deftypefun
|
||||
|
||||
@comment unistd.h
|
||||
@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 64 bits wide even on 32
|
||||
bits machines which allows to handle file with a size up to @math{2^63}
|
||||
bytes.
|
||||
|
||||
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
|
||||
32 bits machine this function is actually available under the name
|
||||
@code{ftruncate} and so transparently replaces the 32 bits interface.
|
||||
@end deftypefun
|
||||
|
||||
@node I/O Primitives
|
||||
@section Input and Output Primitives
|
||||
|
||||
|
||||
@ -1616,6 +1616,12 @@ make_message (char *name, char *value)
|
||||
@end smallexample
|
||||
|
||||
In practice, it is often easier just to use @code{asprintf}, below.
|
||||
|
||||
@strong{Attention:} In the GNU C library version 2.0 the return value
|
||||
is the number of characters stored, not including the terminating null.
|
||||
If this value equals @code{@var{size} - 1}, then there was not enough
|
||||
space in @var{s} for all the output. This change was neccessary with
|
||||
the adoption of snprintf by ISO C9x.
|
||||
@end deftypefun
|
||||
|
||||
@node Dynamic Output
|
||||
|
||||
Loading…
Reference in New Issue
Block a user