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 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'.
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.
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 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 I/O Primitives) and to specify offsets for file locks (see Control Operations).
fseek function, specifies that the offset provided is relative to the beginning of the file.
fseek function, specifies that the offset provided is relative to the current file position.
fseek function, specifies that the offset provided is relative to the end of the file.
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 SEEK_SET .
L_INCR SEEK_CUR .
L_XTND SEEK_END .