diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/creature.texi | 4 | ||||
| -rw-r--r-- | manual/llio.texi | 65 | ||||
| -rw-r--r-- | manual/stdio.texi | 117 |
3 files changed, 150 insertions, 36 deletions
diff --git a/manual/creature.texi b/manual/creature.texi index edac770f6c..9d9b451a94 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -85,6 +85,10 @@ BSD and SVID is also included. If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more functionality is available. The extra functions will make all functions available which are necessary for the X/Open Unix brand. + +If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes +all functionality described so far plus some new definitions from the +Single Unix specification, @w{version 2}. @end defvr @comment (none) diff --git a/manual/llio.texi b/manual/llio.texi index 7891ee66e0..4c10b72578 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -301,6 +301,35 @@ The @code{read} function is the underlying primitive for all of the functions that read from streams, such as @code{fgetc}. @end deftypefun +@comment unistd.h +@comment Unix98 +@deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset}) +The @code{pread} function is similar to the @code{read} function. The +first three arguments are identical and also the return values and error +codes correspond. + +The difference is the fourth argument and its handling. The data block +is not read from the current position of the file descriptor +@code{filedes}. Instead the data is read from the file starting at +position @var{offset}. The position of the file descriptor itself is +not effected by the operation. The value is the same as before the call. + +The return value of @code{pread} describes the number of bytes read. +In the error case it returns @math{-1} like @code{read} does and the +error codes are also the same. Only there are a few more error codes: +@table @code +@item EINVAL +The value given for @var{offset} is negative and therefore illegal. + +@item ESPIPE +The file descriptor @var{filedes} is associate with a pipe or a FIFO and +this device does not allow positioning of the file pointer. +@end table + +The function is an extension defined in the Unix Single Specification +version 2. +@end deftypefun + @cindex writing to a file descriptor @comment unistd.h @comment POSIX.1 @@ -320,8 +349,10 @@ storage immediately. You can use @code{fsync} when you need to be sure your data has been permanently stored before continuing. (It is more efficient for the system to batch up consecutive writes and do them all at once when convenient. Normally they will always be written to disk -within a minute or less.) -@c !!! xref fsync +within a minute or less.) Modern systems provide another function +@code{fdatasync} which guarantees integrity only for the file data and +is therefore faster. +@c !!! xref fsync, fdatasync You can use the @code{O_FSYNC} open mode to make @code{write} always store the data to disk before returning; @pxref{Operating Modes}. @@ -392,6 +423,36 @@ The @code{write} function is the underlying primitive for all of the functions that write to streams, such as @code{fputc}. @end deftypefun +@comment unistd.h +@comment Unix98 +@deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset}) +The @code{pwrite} function is similar to the @code{write} function. The +first three arguments are identical and also the return values and error +codes correspond. + +The difference is the fourth argument and its handling. The data block +is not written to the current position of the file descriptor +@code{filedes}. Instead the data is written to the file starting at +position @var{offset}. The position of the file descriptor itself is +not effected by the operation. The value is the same as before the call. + +The return value of @code{pwrite} describes the number of written bytes. +In the error case it returns @math{-1} like @code{write} does and the +error codes are also the same. Only there are a few more error codes: +@table @code +@item EINVAL +The value given for @var{offset} is negative and therefore illegal. + +@item ESPIPE +The file descriptor @var{filedes} is associate with a pipe or a FIFO and +this device does not allow positioning of the file pointer. +@end table + +The function is an extension defined in the Unix Single Specification +version 2. +@end deftypefun + + @node File Position Primitive @section Setting the File Position of a Descriptor 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 |