fseek, fseek64, fseeko, fseeko64 - reposition file position indicator in stream

Syntax

#include <stdio.h>

int fseek(FILE *stream, long int offset, int whence);
int fseek64(FILE *stream, long long int offset, int whence);
int fseeko(FILE *stream, off_t offset, int whence);
int fseeko64(FILE *stream, off64_t offset, int whence); 

Description

When POSIX files are executed, the function behaves in conformance with XPG as described below:

fseek() sets the file position indicator for the stream pointed to by stream.

The new position, measured in bytes from the beginning of the file, is obtained by adding offset to the position specified by whence. The specified point is the beginning of the file for SEEK_SET, the current value of the file position indicator for SEEK_CUR, or end-of-file for SEEK_END.

If the stream is to be used with wide character input/output functions, offset must either be 0 or a value returned by an earlier call to ftell() on the same stream and whence must be SEEK_SET.

A successful call to fseek() clears the end-of-file indicator for the stream and undoes any effects of ungetc() and ungetwc() on the same stream. After an fseek() call, the next operation on a stream opened for an update may be either input or output.

If the most recent operation, other than ftell(), on a given stream is fflush(), the file offset in the underlying open file description will be adjusted to reflect the location specified by fseek().

fseek() 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 null bytes until data is actually written into the gap.

If the stream was opened for writing and buffered data has not yet been written to the underlying file, fseek() will cause the unwritten data to be written to the file and mark the st_ctime and st_mtime fields of the file for update.

The fseek64() function behaves like fseek() except that the offset type long long is used for fseek64().

There is no difference in functionality between fseeko() and fseeko64() except thatfseeko64() uses the off64_t structure.
The fseeko() function is the same as the modified fseek() function except that the offset argument is of type off_t and that the EOVERFLOW error has changed.

BS2000
The following must be noted when executing BS2000 files:

fseek() sets the file position indicator for the file associated with stream in accordance with the specifications in offset and whence. This allows files to be processed non-sequentially.

Text files (SAM in text mode, ISAM) can be positioned absolutely to the beginning or end of the file as well as to any position previously marked with ftell().

Binary files (SAM in binary mode, PAM, INCORE) can be positioned absolutely (see above) or relatively, i.e. relative to beginning of file, end of file, or current position (by a desired number of bytes).

The significance, combination options, and effects of the offset and whence parameters differ for text and binary files and are therefore discussed individually below:

Text files (SAM in text mode, ISAM)

Possible values:

offset	0L or value determined by a previous ftell call.
whence	SEEK_SET (beginning of file) SEEK_END (end of file)

Meaningful combinations and their effects:

offset	whence	Effect
ftell value	SEEK_SET	Position to the location marked by ftell()
0L	SEEK_SET	Position to the beginning of the file
0L	SEEK_END	Position to the end of the

Binary files (SAM in binary mode, PAM, INCORE)

Possible values:

Meaningful combinations and their effects:

offset	Number of bytes by which the current file position indicator is to be shifted. This number may be positive: position forwards toward the end of the file negative: position backwards toward the beginning of the file 0L: absolute positioning to the beginning or end of the file
whence	For absolute positioning to the beginning or end of the file, the location at which the file position indicator is to be set. For relative positioning, the reference point from which the file position indicator is to be moved by offset bytes: SEEK_SET (beginning of file) SEEK_CUR (current position) SEEK_END (end of file)

Meaningful combinations and their effects:

offset	whence	Effect
0L	SEEK_SET	Position to the beginning of the file.
0L	SEEK_END	Position to the end of the file.
positive number	SEEK_SET SEEK_CUR SEEK_END	Forward positioning from beginning of file, from current position, from end of file (beyond the end of file).
negative number	SEEK_CUR SEEK_END	Backward positioning from current position, from end of file.
ftell value	SEEK_SET	Position to the location marked by an ftell call.

Return val.

0

-1

if successful.

if the specified file cannot be positioned. errno is set to indicate the error.
An improper seek can be, for example, an fseek() done on a file that has not been opened via fopen(); in particular, fseek() may not be used on a terminal or on a file opened via popen(). After a stream is closed, no further operations are defined on that stream.

 

fseek() and fseeko() will fail if either the stream is unbuffered or the stream's buffer needed to be flushed, and the call to fseek() or fseeko() causes an underlying lseek() or write() to be invoked:

 

EAGAIN

The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the write operation.

 

EBADF

The file descriptor underlying stream is not open for writing or the stream's buffer needed to be flushed and the file is not open.

 

EFBIG

An attempt was made to write a file that exceeds the maximum file size or the process file size limit (see also ulimit()).

 

EINTR

The write operation was terminated due to the receipt of a signal, and no data was transferred.

EINVAL

The whence argument is invalid. The resulting file-position indicator would be set to a negative value.

EIO

An I/O error occurred.
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 the SIGTTOU signal, 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.

If threads are used, then the function affects the process or a thread in the following manner: If an EPIPE error occurs, the SIGPIPE signal is not sent to the process, but is sent to the calling thread instead.

ENXIO

The device does not exist or it cannot be accessed.

EOVERFLOW

For fseek(): The resulting file offset value cannot be represented correctly in an object of type long.

EOVERFLOW

For fseeko(): The resulting file offset value cannot be represented correctly in an object of type off_t.

Notes

For POSIX files, the file offset returned by ftell() is measured in bytes, and a seek to a position relative to that file offset is permissible; however, portability to other systems requires that a direct file offset (i.e. the value returned by ftell()) be used by fseek(). Arithmetic operations cannot always be meaningfully performed on any other file offset which may not necessarily be measured in bytes.

The program environment determines whether fseek() is executed for a BS2000 or POSIX file.

BS2000
The call fseek( stream,0L,SEEK_SET) is equivalent to the call rewind( stream ).

If new records are written to a text file that was opened in the write or append mode and an fseek call is issued, any data that may still be in the buffer is first written to the file and terminated with a newline character (\n).

Exception for ANSI functionality:
If the data of an ISAM file in the buffer does not end in a newline character, fseek() does not insert a change of line (or record). In other words, the data is not automatically terminated with a newline character when it is written from the buffer. Subsequent data extends the record in the file. Consequently, when an ISAM file is read, only the newline characters that were explicitly written by the program are read in.If a binary file is positioned past the end of file, a gap appears between the last physically stored data and the newly written data. Reading from this gap returns binary zeros.

It is not possible to position to system files (SYSDTA, SYSLST, SYSOUT).

A successful fseek() call deletes the EOF flag of the file and cancels all the effects of the preceding ungetc calls for that file.

In the case of record I/O, fseek() can be only be used for positioning to the beginning or end of the file.

fseek( stream,0L,SEEK_SET) positions on the first record of the file.

fseek( stream,0L,SEEK_END) positions after the last record of the file.

If fseek() is called with any other arguments, it will return EOF. 

See also

fopen(), fsetpos(), ftell(), lseek(), rewind(), tell(), ungetc(), stdio.h.