Repositions the file pointer of a stream.
Standard C Library (libc.a)
#include <stdio.h>int fseek ( Stream, Offset, Whence)
FILE *Stream;
long int Offset;
int Whence;
void rewind (Stream)
FILE *Stream;long int ftell (Stream)
FILE *Stream;int fgetpos (Stream, Position)
FILE *Stream;
fpos_t *Position;int fsetpos (Stream, Position)
FILE *Stream;
const fpos_t *Position;
int fseeko ( Stream, Offset, Whence)
FILE *Stream;
off_t Offset;
int Whence;
int fseeko64 ( Stream, Offset, Whence)
FILE *Stream;
off64_t Offset;
int Whence;
off_t int ftello (Stream)
FILE *Stream;off64_t int ftello64 (Stream)
FILE *Stream;int fgetpos64 (Stream, Position)
FILE *Stream;
fpos64_t *Position;int fsetpos64 (Stream, Position)
FILE *Stream;
const fpos64_t *Position;
The fseek, fseeko and fseeko64 subroutines set the position of the next input or output operation on the I/O stream specified by the Stream parameter. The position if the next operation is determined by the Offset parameter, which can be either positive or negative.
The fseek, fseeko and fseeko64 subroutines set the file pointer associated with the specified Stream as follows:
The fseek, fseeko, and fseeko64 subroutine are unsuccessful if attempted on a file that has not been opened using the fopen (fopen, fopen64, freopen, freopen64, fopen_s or fdopen Subroutine) subroutine. In particular, the fseek subroutine cannot be used on a terminal or on a file opened with the popen (popen Subroutine) subroutine. The fseek and fseeko subroutines will also fail when the resulting offset is larger than can be properly returned.
The rewind subroutine is equivalent to calling the fseek subroutine using parameter values of (Stream,SEEK_SET,SEEK_SET), except that the rewind subroutine does not return a value. Do not use the rewind subroutine in situations where the fseek subroutine might fail (for example, when the fseek subroutine is used with buffered I/O streams). In this case, use the fseek subroutine, so error conditions can be checked.
The fseek, fseeko, fseeko64 and rewind subroutines undo any effects of the ungetc and ungetwc subroutines and clear the end-of-file (EOF) indicator on the same stream.
The fseek, fseeko, and fseeko64 function allows the file-position indicator to be set beyond the end of existing data in the file. If data is written later at this point, subsequent reads of data in the gap will return bytes of the value 0 until data is actually written into the gap.
A successful calls to the fsetpos or fsetpos64 subroutines clear the EOF indicator and undoes any effects of the ungetc and ungetwc subroutines.
After an fseek, fseeko, fseeko64 or a rewind subroutine, the next operation on a file opened for update can be either input or output.
ftell, ftello and ftello64 subroutines return the position current value of the file-position indicator for the stream pointed to by the Stream parameter. ftell and ftello will fail if the resulting offset is larger than can be properly returned.
The fgetpos and fgetpos64 subroutines store 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 and fsetpos64 set the file-position indicator for Stream according to the value of the Position parameter, which must be the result of a prior call to fgetpos or fgetpos64 subroutine. fgetpos and fsetpos will fail if the resulting offset is larger than can be properly returned.
| Item | Description |
|---|---|
| Stream | Specifies the input/output (I/O) stream. |
| Offset | Determines the position of the next operation. |
| Whence | Determines the value for the file pointer associated with the Stream parameter. |
| Position | Specifies the value of the file-position indicator. |
Upon successful completion, the fseek, fseeko and fseeko64 subroutine return a value of 0. Otherwise, it returns a value of -1.
Upon successful completion, the ftell, ftello and ftello64 subroutine return the offset of the current byte relative to the beginning of the file associated with the named stream. Otherwise, a long int value of -1 is returned and the errno global variable is set.
Upon successful completion, the fgetpos, fgetpos64, fsetpos and fsetpos64 subroutines return a value of 0. Otherwise, a nonzero value is returned and the errno global variable is set to the specific error.
If the fseek, fseeko, fseeko64, ftell, ftello, or ftello64 subroutines are unsuccessful because the stream is unbuffered or the stream buffer needs to be flushed and the call to the subroutine causes an underlying lseek or write subroutine to be invoked, it returns one or more of the following error codes:
| Item | Description |
|---|---|
| EAGAIN | Indicates that the O_NONBLOCK flag is set for the file descriptor, delaying the process in the write operation. |
| EBADF | Indicates that the file descriptor underlying the Stream parameter is not open for writing. |
| EFBIG | Indicates that an attempt has been made to write to a file that exceeds the file-size limit of the process or the maximum file size. |
| EFBIG | Indicates that the file is a regular file and that an attempt was made to write at or beyond the offset maximum associated with the corresponding stream. |
| EINTR | Indicates that the write operation has been terminated because the process has received a signal, and either no data was transferred, or the implementation does not report partial transfers for this file. |
| EIO | Indicates that the process is a member of a background process group attempting to perform a write subroutine to its controlling terminal, the TOSTOP flag is set, the process is not ignoring or blocking the SIGTTOU signal, and the process group of the process is orphaned. This error may also be returned under implementation-dependent conditions. |
| ENOSPC | Indicates that no remaining free space exists on the device containing the file. |
| EPIPE | Indicates that an attempt has been 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. |
| EINVAL | Indicates that the Whence parameter is not valid. The resulting file-position indicator will be set to a negative value. The EINVAL error code does not apply to the ftell and rewind subroutines. |
| ESPIPE | Indicates that the file descriptor underlying the Stream parameter is associated with a pipe, FIFO, or socket. |
| EOVERFLOW | Indicates that for fseek, the resulting file offset would be a value that cannot be represented correctly in an object of type long. |
| EOVERFLOW | Indicates that for fseeko, the resulting file offset would be a value that cannot be represented correctly in an object of type off_t. |
| ENXIO | Indicates that a request was made of a non-existent device, or the request was outside the capabilities of the device. |
The fgetpos and fsetpos subroutines are unsuccessful due to the following conditions:
| Item | Description |
|---|---|
| EINVAL | Indicates that either the Stream or the Position parameter is not valid. The EINVAL error code does not apply to the fgetpos subroutine. |
| EBADF | Indicates that the file descriptor underlying the Stream parameter is not open for writing. |
| ESPIPE | Indicates that the file descriptor underlying the Stream parameter is associated with a pipe, FIFO, or socket. |
The fseek, fseeko, ftell, ftello, fgetpos, and fsetpos subroutines are unsuccessful under the following condition:
| Item | Description |
|---|---|
| EOVERFLOW | The resulting could not be returned properly. |