lseek, lseek64 - Position read/write pointer (elementary)

Definition

#include <stdio.h>

off__t lseek(int fd, off_t offset, int loc);
off64_t lseek64(int fd, off64_t offset, int loc);

lseek and lseek64 position the read/write pointer for the file with file descriptor fd according to the specifications in offset and loc. It is thus possible for you to process a file non-sequentially. The return value from lseek and lseek64 is the current position in the file.

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 lseek. lseek64 is then used implicitly with the appropriate parameters.

• Otherwise, you have to call lseek64.

There is no functional difference between lseek and lseek64, except that the offset type off64_t and the return type off64_t are used for lseek64.

Text files (SAM, ISAM) can be absolutely positioned to the beginning or end of the file as well as to any position previously marked with tell.

Binary files (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). SAM files are always processed as text files with elementary text functions.

SAM files are processed as text files with elementary functions except when O_RECORD was specified for open.

Parameters 

int fd

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

off_t / off64_t offset, int loc

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

Text files (SAM, ISAM)

Possible parameter values:

offset	0L or value determined by a previous ftell/tell/lseek call.
offset (64-bit interface)	0LL or value determined by a previous ftell64/lseek64 call.
loc	SEEK_SET (beginning of file) SEEK_CUR (current position) SEEK_END (end of file)

Meaningful combinations and their effects

distanz	ort	Wirkung
tell/lseek-Wert or lseek64-Wert	SEEK_SET	Position to the location marked by tell or lseek/lseek64.
0L or 0LL	SEEK_SET	Position to the beginning of the file.
0L or 0LL	SEEK_CUR	Query current position without positioning.
0L or 0LL	SEEK_END	Position to the end of the file.

Binary files(PAM, INCORE)

Possible parameter values:

offset	Number of bytes by which the current read/write pointer is to be shifted. This number may be a positive number: forward positioning toward end of file negative number: backward positioning toward beginning of file 0L or 0LL: absolute positioning to beginning or end of file.
ort	For absolute positioning to the beginning or end of the file, the point to which the read/write pointer is to be shifted. For relative positioning, the point 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	Effects
0L or 0LL	SEEK_SET	Position to the beginning of the file.
0L or 0LL	SEEK_CUR	Query current position without positioning.
0L or 0LL	SEEK_END	Position to the end of the file.
positive number	SEEK_SET SEEK_CUR SEEK_END	Forward positioning from beginning of file, from current position, from end of file (beyond the end of file).
negative number	SEEK_CUR SEEK_END	Backward positioning from current position, from end of file.
tell/lseek value or lseek64 value	SEEK_SET	Position to the location marked by tell orlseek/lseek64.

Return val.

The position in the file if successful, i.e.

for binary files, the number of bytes that offsets the read/write pointer from the beginning of the file;
for text files, the absolute position of the read/write pointer.

-1

if an error occurs. In addition, the corresponding error information is stored in the errno variable:
EBADF: Invalid file descriptor
ESPIPE: Invalid positioning
EINVAL: Invalid argument.
EMDS: For binary file opened for reading only, positioned after the end of the file.

Notes

The lseek(fd, 0L, SEEK_CUR) and tell(fd) calls are equivalent, i.e. they both call the current position in the file without positioning it.

If new records are written to a text file (opened for creation or in append mode) and an lseek/lseek64 call is issued, any residual data is first written from the internal C buffer 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, lseek/lseek64 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 file in the case of a 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 a binary file opened for reading only, an error occurs (EMDS).

System files (SYSDTA, SYSLST, SYSOUT) cannot be positioned.

Since information on the file position is combined in a single field, the following restrictions apply to the size of SAM and ISAM files:

SAM file

	lseek()	lseek64()
Record length	<= 2048 bytes	<= 32 KByte
Number of records/block	<= 255	< 32 K
Number of blocks	<= 2047	-

ISAM file

	lseek()	lseek64()
Record length	<= 32 KBytes	<= 32 KBytes
Number of records	< 32 K	-

Record I/O

lseek and lseek64 can only be used to position to start of or end of file.

lseek(dk,0L,SEEK_SET) or lseek64(dk,0LL,SEEK_SET) positions to the first record of the file.

lseek(dk,0L,SEEK_END) or lseek64(dk,0LL,SEEK_SET) positions behind the last record of the file.
In the case of calls with other arguments, fseek/fseeko and fseek64/fseeko64 return EOF.

Example

The following program reads the file passed as the first argument in the call from position 10 onwards and appends its contents to the end of another file if a second argument is specified. Otherwise, it writes to the standard output (only works with binary files, i.e. with PAM files in this case):

#include <stdio.h>
#include <stdlib>
int fd1, fd2;
long result;
char c;
int main(int argc, char *argv[])
{
  if((fd1 = open (argv[1],0)) < 0) exit(1);
  if(argc < 3)
          fd2 = 1;
  else
          fd2 = open(argv[2], 1);
  result = lseek(fd1, 10L, SEEK_SET);
  printf("current position in file1 : %ld\n", tell(fd1));
  /* Other possible position queries:
  printf("current position in file1: %ld\n, result);
  printf("current position in file1: %ld\n, lseek(fd1, 0L, SEEK_CUR)); */
  while(read(fd1, &c, 1) > 0)
          write(fd2, &c, 1);
  close(fd1);
  close(fd2);
}

See also

tell, fseek, fseek64, ftell, ftell64