fseek, fseeko, fseek64, fseeko64 - Position read/write pointer

Definition

#include <stdio.h>

int fseek(FILE *fp, long offset, int loc);
int fseeko(FILE *fp, off_t offset; int loc);
int fseek64(FILE *fp, long long offset, int loc);
int fseeko64(FILE *fp, off64_t offset, int loc);

fseek and fseek64 position the read/write pointer for the file with file pointer fp in accordance with the specifications in offset and loc. It thus becomes possible for you to process a file 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/ftello or ftell64/ftello64.

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).

To process files > 2 GB, proceed as follows:

• If the _FILE_OFFSET_BITS 64 define (see "Support for DMS and UFS files > 2 GB") is set, call fseeko. fseeko64 is then used implicitly with the appropriate parameters. (Automatic conversion is not upported for fseek.)

• Otherwise, you have to call fseek64 or fseeko64.

There is no functional difference between fseek and fseek64 or fseeko and fseeko64. The functions differ only in terms of the offset type used.

Parameters

FILE *fp

File pointer for the file whose read/write pointer is to be positioned.

long offset / off_t offset / long long offset / off64_t offset

Since the meaning, combination options, and effect of these parameters differ for text and binary files, they are individually described in the following:

Text files (SAM in text mode, ISAM)

Possible parameter values:

offset	0L or value determined by a previous ftell/ftello call.
offset (64-bit interface)	0LL or value determined by a previous ftell/ftello/ftell64/ftello64 call.
loc	SEEK_SET (beginning of file) SEEK_END (end of file)

Meaningful combinations and their effects:

offset	loc	Effect
ftell/ftello value or ftell64/ftello64 value	SEEK_SET	Position to the location determined by ftell/ftello or ftell64/ftello64.
0L bzw. 0LL	SEEK_SET	Position to the beginning of the file..
0L bzw. 0LL	SEEK_END	Position to the end of the file.

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

Possible parameter values:

offset	Number of bytes by which the current read/write pointer 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 position to the beginning or end of the file.
loc	For absolute positioning to the beginning or end of the file, the position to which the read/write pointer is to be shifted. For relative positioning, the position from which the read/write pointer is to be shifted by offset bytes: SEEK_SET (beginning of file) SEEK_CUR (current position) SEEK_END (end of file)

Meaningful combinations and their effects:

offset	loc	Effect
0L or for 64 bit: 0LL	SEEK_SET	Position to the beginning of the file.
0L or for 64 bit: 0LL	SEEK_END	Position to the end of the file.
positive number	SEEK_SET	Forward positioning from beginning of file,
	SEEK_CUR	from current position,
	SEEK_END	from end of file (beyond the end of file).
negative number	SEEK_CUR	Backward positioning from current position,
	SEEK_END	from end of file.
ftell/ftello value or ftell64/ftello64 value	SEEK_SET	Position to the location marked by an ftell/ftello or ftell64/ftello64 call.

Return val.

0

if successful.

-1

if an error occurred.
If you position past the end of a binary file opened only for reading, errno is set to EMDS.

Hinweise

If new records are written to a text file that was opened in the write or append mode and an fseek/fseeko or fseek64/fseeko64 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/fseeko or fseek64/fseeko64 does not cause a change of line (or change of record), i.e. the data is not automatically terminated with a newline character when writing from the buffer. Subsequent data lengthens the record in the file. When an ISAM file is read, therefore, only those newline characters explicitly written by the program are read in.

If you position past the end of binary file opened for writing, a “gap” appears between the last physically stored data and the newly written data. Reading from this “gap” returns binary zeros.
If you position past the end of binary file opened for reading only, an error occurs (EMDS).

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

A successful fseek/fseeko or fseek64/fseeko64 call deletes the EOF flag of the file and cancels all the effects of the preceding ungetc calls for this file.

Record I/O

fseek/fseeko and fseek64/fseeko64 can be used only for positioning to the beginning or end of the file.

fseek(fp,0L,SEEK_SET) and fseek64(fp,0LL,SEEK_SET) position on the first record of the file.

fseeko(fp,0L,SEEK_SET) and fseeko64(fp,0LL,SEEK_SET) position on the first record of the file.

fseek(fp,0L,SEEK_END) and fseek64(fp,0LL,SEEK_SET) position after the last record of the file.

fseeko(fp,0L,SEEK_END) and fseeko64(fp,0LL,SEEK_SET) position after the last record of the file.

If called with any other arguments, fseek/fseeko and fseek64/fseeko64 return EOF.

Example 1

The following program reads file from the eleventh character to the end of the file (only functions for binary files).

#include <stdio.h>
int main(void)
{
  FILE *fp;
  int c;
  if((fp = fopen("file","rb")) != NULL)
  {
               /* skip the first 10 characters */
    fseek(fp,10L,SEEK_SET);
    while((c=getc(fp)) != EOF)
          putc((char)c,stdout);
    fclose(fp);
  }
  return 0;
}

Example 2

The following program processes a file in the update mode. Lowercase letters are written back as uppercase letters; all other characters remain unchanged.

#include <stdio.h>
#include <ctype.h>
int main(void)
{
   FILE *fp;
   int c;
   long n;
   fp = fopen("link=link","r+w");
     do
     {
       n = ftell(fp);
       c = getc(fp);
       if (islower(c) == 0) continue; /* If character is not in lowercase, */
                                      /* read next character */
      else
       {                              /* If character is in lowercase, */
         fseek(fp, n, SEEK_SET);      /* position to this character and */
         fputc((toupper(c)), fp);     /* write it back in uppercase. */
       }
     }
     while(c != EOF);
     fclose(fp);
     return 0;
}

See also

ftell, ftello, ftell64, ftello64, fsetpos, fsetpos64, lseek, lseek64, rewind, tell