OS/161 Reference Manual


lseek - change current position in file


Standard C Library (libc, -lc)


#include <unistd.h>

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


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

If whence is

Note that pos is a signed quantity.

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.


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.