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 tell/lseek call.
0LL or value determined by a previous seek64 call. | offset
(64-bit interface) | 0LL or value determined by a previous ftell/ftell64 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 OL: 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 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 Byte | Number of records/block | <= 256 | Number of blocks | <= 2048 |
ISAM file Record length | <= 32 KByte | 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 |
