fseek, fseeko, fseek_unlocked, rewind, ftell, ftello,
fgetpos, fsetpos - Reposition the file pointer of a stream
#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 ); long int ftell(
FILE *stream ); off_t ftello(
FILE *stream ); int fsetpos(
FILE *stream,
const fpos_t *position ); int fgetpos(
FILE *stream,
fpos_t *position );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
fseek(), fgetpos(), fsetpos(), ftell(), rewind(): XSH5.0,
XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the I/O stream. Determines the position of the
next operation. Determines the value for the file pointer
associated with the stream parameter. Specifies the value
of the file position indicator.
The fseek() function sets the position of the next input
or output operation on the I/O stream specified by the
stream parameter. The position of the next operation is
determined by the offset parameter, which can be either
positive or negative.
The fseek() function sets the file pointer associated with
the specified stream as follows: If the whence parameter
is SEEK_SET(0), the pointer is set to the value of the
offset parameter. If the whence parameter is SEEK_CUR(1),
the pointer is set to its current location plus the value
of the offset parameter. If the whence parameter is
SEEK_END(2), the pointer is set to the size of the file
plus the value of the offset parameter.
The fseek() function fails if attempted on a file that was
not opened with the fopen() function. In particular, the
fseek() function cannot be used on a terminal or on a file
opened with the popen() function.
A successful call to the fseek() function clears the Endof-File
indicator for the stream and undoes any effects of
the ungetc() function on the same stream. After a call to
the fseek() function, the next operation on an update
stream may be either input or output.
If the stream is writable, and buffered data was not written
to the underlying file, the fseek() function causes
the unwritten data to be written to the file and marks the
st_ctime and st_mtime fields of the file for update.
If the most recent operation (ignoring any ftell() operations)
on a given stream was fflush(), then the fseek()
function causes the file offset in the underlying open
file descriptor to be adjusted to reflect the location
specified by the fseek() function.
The fseek() function allows the file-position indicator to
be set beyond the end of existing data in the file. If
data is later written at this point, subsequent reads of
data in the gap will return bytes with the value 0 (zero)
until data is actually written into the gap.
The rewind() function is equivalent to: (void) fseek
(stream, 0L, SEEK_SET) Except that rewind() also clears
the error indicator.
The ftell() function obtains the current value of the file
position indicator for the specified stream.
The fgetpos() and fsetpos() functions are similar to the
ftell() and fseek() functions, respectively. The fgetpos()
function stores the current value of the file position
indicator for the stream pointed to by the stream parameter
in the object pointed to by the position parameter.
The fsetpos function sets the file position indicator
according to the value of the position parameter that was
returned by a prior call to the fgetpos() function.
A successful call to the fsetpos() function clears the EOF
indicator and undoes any effects of the ungetc() function.
[Tru64 UNIX] The fseek_unlocked() function is functionally
identical to the fseek() function, except that
fseek_unlocked() may be safely used only within a scope
that is protected by the flockfile() and funlockfile()
functions used as a pair. The caller must ensure that the
stream is locked before using these functions.
The fseeko() and ftello() functions behave identically to
fseek() and ftell().
Upon successful completion, the fseek() and
fseek_unlocked() functions return a value of 0 (zero). If
the fseek() or fseek_unlocked() function fails, a value of
-1 is returned and errno is set to indicate the error.
The rewind() function does not return a value. You can
detect errors by first clearing errno and then calling the
rewindfunction. If errno is then nonzero, assume an error
has occurred.
Upon successful completion, the ftell() function returns
the offset of the current byte relative to the beginning
of the file associated with the named stream. Otherwise, a
value of -1 is returned and errno is set to indicate the
error.
Upon successful completion, the fgetpos() and fsetpos()
functions return a value of 0 (zero). If the fgetpos() or
fsetpos() function fails, a value of -1 is returned and
errno is set to indicate the error.
The fseek() or fseek_unlocked() function fails if either
the stream is unbuffered or the stream's buffer needed to
be flushed and the call to fseek() or fseek_unlocked()
caused an underlying lseek() or write() function to be
invoked. In addition, if any of the following conditions
occurs, the fseek() or fseek_unlocked() function sets
errno to the value that corresponds to the condition. The
O_NONBLOCK option is set for the file descriptor underlying
the stream parameter and the process would be delayed
in the write operation. The file descriptor underlying
the stream parameter is not a valid file descriptor open
for writing. An attempt was made to write to a file that
exceeds the process's file size limit or the maximum file
size. (See the ulimit(3) reference page.)
The file is a regular file and an attempt was made
to write at or beyond the offset maximum associated
with the corresponding stream. The write operation
was terminated by a signal, and either none, some,
or all the data was transferred. If buffered I/O is
being used, it is recommended that you call the
fflush() function before the fseek() function to
guarantee that the buffer characters were written.
The whence parameter is an invalid value or the
resulting file offset would be invalid. A physical
I/O error has occurred or the following set of conditions
has occurred: the process is a member of a
background process group attempting to write to its
controlling terminal, the TOSTOP signal is set, the
process is neither ignoring nor blocking SIGTTOU,
and the process group of the process is orphaned.
No free space remained on the device containing the
file. The file descriptor underlying stream is
associated with a pipe or FIFO.
An attempt was made to write to a pipe or FIFO that
is not open for reading by any process. A SIGPIPE
signal will also be sent to the process. A request
was made of a nonexistent device or the request was
outside the capabilities of the device.
The rewind() function fails under the same conditions as
the fseek() function, with the exception of [EINVAL],
which does not apply.
If the following conditions occur, the fgetpos(), fsetpos()
or ftell() function sets errno to the value that
corresponds to the condition. The file descriptor underlying
the stream parameter is not a valid file descriptor.
[Tru64 UNIX] The stream parameter does not point to a
valid FILE structure or the position parameter is negative.
An illegal attempt was made to get or set the file
position of a pipe or FIFO.
[XNS5.0] The file descriptor parameter underlying
stream is associated with a socket.
Functions: lseek(2), fopen(3)
Standards: standards(5)
fseek(3)
[ Back ] |
