File Positioning

The file position of a stream describes where in the file the stream is currently reading or writing. I/O on the stream advances the file position through the file. In the GNU system, the file position is represented as an integer, which counts the number of bytes from the beginning of the file. See section File Position.

During I/O to an ordinary disk file, you can change the file position whenever you wish, so as to read or write any portion of the file. Some other kinds of files may also permit this. Files which support changing the file position are sometimes referred to as random-access files.

You can use the functions in this section to examine or modify the file position indicator associated with a stream. The symbols listed below are declared in the header file `stdio.h'.

Function: long int ftell (FILE *stream)

This function returns the current file position of the stream stream.

This function can fail if the stream doesn't support file positioning, or if the file position can't be represented in a long int, and possibly for other reasons as well. If a failure occurs, a value of -1 is returned.

Function: int fseek (FILE *stream, long int offset, int whence)

The fseek function is used to change the file position of the stream stream. The value of whence must be one of the constants SEEK_SET, SEEK_CUR, or SEEK_END, to indicate whether the offset is relative to the beginning of the file, the current file position, or the end of the file, respectively.

This function returns a value of zero if the operation was successful, and a nonzero value to indicate failure. A successful call also clears the end-of-file indicator of stream and discards any characters that were "pushed back" by the use of ungetc.

fseek either flushes any buffered output before setting the file position or else remembers it so it will be written later in its proper place in the file.

Portability Note: In non-POSIX systems, ftell and fseek might work reliably only on binary streams. See section Text and Binary Streams.

The following symbolic constants are defined for use as the whence argument to fseek. They are also used with the lseek function (see section Input and Output Primitives) and to specify offsets for file locks (see section Control Operations on Files).

Macro: int SEEK_SET

This is an integer constant which, when used as the whence argument to the fseek function, specifies that the offset provided is relative to the beginning of the file.

Macro: int SEEK_CUR

This is an integer constant which, when used as the whence argument to the fseek function, specifies that the offset provided is relative to the current file position.

Macro: int SEEK_END

This is an integer constant which, when used as the whence argument to the fseek function, specifies that the offset provided is relative to the end of the file.

Function: void rewind (FILE *stream)

The rewind function positions the stream stream at the begining of the file. It is equivalent to calling fseek on the stream with an offset argument of 0L and a whence argument of SEEK_SET, except that the return value is discarded and the error indicator for the stream is reset.

These three aliases for the `SEEK_...' constants exist for the sake of compatibility with older BSD systems. They are defined in two different header files: `fcntl.h' and `sys/file.h'.

L_SET

An alias for SEEK_SET.

L_INCR

An alias for SEEK_CUR.

L_XTND

An alias for SEEK_END.

Go to the first, previous, next, last section, table of contents.