fseek(3S) fseek(3S)
NAME
fseek, rewind, ftell, fseeko, fseeko64, ftello, ftello64 - 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);
int fseeko(FILE *stream, offt offset, int whence);
int fseeko64(FILE *stream, off64t offset, int whence);
offt ftello(FILE *stream);
off64t ftello64(FILE *stream);
DESCRIPTION
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 to a whence value of SEEKSET, SEEKCUR, or SEEKEND,
defined in stdio.h as follows:
SEEKSET Set position equal to offset bytes.
SEEKCUR Set position to current location plus offset.
SEEKEND Set position to EOF plus offset.
If the stream is to be used with wide character input/output func-
tions, offset must either be zero or a value returned by an earlier
ftell() call on the same stream, and prtname must be SEEKSET.
fseek() allows the file position indicator to be set beyond the end of
the existing data in the file. If data is later written at this point,
subsequent reads of data in the gap will return zero until data is
actually written into the gap.
rewind(stream) is equivalent to:
(void) fseek(stream, 0L, SEEKSET);
except that rewind() also clears the error indicator on stream.
fseek() and rewind() clear the EOF indicator and undo any effects of
ungetc() on stream.
Page 1 Reliant UNIX 5.44 Printed 11/98
fseek(3S) fseek(3S)
After fseek() or rewind(), the next operation on a file opened for
update may be either input or output.
If stream is writable and buffered data has not been written to the
underlying file, fseek() and rewind() cause the unwritten data to be
written to the file.
ftell() returns the offset of the current byte relative to the begin-
ning of the file associated with the named stream.
The fseeko() and ftello() functions are identical to the modified
fseek() and ftell(), except that the offset argument is of type offt
and the EOVERFLOW error has changed.
fseeko() and ftello() are needed because fseek() and ftell() are lim-
ited by the long offset type required by ISO C.
There is no functional difference between fseeko()/ftello() and
fseeko64()/ftello64(), except for the interpretation of off64t [see
lfs(5)].
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
fseek() will fail if:
EAGAIN The ONONBLOCK flag is set for the file descriptor and the
process would be delayed in the write operation.
EBADF The file descriptor underlying the stream is not open for
writing or the stream's buffer needed to be flushed and
the file is not open.
EFBIG An attempt was made to write a file that exceeds the max-
imum file size or the process' file size limit.
EFBIG The file is a regular file and an attempt was made to
write at or beyond the offset maximum associated with the
corresponding stream.
EINTR The write operation was terminated due to the receipt of a
signal, and no data was transferred.
EINVAL whence is an invalid argument. The resulting file-position
indicator would be set to a negative value.
EIO A physical input/output error has occurred, or the process
is a member of a background process group attempting to
perform a 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. This
Page 2 Reliant UNIX 5.44 Printed 11/98
fseek(3S) fseek(3S)
error may also be returned under implementation-dependent
conditions.
ENOSPC There is no free space on the device.
EPIPE The file descriptor underlying the stream is associated
with a pipe or FIFO.
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 be
sent to the process.
ENXIO The device does not exist or cannot be accessed.
EOVERFLOW The resulting file offset would be a value which cannot be
represented correctly in an object of type long.
fseeko() and ftello() will fail if:
EOVERFLOW The current file offset cannot be represented correctly in
an object of type offt.
RESULT
fseek() returns -1 for improper seeks, otherwise zero. 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 termi-
nal or on a file opened via popen(3S). After a stream is closed, no
further operations are defined on that stream.
NOTES
Although on the Reliant 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 non Reliant UNIX systems requires that
a direct offset is used by fseek(). Arithmetic operations cannot
always be meaningfully performed on a non Reliant UNIX offset, which
is not necessarily measured in bytes.
Applications which use the fseeko() and ftello() interfaces should
define LARGEFILESOURCE to be 1, then include <unistd.h> and then
test that LFSLARGEFILE is 1 to determine if the additional func-
tionality is indeed available. This additional functionality may be
available even when LARGEFILESOURCE is not defined, but it will not
be available to strictly conforming X/Open programs.
SEE ALSO
lseek(2), write(2), fopen(3S), popen(3S), stdio(3S), ungetc(3S),
unistd(4), lfs(5), stdio(5).
Page 3 Reliant UNIX 5.44 Printed 11/98