Debian Codegraph @

upstream/debian-unstable/man2/lseek.2

raw
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)