## 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.

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.

### 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.