fseek, fseeko, fseeko64, rewind, ftell, ftello, ftello64, fgetpos, fgetpos64, fsetpos, or fsetpos64 Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

fseek, fseeko, fseeko64, rewind, ftell, ftello, ftello64, fgetpos, fgetpos64, fsetpos, or fsetpos64 Subroutine

Purpose

Repositions the file pointer of a stream.

Library

Standard C Library (libc.a)

Syntax

#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;

Note: The fseeko, fseeko64, ftello, ftello64, fgetpos64, and fsetpot64 subroutines apply to Version 4.2 and later releases.

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;

Description

Note: The fseeko, fseeko64, ftello, ftello64, fgetpos64, and fsetpot64 subroutines apply to Version 4.2 and later releases.

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:

If the Whence parameter is set to the SEEK_SET value, the pointer is set to the value of the Offset parameter.
If the Whence parameter is set to the SEEK_CUR value, the pointer is set to its current location plus the value of the Offset parameter.
If the Whence parameter is set to the SEEK_END value, the pointer is set to the size of the file plus the value of the Offset parameter.

The fseek, fseeko, and fseeko64 subroutine are unsuccessful if attempted on a file that has not been opened using the fopen subroutine. In particular, the fseek subroutine cannot be used on a terminal or on a file opened with the popen 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.

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.

Parameters

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.

Return Values

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.

The errno global variable is used to determine if an error occurred during a rewind subroutine call.

Error Codes

If the fseek, fseeko, fseeko64, ftell, ftello, ftello64 or rewind subroutine 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:

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 or FIFO.
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:

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 or FIFO.

The fseek, fseeko, ftell, ftello, fgetpos, and fsetpos subroutines are unsucessful under the following condition:

EOVERFLOW

The resulting could not be returned properly.

Implementation Specifics

These subroutines are part of Base Operating system (BOS) Runtime.

Related Information

The closedir subroutine, fopen, fopen64, freopen, freopen64 or fdopen subroutine, lseek or lseek64 subroutine, opendir, readdir, rewinddir, seekdir, or telldir subroutine, popen subroutine, ungetc or ungetwc subroutine, write, writex, writev, or writevx subroutine.

Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.