summaryrefslogtreecommitdiff
path: root/manual/stdio.texi
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1997-09-30 17:10:40 +0000
committerUlrich Drepper <drepper@redhat.com>1997-09-30 17:10:40 +0000
commita5a0310d8e9d7176bb17e91c916272006a871016 (patch)
treeb922b764878596e6ee42ae84cc315ecaaac00505 /manual/stdio.texi
parenta2b08ee54130cf3a74655856e6ca6c29874a9df2 (diff)
downloadglibc-a5a0310d8e9d7176bb17e91c916272006a871016.tar.gz
Update.
1997-09-30 18:03 Ulrich Drepper <drepper@cygnus.com> * Makerules: Undo last change. * csu/Makefile: Define before-compile at the right place. * aclocal.m4: Remove a.out file created by assembler test. * set-init.c: Find set-hooks.h using <...>. Update to db 2.3.10. * db2/Makefile: Update. * db2/db.h: Likewise. * db2/db_185.h: Likewise. * db2/db_int.h: Likewise. * db2/btree/bt_close.c: Likewise. * db2/btree/bt_conv.c: Likewise. * db2/btree/bt_cursor.c: Likewise. * db2/btree/bt_put.c: Likewise. * db2/btree/bt_rec.c: Likewise. * db2/btree/bt_recno.c: Likewise. * db2/btree/btree.src: Likewise. * db2/btree/btree_auto.c: Likewise. * db2/clib/getlong.c: Likewise. * db2/db/db.c: Likewise. * db2/db/db_auto.c: Likewise. * db2/db/db_conv.c: Likewise. * db2/db/db_pr.c: Likewise. * db2/db/db_ret.c: Likewise. * db2/db/db_thread.c: Likewise. * db2/hash/hash.c: Likewise. * db2/hash/hash_auto.c: Likewise. * db2/hash/hash_conv.c: Likewise. * db2/hash/hash_dup.c: Likewise. * db2/hash/hash_func.c: Likewise. * db2/hash/hash_page.c: Likewise. * db2/hash/hash_rec.c: Likewise. * db2/include/btree.h: Likewise. * db2/include/btree_ext.h: Likewise. * db2/include/db.h.src: Likewise. * db2/include/db_185.h.src: Likewise. * db2/include/db_cxx.h: Likewise. * db2/include/db_ext.h: Likewise. * db2/include/db_int.h.src: Likewise. * db2/include/db_page.h: Likewise. * db2/include/db_shash.h: Likewise. * db2/include/lock.h: Likewise. * db2/include/log.h: Likewise. * db2/include/log_ext.h: Likewise. * db2/include/mp.h: Likewise. * db2/include/shqueue.h: Likewise. * db2/include/txn.h: Likewise. * db2/lock/lock.c: Likewise. * db2/lock/lock_deadlock.c: Likewise. * db2/log/log.c: Likewise. * db2/log/log_archive.c: Likewise. * db2/log/log_auto.c: Likewise. * db2/log/log_get.c: Likewise. * db2/log/log_put.c: Likewise. * db2/log/log_register.c: Likewise. * db2/mp/mp_bh.c: Likewise. * db2/mp/mp_fget.c: Likewise. * db2/mp/mp_fopen.c: Likewise. * db2/mp/mp_fput.c: Likewise. * db2/mp/mp_fset.c: Likewise. * db2/mp/mp_open.c: Likewise. * db2/mutex/mutex.c: Likewise. * db2/os/db_os_dir.c: Likewise. * db2/progs/db_checkpoint/db_checkpoint.c: Likewise. * db2/progs/db_deadlock/db_deadlock.c: Likewise. * db2/progs/db_dump185/db_dump185.c: Likewise. * db2/progs/db_load/db_load.c: Likewise. * db2/progs/db_recover/db_recover.c: Likewise. * db2/txn/txn.c: Likewise. * db2/txn/txn_auto.c: Likewise. * elf/link.h: Define struct libname_list outside struct link_map to not confuse C++ compilers. * include/features.h: Recognize _XOPEN_SOURCE == 500 and set __USE_UNIX98. * manual/creature.texi: Explain this. * libc.map: Add new functions. * libio/Makefile (routines): Add fseeko and ftello. * libio/ftello.c: New file. * libio/fseeko.c: New file. * libio/stdio.h: Add prototypes for new functions. * manual/stdio.texi: Document fseeko and ftello. * posix/Makefile (routines): Add pread and pwrite. * sysdeps/posix/pread.c: New file. * sysdeps/posix/pwrite.c: New file. * sysdeps/stub/pread.c: New file. * sysdeps/stub/pwrite.c: New file. * posix/unistd.h: Add prototypes for pread and pwrite. Pretty print header. Define gid_t, uid_t, off_t, pid_t if __USE_UNIX98. Declare ctermid and cuserid if __USE_UNIX98. (swab): Change to take void * arguments. * string/swab.c: Change parameter to void *. * posix/sys/types: Define gid_t, uid_t, off_t, pid_t only if not already happened. * manual/llio.texi: Document pread and pwrite. * string/strings.h: Don't simply include string.h. Define BSD functions according to Unix98. * stdlib/tst-strtol.c: Include <string.h> not <strings.h>. * sunrpc/clnt_simp.c: Likewise. * malloc/Makefile (aux): Add set-freeres. * malloc/mtrace.c: Define function release_libc_mem which calls the __libc_subfreeres handler. (mtrace): Register release_libc_mem. * malloc/set-freeres.c: New file. * intl/dcgettext.c: Define free_mem function and add to __libc_subfreeres list. * intl/finddomain.c: Likewise. * intl/gettextP.h (struct loaded_domain): Add new fields use_mmap and mmap_size. Add prototype for _nl_unloaded_domain. * intl/loadmsgcat.c: Define new function _nl_unload_domain. (_nl_load_domain): Store informaiton about mmap use and file size. * intl/localealias.c (read_alias_file): Optimize locale alias file reading by avoid frequen mallocs. Define free_mem function and add to __libc_subfreeres list. * locale/localeinfo.h: Make a difference between MAX_USAGE_COUNT and undeletable. Add prototype for _nl_unload_locale. * locale/C-collate: Mark data as undeletable by using UNDELETABLE. * locale/C-ctype: Likewise. * locale/C-messages: Likewise. * locale/C-monetary: Likewise. * locale/C-numeric: Likewise. * locale/C-time: Likewise. * locale/findlocale.c (_nl_find_locale, _nl_remove_locale): Handle MAX_USAGE_COUNT and UNDELETABLE. (free_mem): New function. Add it to __libc_subfreeres list. * locale/loadlocale.c: Define _nl_unload_locale function. * misc/hsearch.c: Register hdestroy in __libc_subfreeres list. * stdlib/fmtmsg.c (addseverity): Handle illegal severity arguments correctly Define free_mem function and add to __libc_subfreeres list. * locale/programs/localedef.c (options): short form os verbose is v. Reported by Andreas Jaeger. * misc/sys/select.h: Define pselect only is __USE_POSIX since this header is used in some others as well for historical reasons. * resolv/resolv.h: Include <netinet/in.h> to make self-contained. * string/bits/string2.h: Add missing braces and optimize strcmp a bit more. * sysdeps/i386/i486/bits/string.h: Likewise. * sunrpc/rpc/auth_des.h: Include rpc/auth.h to be self-contained. Pretty print. * sysdeps/mach/hurd/cthreads.c: Add copyright text. * sysdeps/unix/sysv/linux/syscalls.list: Correct prctl entry. * sysdeps/unix/sysv/linux/sys/mman.h: Get definition of size_t. * time/time.h: Pretty print. 1997-09-29 Paul Eggert <eggert@twinsun.com> * time/strftime.c: Synchronize with GNU Emacs strftime.c. (HAVE_MEMCPY): Define if emacs is defined and HAVE_BCOPY isn't. (gmtime_r, localtime_r): Undef before defining. (iso_week_days): Use __inline__, not inline. 1997-09-27 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * sysdeps/m68k/fpu/bits/mathinline.h: Rename exp2{,l,f} to __ieee754_exp2{,l,f}. * sysdeps/m68k/fpu/s_exp2.c: Likewise. * sysdeps/m68k/fpu/s_exp2l.c: Likewise. * sysdeps/m68k/fpu/s_exp2f.c: Likewise. 1997-09-27 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * elf/soinit.c (__EH_FRAME_BEGIN__): Don't make the .eh_frame section read-only, it contains relocations. * elf/sofini.c (__FRAME_END__): Likewise. 1997-09-29 03:08 Ulrich Drepper <drepper@cygnus.com> * sysdeps/i386/i486/bits/string.h [__PIC__] (__strspn_cg, __strcspn_cg, __strpbrk_cg, __strstr_cg): Optimize even more. No spill register needed. Patch by NIIBE Yutaka <gniibe@mri.co.jp>. 1997-09-28 08:27 Thorsten Kukuk <kukuk@vt.uni-paderborn.de> * nis/nis_call.c (__do_niscall2): Fix return code, add missing break in switch case. * nis/nis_mkdir.c: Fix return codes to match Solaris version. * nis/nis_rmdir.c: Likewise. * nis/rpcsvc/yp_prot.h: Rename struct keydat to struct keydat_t for C++. 1997-09-28 04:32 Ulrich Drepper <drepper@cygnus.com> * configure.in: Fix typo. Patch by Zack Weinberg <zack@rabi.phys.columbia.edu>. 1997-09-25 20:14 Philip Blundell <Philip.Blundell@pobox.com> * sysdeps/unix/sysv/linux/scsi/sg.h: New file. * sysdeps/unix/sysv/linux/Makefile: Install <scsi/sg.h>.
Diffstat (limited to 'manual/stdio.texi')
-rw-r--r--manual/stdio.texi117
1 files changed, 83 insertions, 34 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi
index 085a1c95a8..4c90b25447 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -697,8 +697,9 @@ order that they were pushed.
Pushing back characters doesn't alter the file; only the internal
buffering for the stream is affected. If a file positioning function
-(such as @code{fseek} or @code{rewind}; @pxref{File Positioning}) is
-called, any pending pushed-back characters are discarded.
+(such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
+Positioning}) is called, any pending pushed-back characters are
+discarded.
Unreading a character on a stream that is at end of file clears the
end-of-file indicator for the stream, because it makes the character of
@@ -3033,6 +3034,28 @@ possibly for other reasons as well. If a failure occurs, a value of
@end deftypefun
@comment stdio.h
+@comment Unix98
+@deftypefun off_t ftello (FILE *@var{stream})
+The @code{ftello} function is similar to @code{ftell} only it corrects a
+problem which the POSIX type system. In this type system all file
+positions are described using values of type @code{off_t} which is not
+necessarily of the same size as @code{long int}. Therefore using
+@code{ftell} can lead to problems if the implementation is written on
+top of a POSIX compliant lowlevel I/O implementation.
+
+Therefore it is a good idea to prefer @code{ftello} whenever it is
+available since its functionality is (if different at all) closer the
+underlying definition.
+
+If this function fails it return @code{(off_t) -1}. This can happen due
+to missing support for file positioning or internal errors. Otherwise
+the return value is the current file position.
+
+The function is an extension defined in the Unix Single Specification
+version 2.
+@end deftypefun
+
+@comment stdio.h
@comment ISO
@deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
The @code{fseek} function is used to change the file position of the
@@ -3051,9 +3074,28 @@ position or else remembers it so it will be written later in its proper
place in the file.
@end deftypefun
-@strong{Portability Note:} In non-POSIX systems, @code{ftell} and
-@code{fseek} might work reliably only on binary streams. @xref{Binary
-Streams}.
+@comment stdio.h
+@comment Unix98
+@deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
+This function is similar to @code{fseek} but it corrects a problem with
+@code{fseek} in a system with POSIX types. Using a value of type
+@code{long int} for the offset is not compatible with POSIX.
+@code{fseeko} uses the correct type @code{off_t} for the @var{offset}
+parameter.
+
+For this reasonit is a good idea to prefer @code{ftello} whenever it is
+available since its functionality is (if different at all) closer the
+underlying definition.
+
+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.
+@end deftypefun
+
+@strong{Portability Note:} In non-POSIX systems, @code{ftell},
+@code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
+on binary streams. @xref{Binary Streams}.
The following symbolic constants are defined for use as the @var{whence}
argument to @code{fseek}. They are also used with the @code{lseek}
@@ -3064,34 +3106,35 @@ function (@pxref{I/O Primitives}) and to specify offsets for file locks
@comment ISO
@deftypevr Macro int SEEK_SET
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} function, specifies that the offset
-provided is relative to the beginning of the file.
+argument to the @code{fseek} or @code{fseeko} function, specifies that
+the offset provided is relative to the beginning of the file.
@end deftypevr
@comment stdio.h
@comment ISO
@deftypevr Macro int SEEK_CUR
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} function, specifies that the offset
-provided is relative to the current file position.
+argument to the @code{fseek} or @code{fseeko} function, specifies that
+the offset provided is relative to the current file position.
@end deftypevr
@comment stdio.h
@comment ISO
@deftypevr Macro int SEEK_END
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} function, specifies that the offset
-provided is relative to the end of the file.
+argument to the @code{fseek} or @code{fseeko} function, specifies that
+the offset provided is relative to the end of the file.
@end deftypevr
@comment stdio.h
@comment ISO
@deftypefun void rewind (FILE *@var{stream})
The @code{rewind} function positions the stream @var{stream} at the
-begining of the file. It is equivalent to calling @code{fseek} on the
-@var{stream} with an @var{offset} argument of @code{0L} and a
-@var{whence} argument of @code{SEEK_SET}, except that the return
-value is discarded and the error indicator for the stream is reset.
+begining of the file. It is equivalent to calling @code{fseek} or
+@code{fseeko} on the @var{stream} with an @var{offset} argument of
+@code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
+the return value is discarded and the error indicator for the stream is
+reset.
@end deftypefun
These three aliases for the @samp{SEEK_@dots{}} constants exist for the
@@ -3122,9 +3165,10 @@ An alias for @code{SEEK_END}.
@section Portable File-Position Functions
On the GNU system, the file position is truly a character count. You
-can specify any character count value as an argument to @code{fseek} and
-get reliable results for any random access file. However, some @w{ISO C}
-systems do not represent file positions in this way.
+can specify any character count value as an argument to @code{fseek} or
+@code{fseeko} and get reliable results for any random access file.
+However, some @w{ISO C} systems do not represent file positions in this
+way.
On some systems where text streams truly differ from binary streams, it
is impossible to represent the file position of a text stream as a count
@@ -3140,14 +3184,14 @@ systems, you must observe certain rules:
The value returned from @code{ftell} on a text stream has no predictable
relationship to the number of characters you have read so far. The only
thing you can rely on is that you can use it subsequently as the
-@var{offset} argument to @code{fseek} to move back to the same file
-position.
+@var{offset} argument to @code{fseek} or @code{fseeko} to move back to
+the same file position.
@item
-In a call to @code{fseek} on a text stream, either the @var{offset} must
-either be zero; or @var{whence} must be @code{SEEK_SET} and the
-@var{offset} must be the result of an earlier call to @code{ftell} on
-the same stream.
+In a call to @code{fseek} or @code{fseeko} on a text stream, either the
+@var{offset} must either be zero; or @var{whence} must be
+@code{SEEK_SET} and the @var{offset} must be the result of an earlier
+call to @code{ftell} on the same stream.
@item
The value of the file position indicator of a text stream is undefined
@@ -3158,7 +3202,11 @@ that haven't been read or discarded. @xref{Unreading}.
But even if you observe these rules, you may still have trouble for long
files, because @code{ftell} and @code{fseek} use a @code{long int} value
to represent the file position. This type may not have room to encode
-all the file positions in a large file.
+all the file positions in a large file. Using the @code{ftello} and
+@code{fseeko} functions might help here since the @code{off_t} type is
+expected to be able to hold all file position values but this still does
+not help to handle additional information which must be associated with
+a file position.
So if you do want to support systems with peculiar encodings for the
file positions, it is better to use the functions @code{fgetpos} and
@@ -3550,9 +3598,10 @@ new values before you use them again.
A null character is written at the end of the buffer. This null character
is @emph{not} included in the size value stored at @var{sizeloc}.
-You can move the stream's file position with @code{fseek} (@pxref{File
-Positioning}). Moving the file position past the end of the data
-already written fills the intervening space with zeroes.
+You can move the stream's file position with @code{fseek} or
+@code{fseeko} (@pxref{File Positioning}). Moving the file position past
+the end of the data already written fills the intervening space with
+zeroes.
@end deftypefun
Here is an example of using @code{open_memstream}:
@@ -3587,9 +3636,9 @@ Calling @code{fflush} on this stream updates the current size of the
object to match the amount of data that has been written. After a call
to @code{fflush}, you can examine the object temporarily.
-You can move the file position of an obstack stream with @code{fseek}
-(@pxref{File Positioning}). Moving the file position past the end of
-the data written fills the intervening space with zeros.
+You can move the file position of an obstack stream with @code{fseek} or
+@code{fseeko} (@pxref{File Positioning}). Moving the file position past
+the end of the data written fills the intervening space with zeros.
To make the object permanent, update the obstack with @code{fflush}, and
then use @code{obstack_finish} to finalize the object and get its address.
@@ -3691,9 +3740,9 @@ discarded.
@item cookie_seek_function_t *seek
This is the function that performs the equivalent of file positioning on
the cookie. If the value is a null pointer instead of a function, calls
-to @code{fseek} on this stream can only seek to locations within the
-buffer; any attempt to seek outside the buffer will return an
-@code{ESPIPE} error.
+to @code{fseek} or @code{fseeko} on this stream can only seek to
+locations within the buffer; any attempt to seek outside the buffer will
+return an @code{ESPIPE} error.
@item cookie_close_function_t *close
This function performs any appropriate cleanup on the cookie when