fseek(3) — Subroutines
OSF
NAME
fseek, rewind, ftell, fgetpos, fsetpos − Repositions the file pointer of a stream
LIBRARY
Standard I/O Package (libc.a)
SYNOPSIS
#include <stdio.h>
int fseek (
FILE ∗stream,
long int offset,
int whence );
void rewind (
FILE ∗stream );
long int ftell (
FILE ∗stream ); int fsetpos (
FILE ∗stream,
const fpos_t ∗position );
int fgetpos (
FILE ∗stream,
fpos_t ∗position );
PARAMETERS
streamSpecifies the I/O stream.
offsetDetermines the position of the next operation.
whenceDetermines the value for the file pointer associated with the stream parameter.
positionSpecifies the value of the file position indicator.
DESCRIPTION
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_SET(1), the pointer is set to its current location plus the value of the offset parameter.
•If the whence parameter is SEEK_SET(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 End-of-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.
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 fseek() function does not, by itself, extend the size of a file.
The rewind() function is equivalent to (void) fseek (stream, 0L, SEEK_SET), except that it 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, 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.
NOTES
AES Support Level:
Full use
RETURN VALUES
Upon successful completion, the fseek() function returns a value of 0 (zero). If the fseek() function fails, a value of -1 is returned and errno is set to indicate the error.
The rewind() function does not return a value.
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, -1 is returned and errno is set to indicate the error.
Upon successful completion, the fgetpos() and fsetpos() functions return 0 (zero). If the fgetpos() or the fsetpos() function fails, a value of -1 is returned and errno is set to [EINVAL].
ERRORS
The fseek() function fails if either the stream is unbuffered, or the stream’s buffer needed to be flushed and the call to fseek() caused an underlying lseek() or write() function to be invoked. In addition, if the fseek() function fails, errno may be set to one of the following values:
[EAGAIN]The O_NONBLOCK flag is set for the file descriptor underlying the stream parameter and the process would be delayed in the write operation.
[EBADF]The file descriptor underlying the stream parameter is not a valid file descriptor open for writing.
[EFBIG]An attempt was made to write to a file that exceeds the process’ file size limit or the maximum file size. See the ulimit() function.
[EINTR]The read operation was interrupted by a signal which was caught, and no data was transferred.
[EIO]The process is a member of a background process group attempting to 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.
[ENOSPC]There was no free space remaining on the device containing the file.
[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 also be sent to the process.
The rewind() and ftell() functions fail under the same conditions as the fseek() function, with the exception of [EINVAL], which does not apply.
If the fgetpos() or fsetpos() function fails, errno may be set to the following value:
[EINVAL]The stream parameter does not point to a valid FILE structure.