| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
Single UNIX Specification, Version 2 |
both | OS/390 V2R10 |
#define _XOPEN_SOURCE 500
#include <stdio.h>
int fseeko(FILE *stream, off_t offset, int origin);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
int fseeko_unlocked(FILE *stream, off_t offset, int origin);The fseeko() 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 fseeko() function clears the EOF indicator, even when the origin is SEEK_END, and cancels the effect of any preceding ungetc() or ungetwc() function on the same stream.
If the call to the fseeko() 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 ftello() and fseeko() 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 ftello() function and the fseeko() function using an origin of SEEK_SET.
Encoded offsets restrict you to seeking only to those positions that are recorded by a previous ftello() 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 fseeko() function to fail.
Regardless of whether encoded or relative offsets are returned by the ftello() 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 fseeko() 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 ftello() 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 ftello() function call.
Attempting to calculate your own position is not supported, and might result in a non-valid position and the failure of the fseeko() 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 ftello() 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 ftello() 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 ftello() and fseeko() 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 fseeko() 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. For AMODE 64 C/C++ applications, there are no restrictions on using the fseeko() function with large files. The AMODE 64 version automatically accepts a signed 8-byte offset.
If successful, fseeko() returns 0, which means it successfully moved the pointer.
If unsuccessful, fseeko() returns nonzero and sets errno to one of the following values.
/* 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.
*/
#define _LARGE_FILES 1
#include <stdio.h>
int main(void)
{
FILE *stream;
int result;
if (stream = fopen("/myfile.dat", "r"))
{ /* successful */
if (fseeko(stream, 0LL, SEEK_SET)); /* moves pointer to */
/* the beginning of the file */
{ /* if not equal to 0
then error ... */
}
else {
/* fseeko() successful */
}
}