+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
@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:
@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
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:
@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}:
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
@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
projects / platform / upstream / glibc.git / commitdiff