fseek(3S)

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.

fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the fseek() except that the offset parameter is an off_t instead of a long int. All other functional behaviors, returns, and errors are identical to the POSIX fseek().

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.

ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the ftell() except that it returns an off_t instead of a long int. All other behaviors, returns, and errors are identical to the POSIX ftell().

RETURN VALUE

fseek() and fseek_unlocked() return zero if they succeed. Otherwise they return -1 and set errno to indicate the error.

ftell() and ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, ftell() and ftell_unlocked() return -1 and set errno to indicate the error.

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

ERRORS

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

fseek() and fseek_unlocked() also fail if:

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() or ftell_unlocked() 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(), fseek_unlocked(), rewind(), and rewind_unlocked() have no effect on streams that have been opened in append mode (see fopen(3S)).

fseek_unlocked(), ftell_unlocked() and rewind_unlocked() are obsolescent interfaces supported for compatibility with existing DCE applications. New multithreaded applications should use fseek(), ftell() and rewind().

SEE ALSO

lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fgetpos64(3S), ungetc(3S), thread_safety(5).

STANDARDS CONFORMANCE

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

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

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