FSEEK(3S)                            SysV                            FSEEK(3S)



NAME
     fgetpos, fseek, fsetpos, ftell, rewind - reposition a file pointer in a
     stream

SYNOPSIS
     #include <stdio.h>

     int fgetpos(stream, pos)
     FILE *stream;
     fpos_t *pos;

     int fseek (stream, offset, ptrname)
     FILE *stream;
     long int offset;
     int ptrname;

     int fsetpos(stream, pos)
     FILE *stream;
     const fpos_t *pos;

     long int ftell(stream)
     FILE *stream;

     void rewind (stream)
     FILE *stream;

DESCRIPTION
     fgetpos stores the current value of the file position indicator for the
     stream pointed to by stream in the object pointed to by pos.  The value
     stored contains unspecified information usable by fsetpos for
     repositioning the stream to its position at the time of the call to
     fgetpos.

     fseek sets the position of the next input or output operation on the
     stream.  The new position is at the signed distance offset bytes from the
     beginning, from the current position, or from the end of the file,
     according as ptrname has the value SEEK_SET, SEEK_CUR, or SEEK_END.

     A successful call to the fseek function clears the End-of-File indicator
     for the stream and undoes any effects of the ungetc(3S) function on the
     same stream.  After a call to the fseek function, the next operation on
     an update stream may be either input or output.

     If the stream is writable and buffered data was not written to the
     underlying file, the fseek function causes the unwritten data to be
     written to the file and marks the st_ctime and st_mtime fields of the
     file for update.

     If the most recent operation, other than ftell, on a given stream is
     fflush, the file offset in the underlying open file description will be
     adjusted to reflect the location specified by the fseek function.

     The fseek function allows the file-position indicator to be set beyond
     the end of existing data in the file.  If data is later written at this
     point, subsequent reads of data in the gap will return bytes with the
     value 0 (zero) until data is actually written into the gap.  The fseek
     function does not, by itself, extend the size of a file.

     The rewind function is equivalent to (void) fseek (stream, 0L, SEEK_SET),
     except that it also clears the error indicator.

     For program compiled to expect AES, POSIX, or XPG3 behavior, fseek undoes
     any effects of ungetc(3S).

     After fseek or rewind, the next operation on a file opened for update may
     be either input or output.

     ftell returns the offset of the current byte relative to the beginning of
     the file associated with the named stream.

     The result of ftell after an fflush(3S) is the same as the result before
     the fflush(3S).

DIAGNOSTICS
     Upon successful completion, the fseek function returns a value of 0
     (zero). If the fseek function fails, a value of -1 is returned and errno
     is set to indicate the error. (An improper seek can be, for example, an
     fseek done on a file that has not been opened via fopen; in particular,
     fseek may not be used on a terminal, or on a file opened via popen(3S).)

     The rewind function does not return a value.

     Upon successful completion, the ftell function returns the offset of the
     current byte relative to the beginning of the file associated with the
     named stream.  Otherwise, -1 is returned and errno is set to indicate the
     error.

     Upon successful completion, the fgetpos and fsetpos functions return 0
     (zero). If the fgetpos or the fsetpos function fails, a value of -1 is
     returned.  The fseek calls return less data than was requested only if a
     write error is encountered. (Instead of calling write(2) once and risk
     having it return less than what was requested, it keeps calling write
     until they finish or receive an outright error.)

ERRORS
     The fseek function fails if either the stream is unbuffered, or the
     stream's buffer needed to be flushed and the call to fseek caused an
     underlying lseek or write function to be invoked.

     In addition, if the fseek function fails, errno is set to one of the
     following values:

     [EAGAIN]       The O_NONBLOCK flag is set for the file descriptor
                    underlying the stream parameter and the process would be
                    delayed in the write operation.

     [EBADF]        The file descriptor underlying the stream parameter is not
                    a valid file descriptor open for writing.

     [EFBIG]        An attempt was made to write to a file that exceeds the
                    process' file size limit or the maximum file size.  See
                    the ulimit function.

     [EINTR]        The read operation was interrupted by a signal which was
                    caught, and no data was transferred.

     [EIO]          The process is a member of a background process group
                    attempting to write to its controlling terminal, TOSTOP is
                    set, the process is neither ignoring nor blocking SIGTTOU,
                    and the process group of the process is orphaned.

     [ENOSPC]       There was no free space remaining on the device containing
                    the file.

     [EPIPE]        An attempt was made to write to a pipe or FIFO that is not
                    open for reading by any process.  A SIGPIPE signal will
                    also be sent to the process.

     The rewind and ftell functions fail under the same conditions as the
     fseek function, with the exception of [EINVAL], which does not apply.

SEE ALSO
     lseek(2), fopen(3S), popen(3S), stdio(3S), ungetc(3S).

WARNING
     Although on the UNIX system an offset returned by ftell is measured in
     bytes, and it is permissible to seek to positions relative to that
     offset, portability to other systems requires that an offset be used by
     fseek directly. Arithmetic may not meaningfully be performed on such an
     offset, which is not necessarily measured in bytes.