diff options
| -rw-r--r-- | ChangeLog | 15 | ||||
| -rw-r--r-- | manual/filesys.texi | 58 | ||||
| -rw-r--r-- | manual/llio.texi | 103 | ||||
| -rw-r--r-- | manual/stdio.texi | 6 |
4 files changed, 76 insertions, 106 deletions
@@ -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 diff --git a/manual/filesys.texi b/manual/filesys.texi index 5cd7db9..21d27f2 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -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}: diff --git a/manual/llio.texi b/manual/llio.texi index 47f79a7..7fe382a 100644 --- a/manual/llio.texi +++ b/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 diff --git a/manual/stdio.texi b/manual/stdio.texi index 3449a51..9cf4c9f 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -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 |