lseek, lseek64 - move read/write file offset

Syntax

Optional
#include <sys/types.h> (End)
#include <unistd.h>

off_t lseek (int fildes, off_t offset, int whence);
off64_t lseek64 (int fildes, off64_t offset, int whence);

 

Description

If POSIX files are executed, the behavior of this function conforms to the XPG standard as described below:

lseek() sets the file offset (i.e. the file position indicator) for the file with the file descriptor fildes as follows:

If whence is SEEK_SET, the file offset is set to offset bytes.

If whence is SEEK_CUR, the file offset is set to its current location plus offset.

If whence is SEEK_END, the file offset is set to the size of the file plus offset.

The symbolic constants SEEK_SET, SEEK_CUR and SEEK_END are defined in the header unistd.h.

The lseek() function has no effect when applied on a file that is incapable of seeking.

lseek() allows the file offset to be set beyond the end of the existing data in the file. If data is later written at this point, subsequent reads of data in the gap will return bytes with the value 0 until data is actually written into the gap.

lseek() will not, by itself, extend the size of a file.

There is no difference in functionality between lseek() and lseek64() except that lseek64() uses the offset type off64_t.

BS2000 The following must be noted when executing BS2000 files:

lseek() sets the file position indicator for the file with file descriptor fildes according to the specifications in offset and whence. This allows a file to be processed non-sequentially. The return value of lseek() is the current position in the file.

Text files (SAM, ISAM) can be positioned absolutely 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 are always processed as text files with elementary functions.

The significance, combination options, and effects of the offset and whence parameters differ for text and binary files and are therefore discussed individually below.

Text files (SAM, ISAM)

Possible values:

offset	0L or value determined by a previous tell/lseek call.
whence	SEEK_SET (beginning of file) SEEK_CUR (current position) SEEK_END (end of file)

Meaningful combinations and their effects:

offset	whence	Effect
tell/lseek value	SEEK_SET	Position to the location marked by tell() or lseek().
0L	SEEK_SET	Position to the beginning of the file.
0L	SEEK_CUR	Check current position without moving.
0L	SEEK_END	Position to the end of the file.

Binary files (PAM, INCORE)

Possible values:

offset	Number of bytes by which the current file position indicator 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 positioning to the beginning or end of the file
whence	For absolute positioning to the beginning or end of the file, the location at which the file position indicator is to be set. For relative positioning, the reference point from which the file position indicator is to be moved by offset bytes: SEEK_SET (beginning of file) SEEK_CUR (current position) SEEK_END (end of file)

Meaningful combinations and their effects:

offset	whence	Effect
0L	SEEK_SET	Position to the beginning of the file.
0L	SEEK_CUR	Check current position without moving.
0L	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.
tell/lseek value	SEEK_SET	Position to the location marked by a tell() or lseek call.

(End)

Return val.

New value of the file position indicator, measured in bytes from the beginning of the file, 

if successful.

 

(off_t) -1

if an error occurs; errno is set to indicate the error. The value of the file position indicator remains the same.

 

BS2000
New value of the file position indicator, measured in bytes from the beginning of the file, for binary files,

if successful.

 

Absolute position in text files, 

if successful. (End)

 

-1

if an error occurs.

Errors

lseek() and lseek64() will fail if: 

 

EBADF

fildes is not an open file descriptor.

 

EINVAL

whence is not a proper value, or the resulting file offset would be invalid.

 

ESPIPE

fildes is associated with a pipe or FIFO.

 

EOVERFLOW

The resulting file offset cannot be represented correctly in the structure pointed to by offset.

Notes

The program environment determines whether a BS2000 or POSIX file is created.

BS2000

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

If new records are written to a text file (opened for creation or in append mode) and an lseek call is issued, any data that may still be in the internal C 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, lseek() does not insert a change of line (or record). In other words, the data is not automatically terminated with a newline character when it is written from the buffer. Subsequent data extends the record in the file. Consequently, when an ISAM file is read, only the newline characters that were explicitly written by the program are read in.

If a binary file is positioned past the end of file, a gap appears between the last physically stored data and the newly written data. Reading from this gap returns binary zeros.

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

Since information on the file position is stored in a field that is 4 bytes long, the following restrictions apply to the size of SAM and ISAM files when processing them with tell()/lseek():

SAM file

Record length	<= 2048 bytes
Number of records/block	<= 256
Number of blocks	<= 2048

ISAM file

Record length	<= 32 KB
Number of records	<= 32 K

(End)

See also

fseek(), ftell(), open(), tell(), sys/types.h, unistd.h.