fseek(3S)

NAME

fseek(), fseeko(), fseek_unlocked(), rewind(), rewind_unlocked(), ftell(), ftello(), ftell_unlocked() − reposition a file pointer in a stream

SYNOPSIS

#include <stdio.h>

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

int fseeko(FILE *stream, off_t offset, int whence);

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

void rewind(FILE *stream);

void rewind_unlocked(FILE *stream);

long int ftell(FILE *stream);

off_t ftello(FILE *stream);

long int ftell_unlocked(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.

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().

fseek_unlocked(), rewind_unlocked(), and ftell_unlocked() are identical to fseek(), rewind(), and ftell() respectively except they do not perform any internal locking of the stream for multi-thread applications. The _unlocked routines can be used by multi-thread applications which have already used flockfile() to acquire a mutual exclusion lock for the stream (see flockfile(3S)).

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:

[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).

[EINVAL] The file offset cannot be represented correctly in an object of type long or size off_t in this environment.

[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() and fseek_unlocked() also fail 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() 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)).

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

Hewlett-Packard Company — HP-UX Release 10.20: July 1996

Museum

Related Articles