| 1 |
.\" Copyright 1980-1991, Regents of the University of California. |
| 2 |
.\" Copyright 2011, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: BSD-4-Clause-UC |
| 6 |
.\" |
| 7 |
.TH lseek 2 2026-02-11 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
lseek \- reposition read/write file offset |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.B #include <unistd.h> |
| 16 |
.P |
| 17 |
.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); |
| 18 |
.fi |
| 19 |
.SH DESCRIPTION |
| 20 |
.BR lseek () |
| 21 |
repositions the file offset of the open file description |
| 22 |
associated with the file descriptor |
| 23 |
.I fd |
| 24 |
to the argument |
| 25 |
.I offset |
| 26 |
according to the directive |
| 27 |
.I whence |
| 28 |
as follows: |
| 29 |
.TP |
| 30 |
.B SEEK_SET |
| 31 |
The file offset is set to |
| 32 |
.I offset |
| 33 |
bytes. |
| 34 |
.TP |
| 35 |
.B SEEK_CUR |
| 36 |
The file offset is set to its current location plus |
| 37 |
.I offset |
| 38 |
bytes. |
| 39 |
.TP |
| 40 |
.B SEEK_END |
| 41 |
The file offset is set to the size of the file plus |
| 42 |
.I offset |
| 43 |
bytes. |
| 44 |
.P |
| 45 |
.BR lseek () |
| 46 |
allows the file offset to be set beyond the end |
| 47 |
of the file (but this does not change the size of the file). |
| 48 |
If data is later written at this point, subsequent reads of the data |
| 49 |
in the gap (a "hole") return null bytes (\[aq]\[rs]0\[aq]) until |
| 50 |
data is actually written into the gap. |
| 51 |
.SS Seeking file data and holes |
| 52 |
Since Linux 3.1, Linux supports the following additional values for |
| 53 |
.IR whence : |
| 54 |
.TP |
| 55 |
.B SEEK_DATA |
| 56 |
Adjust the file offset to the next location |
| 57 |
in the file greater than or equal to |
| 58 |
.I offset |
| 59 |
containing data. |
| 60 |
If |
| 61 |
.I offset |
| 62 |
points to data, |
| 63 |
then the file offset is set to |
| 64 |
.IR offset . |
| 65 |
.TP |
| 66 |
.B SEEK_HOLE |
| 67 |
Adjust the file offset to the next hole in the file |
| 68 |
greater than or equal to |
| 69 |
.IR offset . |
| 70 |
If |
| 71 |
.I offset |
| 72 |
points into the middle of a hole, |
| 73 |
then the file offset is set to |
| 74 |
.IR offset . |
| 75 |
If there is no hole past |
| 76 |
.IR offset , |
| 77 |
then the file offset is adjusted to the end of the file |
| 78 |
(i.e., there is an implicit hole at the end of any file). |
| 79 |
.P |
| 80 |
In both of the above cases, |
| 81 |
.BR lseek () |
| 82 |
fails if |
| 83 |
.I offset |
| 84 |
points past the end of the file. |
| 85 |
.P |
| 86 |
These operations allow applications to map holes in a sparsely |
| 87 |
allocated file. |
| 88 |
This can be useful for applications such as file backup tools, |
| 89 |
which can save space when creating backups and preserve holes, |
| 90 |
if they have a mechanism for discovering holes. |
| 91 |
.P |
| 92 |
For the purposes of these operations, a hole is a sequence of zeros that |
| 93 |
(normally) has not been allocated in the underlying file storage. |
| 94 |
However, a filesystem is not obliged to report holes, |
| 95 |
so these operations are not a guaranteed mechanism for |
| 96 |
mapping the storage space actually allocated to a file. |
| 97 |
(Furthermore, a sequence of zeros that actually has been written |
| 98 |
to the underlying storage may not be reported as a hole.) |
| 99 |
In the simplest implementation, |
| 100 |
a filesystem can support the operations by making |
| 101 |
.B SEEK_HOLE |
| 102 |
always return the offset of the end of the file, |
| 103 |
and making |
| 104 |
.B SEEK_DATA |
| 105 |
always return |
| 106 |
.I offset |
| 107 |
(i.e., even if the location referred to by |
| 108 |
.I offset |
| 109 |
is a hole, |
| 110 |
it can be considered to consist of data that is a sequence of zeros). |
| 111 |
.\" https://lkml.org/lkml/2011/4/22/79 |
| 112 |
.\" http://lwn.net/Articles/440255/ |
| 113 |
.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data |
| 114 |
.P |
| 115 |
The |
| 116 |
.B _GNU_SOURCE |
| 117 |
feature test macro must be defined in order to obtain the definitions of |
| 118 |
.B SEEK_DATA |
| 119 |
and |
| 120 |
.B SEEK_HOLE |
| 121 |
from |
| 122 |
.IR <unistd.h> . |
| 123 |
.P |
| 124 |
The |
| 125 |
.B SEEK_HOLE |
| 126 |
and |
| 127 |
.B SEEK_DATA |
| 128 |
operations are supported for the following filesystems: |
| 129 |
.IP \[bu] 3 |
| 130 |
Btrfs (since Linux 3.1) |
| 131 |
.IP \[bu] |
| 132 |
OCFS (since Linux 3.2) |
| 133 |
.\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 |
| 134 |
.IP \[bu] |
| 135 |
XFS (since Linux 3.5) |
| 136 |
.IP \[bu] |
| 137 |
ext4 (since Linux 3.8) |
| 138 |
.IP \[bu] |
| 139 |
.BR tmpfs (5) |
| 140 |
(since Linux 3.8) |
| 141 |
.IP \[bu] |
| 142 |
NFS (since Linux 3.18) |
| 143 |
.\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 |
| 144 |
.\" commit 24bab491220faa446d945624086d838af41d616c |
| 145 |
.IP \[bu] |
| 146 |
FUSE (since Linux 4.5) |
| 147 |
.\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 |
| 148 |
.IP \[bu] |
| 149 |
GFS2 (since Linux 4.15) |
| 150 |
.\" commit 3a27411cb4bc3ce31db228e3569ad01b462a4310 |
| 151 |
.SH RETURN VALUE |
| 152 |
Upon successful completion, |
| 153 |
.BR lseek () |
| 154 |
returns the resulting offset location as measured in bytes from the |
| 155 |
beginning of the file. |
| 156 |
On error, the value |
| 157 |
.I (off_t)\ \-1 |
| 158 |
is returned and |
| 159 |
.I errno |
| 160 |
is set to indicate the error. |
| 161 |
.SH ERRORS |
| 162 |
.TP |
| 163 |
.B EBADF |
| 164 |
.I fd |
| 165 |
is not an open file descriptor. |
| 166 |
.TP |
| 167 |
.B EINVAL |
| 168 |
.I whence |
| 169 |
is not valid. |
| 170 |
Or: the resulting file offset would be negative, |
| 171 |
or beyond the end of a seekable device. |
| 172 |
.\" Some systems may allow negative offsets for character devices |
| 173 |
.\" and/or for remote filesystems. |
| 174 |
.TP |
| 175 |
.B ENXIO |
| 176 |
.I whence |
| 177 |
is |
| 178 |
.B SEEK_DATA |
| 179 |
or |
| 180 |
.BR SEEK_HOLE , |
| 181 |
and |
| 182 |
.I offset |
| 183 |
is beyond the end of the file, or |
| 184 |
.I whence |
| 185 |
is |
| 186 |
.B SEEK_DATA |
| 187 |
and |
| 188 |
.I offset |
| 189 |
is within a hole at the end of the file. |
| 190 |
.TP |
| 191 |
.B EOVERFLOW |
| 192 |
.\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) |
| 193 |
The resulting file offset cannot be represented in an |
| 194 |
.IR off_t . |
| 195 |
.TP |
| 196 |
.B ESPIPE |
| 197 |
.I fd |
| 198 |
is associated with a pipe, socket, or FIFO. |
| 199 |
.SH VERSIONS |
| 200 |
On Linux, using |
| 201 |
.BR lseek () |
| 202 |
on a terminal device fails with the error |
| 203 |
.BR ESPIPE . |
| 204 |
.\" Other systems return the number of written characters, |
| 205 |
.\" using SEEK_SET to set the counter. (Of written characters.) |
| 206 |
.SH STANDARDS |
| 207 |
POSIX.1-2024. |
| 208 |
.SH HISTORY |
| 209 |
4.3BSD, |
| 210 |
SVr4, |
| 211 |
POSIX.1-1988. |
| 212 |
.TP |
| 213 |
.B SEEK_DATA |
| 214 |
.TQ |
| 215 |
.B SEEK_HOLE |
| 216 |
Solaris 10, |
| 217 |
FreeBSD 7.0, |
| 218 |
DragonFly BSD 2.3.1, |
| 219 |
POSIX.1-2024. |
| 220 |
.SH NOTES |
| 221 |
See |
| 222 |
.BR open (2) |
| 223 |
for a discussion of the relationship between file descriptors, |
| 224 |
open file descriptions, and files. |
| 225 |
.P |
| 226 |
If the |
| 227 |
.B O_APPEND |
| 228 |
file status flag is set on the open file description, |
| 229 |
then a |
| 230 |
.BR write (2) |
| 231 |
.I always |
| 232 |
moves the file offset to the end of the file, regardless of the use of |
| 233 |
.BR lseek (). |
| 234 |
.P |
| 235 |
Some devices are incapable of seeking and POSIX does not specify which |
| 236 |
devices must support |
| 237 |
.BR lseek (). |
| 238 |
.SH SEE ALSO |
| 239 |
.BR dup (2), |
| 240 |
.BR fallocate (2), |
| 241 |
.BR fork (2), |
| 242 |
.BR open (2), |
| 243 |
.BR fseek (3), |
| 244 |
.BR lseek64 (3), |
| 245 |
.BR posix_fallocate (3) |