]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
1e0819c8 | 2 | .\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
3 | .\" All rights reserved. |
4 | .\" | |
47009d5e | 5 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
6 | .\" |
7 | .\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 | |
8 | .\" | |
9 | .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> | |
10 | .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl> | |
11 | .\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com> | |
12 | .\" Modified 1998-01-17 by Michael Haardt | |
13 | .\" <michael@cantor.informatik.rwth-aachen.de> | |
14 | .\" Modified 2001-09-24 by Michael Haardt <michael@moria.de> | |
15 | .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl> | |
1e0819c8 | 16 | .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE |
fea681da | 17 | .\" |
4c1c5274 | 18 | .TH lseek 2 (date) "Linux man-pages (unreleased)" |
fea681da MK |
19 | .SH NAME |
20 | lseek \- reposition read/write file offset | |
c0d4cde6 AC |
21 | .SH LIBRARY |
22 | Standard C library | |
8fc3b2cf | 23 | .RI ( libc ", " \-lc ) |
fea681da | 24 | .SH SYNOPSIS |
c7db92b9 | 25 | .nf |
fea681da | 26 | .B #include <unistd.h> |
c6d039a3 | 27 | .P |
47752f33 | 28 | .BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); |
c7db92b9 | 29 | .fi |
fea681da | 30 | .SH DESCRIPTION |
e511ffb6 | 31 | .BR lseek () |
67436769 | 32 | repositions the file offset of the open file description |
14a9ad49 | 33 | associated with the file descriptor |
47752f33 | 34 | .I fd |
fea681da MK |
35 | to the argument |
36 | .I offset | |
37 | according to the directive | |
38 | .I whence | |
39 | as follows: | |
40 | .TP | |
41 | .B SEEK_SET | |
e2b89c5c | 42 | The file offset is set to |
fea681da MK |
43 | .I offset |
44 | bytes. | |
45 | .TP | |
46 | .B SEEK_CUR | |
e2b89c5c | 47 | The file offset is set to its current location plus |
fea681da MK |
48 | .I offset |
49 | bytes. | |
50 | .TP | |
51 | .B SEEK_END | |
e2b89c5c | 52 | The file offset is set to the size of the file plus |
fea681da MK |
53 | .I offset |
54 | bytes. | |
c6d039a3 | 55 | .P |
e511ffb6 | 56 | .BR lseek () |
67436769 | 57 | allows the file offset to be set beyond the end |
2374c178 | 58 | of the file (but this does not change the size of the file). |
fea681da | 59 | If data is later written at this point, subsequent reads of the data |
b957f81f | 60 | in the gap (a "hole") return null bytes (\[aq]\e0\[aq]) until |
2374c178 | 61 | data is actually written into the gap. |
1e0819c8 | 62 | .SS Seeking file data and holes |
b324e17d | 63 | Since Linux 3.1, Linux supports the following additional values for |
1e0819c8 MK |
64 | .IR whence : |
65 | .TP | |
66 | .B SEEK_DATA | |
67 | Adjust the file offset to the next location | |
68 | in the file greater than or equal to | |
69 | .I offset | |
70 | containing data. | |
71 | If | |
72 | .I offset | |
73 | points to data, | |
74 | then the file offset is set to | |
75 | .IR offset . | |
76 | .TP | |
77 | .B SEEK_HOLE | |
78 | Adjust the file offset to the next hole in the file | |
79 | greater than or equal to | |
80 | .IR offset . | |
81 | If | |
82 | .I offset | |
83 | points into the middle of a hole, | |
84 | then the file offset is set to | |
85 | .IR offset . | |
86 | If there is no hole past | |
87 | .IR offset , | |
88 | then the file offset is adjusted to the end of the file | |
89 | (i.e., there is an implicit hole at the end of any file). | |
c6d039a3 | 90 | .P |
1976f57a | 91 | In both of the above cases, |
1e0819c8 MK |
92 | .BR lseek () |
93 | fails if | |
94 | .I offset | |
95 | points past the end of the file. | |
c6d039a3 | 96 | .P |
1e0819c8 MK |
97 | These operations allow applications to map holes in a sparsely |
98 | allocated file. | |
99 | This can be useful for applications such as file backup tools, | |
100 | which can save space when creating backups and preserve holes, | |
101 | if they have a mechanism for discovering holes. | |
c6d039a3 | 102 | .P |
fb30b096 | 103 | For the purposes of these operations, a hole is a sequence of zeros that |
1e0819c8 | 104 | (normally) has not been allocated in the underlying file storage. |
9ee4a2b6 | 105 | However, a filesystem is not obliged to report holes, |
1e0819c8 MK |
106 | so these operations are not a guaranteed mechanism for |
107 | mapping the storage space actually allocated to a file. | |
fb30b096 | 108 | (Furthermore, a sequence of zeros that actually has been written |
1e0819c8 MK |
109 | to the underlying storage may not be reported as a hole.) |
110 | In the simplest implementation, | |
9ee4a2b6 | 111 | a filesystem can support the operations by making |
1ae6b2c7 | 112 | .B SEEK_HOLE |
1e0819c8 MK |
113 | always return the offset of the end of the file, |
114 | and making | |
1ae6b2c7 | 115 | .B SEEK_DATA |
1e0819c8 | 116 | always return |
1ae6b2c7 | 117 | .I offset |
1e0819c8 MK |
118 | (i.e., even if the location referred to by |
119 | .I offset | |
120 | is a hole, | |
fb30b096 | 121 | it can be considered to consist of data that is a sequence of zeros). |
1e0819c8 MK |
122 | .\" https://lkml.org/lkml/2011/4/22/79 |
123 | .\" http://lwn.net/Articles/440255/ | |
124 | .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data | |
c6d039a3 | 125 | .P |
b4be4f08 | 126 | The |
1ae6b2c7 | 127 | .B _GNU_SOURCE |
b4be4f08 | 128 | feature test macro must be defined in order to obtain the definitions of |
1ae6b2c7 | 129 | .B SEEK_DATA |
b4be4f08 | 130 | and |
1ae6b2c7 | 131 | .B SEEK_HOLE |
b4be4f08 MK |
132 | from |
133 | .IR <unistd.h> . | |
c6d039a3 | 134 | .P |
b146ac83 | 135 | The |
1ae6b2c7 | 136 | .B SEEK_HOLE |
b146ac83 | 137 | and |
1ae6b2c7 | 138 | .B SEEK_DATA |
b146ac83 | 139 | operations are supported for the following filesystems: |
cdede5cd | 140 | .IP \[bu] 3 |
b146ac83 | 141 | Btrfs (since Linux 3.1) |
cdede5cd | 142 | .IP \[bu] |
b146ac83 MK |
143 | OCFS (since Linux 3.2) |
144 | .\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 | |
cdede5cd | 145 | .IP \[bu] |
b146ac83 | 146 | XFS (since Linux 3.5) |
cdede5cd | 147 | .IP \[bu] |
b146ac83 | 148 | ext4 (since Linux 3.8) |
cdede5cd | 149 | .IP \[bu] |
b30b425b MK |
150 | .BR tmpfs (5) |
151 | (since Linux 3.8) | |
cdede5cd | 152 | .IP \[bu] |
33fd2d00 MK |
153 | NFS (since Linux 3.18) |
154 | .\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 | |
155 | .\" commit 24bab491220faa446d945624086d838af41d616c | |
cdede5cd | 156 | .IP \[bu] |
6660ed03 MK |
157 | FUSE (since Linux 4.5) |
158 | .\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 | |
cdede5cd | 159 | .IP \[bu] |
a5b25af5 AP |
160 | GFS2 (since Linux 4.15) |
161 | .\" commit 3a27411cb4bc3ce31db228e3569ad01b462a4310 | |
47297adb | 162 | .SH RETURN VALUE |
fea681da | 163 | Upon successful completion, |
e511ffb6 | 164 | .BR lseek () |
fea681da | 165 | returns the resulting offset location as measured in bytes from the |
c13182ef | 166 | beginning of the file. |
b3a45270 | 167 | On error, the value \fI(off_t)\ \-1\fP is returned and |
fea681da MK |
168 | .I errno |
169 | is set to indicate the error. | |
170 | .SH ERRORS | |
171 | .TP | |
172 | .B EBADF | |
47752f33 | 173 | .I fd |
fea681da MK |
174 | is not an open file descriptor. |
175 | .TP | |
176 | .B EINVAL | |
177 | .I whence | |
1e0819c8 MK |
178 | is not valid. |
179 | Or: the resulting file offset would be negative, | |
2374c178 | 180 | or beyond the end of a seekable device. |
fea681da | 181 | .\" Some systems may allow negative offsets for character devices |
9ee4a2b6 | 182 | .\" and/or for remote filesystems. |
fea681da | 183 | .TP |
b6451637 MK |
184 | .B ENXIO |
185 | .I whence | |
186 | is | |
187 | .B SEEK_DATA | |
188 | or | |
189 | .BR SEEK_HOLE , | |
ab366b45 MK |
190 | and |
191 | .I offset | |
22a2e055 MK |
192 | is beyond the end of the file, or |
193 | .I whence | |
194 | is | |
195 | .B SEEK_DATA | |
196 | and | |
197 | .I offset | |
198 | is within a hole at the end of the file. | |
b6451637 | 199 | .TP |
fea681da | 200 | .B EOVERFLOW |
2374c178 | 201 | .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) |
c13182ef | 202 | The resulting file offset cannot be represented in an |
2486cacf | 203 | .IR off_t . |
fea681da MK |
204 | .TP |
205 | .B ESPIPE | |
47752f33 | 206 | .I fd |
fea681da | 207 | is associated with a pipe, socket, or FIFO. |
4131356c AC |
208 | .SH VERSIONS |
209 | On Linux, using | |
210 | .BR lseek () | |
211 | on a terminal device fails with the error | |
212 | .BR ESPIPE . | |
213 | .\" Other systems return the number of written characters, | |
214 | .\" using SEEK_SET to set the counter. (Of written characters.) | |
3113c7f3 | 215 | .SH STANDARDS |
4131356c AC |
216 | POSIX.1-2008. |
217 | .SH HISTORY | |
218 | POSIX.1-2001, SVr4, 4.3BSD. | |
c6d039a3 | 219 | .P |
1ae6b2c7 | 220 | .B SEEK_DATA |
1e0819c8 | 221 | and |
1ae6b2c7 | 222 | .B SEEK_HOLE |
25675bff GJ |
223 | are nonstandard extensions also present in Solaris, |
224 | FreeBSD, and DragonFly BSD; | |
1e0819c8 MK |
225 | they are proposed for inclusion in the next POSIX revision (Issue 8). |
226 | .\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future | |
b07cd0a9 | 227 | .SH NOTES |
22603b1d MK |
228 | See |
229 | .BR open (2) | |
230 | for a discussion of the relationship between file descriptors, | |
231 | open file descriptions, and files. | |
c6d039a3 | 232 | .P |
6b74f6c7 MK |
233 | If the |
234 | .B O_APPEND | |
235 | file status flag is set on the open file description, | |
236 | then a | |
237 | .BR write (2) | |
238 | .I always | |
239 | moves the file offset to the end of the file, regardless of the use of | |
240 | .BR lseek (). | |
c6d039a3 | 241 | .P |
fea681da | 242 | Some devices are incapable of seeking and POSIX does not specify which |
c13182ef | 243 | devices must support |
97c1eac8 | 244 | .BR lseek (). |
47297adb | 245 | .SH SEE ALSO |
fea681da | 246 | .BR dup (2), |
56fbdd27 | 247 | .BR fallocate (2), |
fea681da MK |
248 | .BR fork (2), |
249 | .BR open (2), | |
3ba7aed4 | 250 | .BR fseek (3), |
1f0ea6d8 | 251 | .BR lseek64 (3), |
c13182ef | 252 | .BR posix_fallocate (3) |