NAME
fgetpos,
fseek,
fseeko,
fsetpos,
ftell,
ftello,
rewind —
reposition a stream
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdio.h>
int
fseek(
FILE
*stream,
long int
offset,
int whence);
int
fseeko(
FILE
*stream,
off_t
offset,
int whence);
long int
ftell(
FILE
*stream);
off_t
ftello(
FILE
*stream);
void
rewind(
FILE
*stream);
int
fgetpos(
FILE *
restrict stream,
fpos_t *
restrict pos);
int
fsetpos(
FILE *
restrict stream,
const
fpos_t * restrict pos);
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 the
fseek() function except that the
offset argument is of type
off_t.
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 the
ftell() function except that the 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)).
In this implementations, “
fpos_t” is a complex
object that represents both the position and the parse state of the stream,
making these routines as the only way to portably reposition a text stream.
The
pos argument of
fsetpos() must
always be initialized by a call to
fgetpos().
RETURN VALUES
The
rewind() function returns no value.
Upon successful completion,
fgetpos(),
fseek(),
fseeko(), and
fsetpos() return 0, whereas the functions
ftell() and
ftello() return the current
offset. On failure,
fseek(),
fseeko(),
ftell(), and
ftello() return -1, while
fgetpos() and
fsetpos() return a nonzero
value.
On error all functions set the global variable
errno to
indicate the error. Since the
rewind() function does not
return an error code, applications need to clear
errno
before calling it in order to detect errors.
ERRORS
-
-
- [
EBADF
]
- The stream specified is not a
seekable stream.
-
-
- [
EINVAL
]
- The whence argument to
fseek() was not
SEEK_SET
,
SEEK_END
, or
SEEK_CUR
.
-
-
- [
EOVERFLOW
]
- For ftell(), the current file offset
cannot be represented correctly in an object of type
long.
The function
fgetpos(),
fseek(),
fseeko(),
fsetpos(),
ftell(),
ftello(), and
rewind() 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
lseek(2),
clearerr(3),
ungetc(3)
STANDARDS
The
fgetpos(),
fsetpos(),
fseek(),
ftell(), and
rewind() functions conform to
ANSI
X3.159-1989 (“ANSI C89”). The
fseeko() and
ftello() functions conform to
X/Open System Interfaces and Headers Issue 5
(“XSH5”).
BUGS
The
fgetpos() and
fsetpos() functions don't
store/set shift states of the stream in this implementation.