lseek

OS/161 Reference Manual

Name

lseek - change current position in file

Library

Standard C Library (libc, -lc)

Synopsis

#include <unistd.h>

off_t
lseek(int fd, off_t pos, int whence);

Description

lseek alters the current seek position of the file handle filehandle, seeking to a new position based on pos and whence.

If whence is

• SEEK_SET, the new position is pos.
• SEEK_CUR, the new position is the current position plus pos.
• SEEK_END, the new position is the position of end-of-file plus pos.
• anything else, lseek fails.

It is not meaningful to seek on certain objects, such as the console device. All seeks on these objects fail.

Seek positions less than zero are invalid. Seek positions beyond EOF are legal, at least on regular files.

As discussed under getdirentry, seek positions on directories are defined by the file system and should not be interpreted.

Note that each distinct open of a file should have an independent seek pointer.

lseek (like all system calls) should be atomic. In this case this means that multiple threads or processes sharing the same seek pointer should be able to update it without seeing or generating invalid intermediate states. There is no provision for making pairs of lseek and read or write calls atomic. The pread and pwrite calls in Unix were invented to address this issue. (These are not in OS/161 by default but are easy to implement.)

Return Values

On success, lseek returns the new position. On error, -1 is returned, and errno is set according to the error encountered.

Errors

The following error codes should be returned under the conditions given. Other error codes may be returned for other cases not mentioned here.

	EBADF	fd is not a valid file handle.
	ESPIPE	fd refers to an object which does not support seeking.
	EINVAL	whence is invalid.
	EINVAL	The resulting seek position would be negative.