Standards / Extensions | C or C++ | Dependencies |
---|---|---|
ISO C |
both |
#include <stdio.h>
int fseek(FILE *stream, long int offset, int origin);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
int fseek_unlocked(FILE *stream, long int offset, int origin);
The fseek() function changes the current file position associated with stream to a new location within the file. The next operation on the stream takes place at the new location. On a stream opened for update, the next operation can be either a reading or a writing operation.
If successful, the fseek() function clears the EOF indicator, even when origin is SEEK_END, and cancels the effect of any preceding ungetc() or ungetwc() function on the same stream.
If the call to the fseek() function or the fsetpos() function is not valid, the call is treated as a flush and the ungetc characters are discarded.
Behavior for binary streams: ANSI states that binary streams use relative byte offsets for both the ftell() and fseek() functions. Under z/OS® XL C/C++, this is true except for record-oriented files that have variable length records. For these types of files, the default behavior is to use encoded offsets for the ftell() function and the fseek() function using an origin of SEEK_SET.
Encoded offsets restrict you to seeking only to those positions that are recorded by a previous ftell() function call or to position 0. If you want to use relative-byte offsets for these types of files, you can either open the file with the BYTESEEK fopen() function option or set the _EDC_BYTE_SEEK environment variable before opening.
With relative-byte offsets, you can calculate your own offsets. If the offset exceeds the EOF, your file is extended with NULLs, except for z/OS UNIX files, for which the file is only extended with NULLs if you subsequently write new data. This is true also under POSIX, using z/OS UNIX files, where the file is only extended with NULLs if you subsequently write new data.
Attempting to reposition to before the start of the file causes the fseek() function to fail.
Regardless of whether encoded or relative offsets are returned by the ftell() function, you can specify relative offsets when using SEEK_CUR and SEEK_END.
If the new position is before the start of the file, the fseek() function fails. If the relative offset is positioned beyond the EOF, the file is padded with NULLs, except in the case of POSIX, using z/OS UNIX files, where padding does not occur until a subsequent write of new data.
Behavior for text streams: For text streams, the ftell() function returns an encoded offset. When seeking with an origin of SEEK_SET, you are restricted to seeking only to 0 or to positions returned by a previous ftell() function call.
Attempting to calculate your own position is not supported, and might result in a non-valid position and the failure of the fseek() function.
When you are using SEEK_CUR or SEEK_END, the offset is a relative byte offset. Attempting to seek to before the start of the file or past the EOF results in failure.
Behavior for record I/O: For files opened for record I/O using the type=record open mode parameter, the ftell() function returns the relative record number. For the origins of SEEK_SET, SEEK_CUR, and SEEK_END, the offset is a relative record number.
Attempting to seek to before the first record or past the EOF results in failure.
Behavior for blocked I/O: For files opened for blocked I/O using the type=blocked open mode parameter, the ftell() function returns the relative block number. For the origins of SEEK_SET, SEEK_CUR, and SEEK_END, the offset is a relative block number.
Attempting to seek to before the first block or past the EOF results in failure.
Behavior for wide-oriented streams: All of the above restrictions apply for wide-oriented streams of any type.
Multivolume data sets performance: Using the fgetpos() and fsetpos() functions generally results in better repositioning performance compared to the ftell() and fseek() functions when working with multivolume data sets.
Large file support for MVS data sets, VSAM data sets, and z/OS UNIX files: For AMODE 31 C/C++ applications, the fseek() function accepts a signed 4-byte offset and therefore cannot be used to directly or relatively position to offsets beyond 2 GB - 1. To avoid repositioning limitations, AMODE 31 C/C++ applications should define the _LARGE_FILES feature test macro before any headers are included and replace the fseek() function with the fseeko() function. For AMODE 64 C/C++ applications, there are no restrictions on using the fseek() function with large files. The AMODE 64 version automatically accepts a signed 8-byte offset.
If successful in moving the pointer, the fseek() function returns 0.
If unsuccessful, or on devices that cannot seek, such as terminals and printers, the fseek() function returns nonzero.
/* This example opens a file myfile.dat for reading.
After performing input operations (not shown), it moves the file
pointer to the beginning of the file.
*/
#include <stdio.h>
int main(void)
{
FILE *stream;
int result;
if (stream = fopen("myfile.dat", "r"))
{ /* successful */
if (fseek(stream, 0L, SEEK_SET)); /* moves pointer to */
/* the beginning of the file */
{ /* if not equal to 0
then error ... */
}
else {
/* fseek() successful */
}
}