NAME

fseek(), rewind(), ftell() − reposition a file pointer in a stream

SYNOPSIS

#include <stdio.h>

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

void rewind(FILE *stream);

long int ftell(FILE *stream);

DESCRIPTION

fseek() sets the file-position indicator for stream. The new position, measured in bytes from the beginning of the file, is obtained by adding offset to the position specified by whence. The specified position is the beginning of the file for SEEK_SET, the current position for SEEK_CUR, or end-of-file for SEEK_END. 

If the most recent operation, other than ftell() , on the stream is fflush(), the file offset in the underlying open file description is adjusted to reflect the location specified by the fseek() . 

rewind(stream) is equivalent to fseek (stream, 0L, SEEK_SET), except that no value is returned. 

fseek() and rewind() undo any effects of ungetc(3S).

After fseek() or rewind(), the next operation on a file opened for update can be either input or output.  fseek() clears the EOF indicator for the stream. rewind() does an implicit clearerr() call (see ferror(3S)).

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

RETURN VALUE

fseek() returns zero if it succeeds.  Otherwise it returns −1 and sets errno to indicate the error. 

ftell() returns the current value of the file position indicator for the stream measured in bytes from the beginning of the file.  Otherwise, ftell() returns −1 and sets errno to indicate the error. 

rewind() does not return a value.  Therefore, any application that needs to detect errors should clear errno before calling rewind().  Then, upon completion, if errno is non-zero, it should assume an error has occurred. 

ERRORS

fseek(), ftell(), and rewind() fail if the stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered:

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

[EBADF] The underlying file is not open for writing. 

[EFBIG] An attempt was made to write a file that exceeds the process’s file size limit or the maximum file size.  See ulimit(2).

[EINTR] A signal was caught during the write operation. 

[EIO] The process is in a background process group and is attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking the SIGTTOU signal, 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 that is not open for reading by any process.  A SIGPIPE signal is also sent to the process. 

[ESPIPE] A seek operation was attempted and the file descriptor underlying stream is associated with a pipe. 

fseek() also fails if:

[EINVAL] The whence argument is invalid, or the file-position indicator would be set to a negative value. 

Additional errno values may be set by the underlying write() and lseek() functions (see write(2) and lseek(2)).

WARNINGS

On HP-UX systems, the offset returned by ftell() is measured in bytes and it is permissible to seek to positions relative to that offset.  However, when porting to non- HP-UX systems, fseek() should be used directly without relying on any offset obtained from ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. 

fseek() and rewind() have no effect on streams that have been opened in append mode (see fopen(3S)).

SEE ALSO

lseek(2), write(2), ferror(3S), fopen(3S), fgetpos(3S), ungetc(3S). 

STANDARDS CONFORMANCE

fseek(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

ftell(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

rewind(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992