NAME
fgetpos
, fseek
,
fseeko
, fsetpos
,
ftell
, ftello
,
rewind
—
reposition a stream
SYNOPSIS
#include
<stdio.h>
int
fgetpos
(FILE
*stream, fpos_t
*pos);
int
fseek
(FILE
*stream, long
offset, int
whence);
int
fseeko
(FILE
*stream, off_t
offset, int
whence);
int
fsetpos
(FILE
*stream, const fpos_t
*pos);
long
ftell
(FILE
*stream);
off_t
ftello
(FILE
*stream);
void
rewind
(FILE
*stream);
DESCRIPTION
The
fseek
()
function sets the file position indicator for the stream pointed to by
stream. The new position, measured in bytes, is
obtained by adding offset bytes to the position
specified by whence. If whence
is set to SEEK_SET
,
SEEK_CUR
, or SEEK_END
, the
offset is relative to the start of the file, the current position indicator,
or end-of-file, respectively. A successful call to the
fseek
() function clears the end-of-file indicator
for the stream and undoes any effects of the
ungetc(3) function on the
same stream.
The
fseeko
()
function is identical to fseek
() except that it
takes an off_t as its
offset.
The
ftell
()
function obtains the current value of the file position indicator for the
stream pointed to by stream.
The
ftello
()
function is identical to ftell
() except that its
return value is of type off_t.
The
rewind
()
function sets the file position indicator for the stream pointed to by
stream to the beginning of the file. It is equivalent
to:
(void)fseek(stream, 0L,
SEEK_SET)
except that the error indicator for the stream is also cleared (see clearerr(3)).
The
fgetpos
()
and
fsetpos
()
functions are alternate interfaces equivalent to
ftell
() and fseek
() (with
whence set to SEEK_SET
), setting and storing the
current value of the file offset into or from the object referenced by
pos. On some systems an
“fpos_t” object may be a complex object
and these routines may be the only way to portably reposition a text
stream.
RETURN VALUES
The rewind
() function returns no value.
Prefer fseek
(), which is just as portable, and does
not hide errors. Upon successful completion,
fgetpos
(), fseek
(),
fseeko
(), and fsetpos
()
return 0 and ftell
() and
ftello
() return the current offset. Otherwise,
fseek
(), fseeko
(),
ftell
(), and ftello
() return
-1 and fgetpos
() and
fsetpos
() return a non-zero value and the global
variable errno is set to indicate the error.
ERRORS
The fgetpos
(),
fseek
(), fseeko
(),
fsetpos
(), ftell
(),
ftello
(), and rewind
()
functions will fail if:
- [
EBADF
] - The stream specified is not a seekable stream.
Additionally, the fseek
() and
fseeko
() functions will fail if:
- [
EINVAL
] - The whence argument was not
SEEK_SET
,SEEK_END
, orSEEK_CUR
.
Additionally, the ftell
() function will
fail if:
- [
EOVERFLOW
] - The value of the file position indicator is too large to be represented by a long.
Finally, the functions fgetpos
(),
fseek
(), fseeko
(),
fsetpos
(), ftell
(), and
ftello
() may also fail and set
errno for any of the errors specified for the routines
fflush(3),
fstat(2),
lseek(2), and
malloc(3).
SEE ALSO
STANDARDS
The fgetpos
(),
fsetpos
(), fseek
(),
ftell
(), and rewind
()
functions conform to ANSI X3.159-1989
(“ANSI C89”) and X/Open
Portability Guide Issue 4 (“XPG4”).
The fseeko
() and
ftello
() functions conform to
X/Open Portability Guide Issue 4
(“XPG4”).
HISTORY
The functions fseek
(),
ftell
(), and rewind
() first
appeared in Version 7 AT&T UNIX.