]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Copyright (c) 1980, 1991 Regents of the University of California. | |
1e0819c8 | 3 | .\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
4 | .\" All rights reserved. |
5 | .\" | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
14 | .\" 3. All advertising materials mentioning features or use of this software | |
15 | .\" must display the following acknowledgement: | |
16 | .\" This product includes software developed by the University of | |
17 | .\" California, Berkeley and its contributors. | |
18 | .\" 4. Neither the name of the University nor the names of its contributors | |
19 | .\" may be used to endorse or promote products derived from this software | |
20 | .\" without specific prior written permission. | |
21 | .\" | |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | .\" SUCH DAMAGE. | |
33 | .\" | |
34 | .\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 | |
35 | .\" | |
36 | .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> | |
37 | .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl> | |
38 | .\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com> | |
39 | .\" Modified 1998-01-17 by Michael Haardt | |
40 | .\" <michael@cantor.informatik.rwth-aachen.de> | |
41 | .\" Modified 2001-09-24 by Michael Haardt <michael@moria.de> | |
42 | .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl> | |
1e0819c8 | 43 | .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE |
fea681da | 44 | .\" |
25675bff | 45 | .TH LSEEK 2 2011-09-25 "Linux" "Linux Programmer's Manual" |
fea681da MK |
46 | .SH NAME |
47 | lseek \- reposition read/write file offset | |
48 | .SH SYNOPSIS | |
49 | .B #include <sys/types.h> | |
50 | .br | |
51 | .B #include <unistd.h> | |
52 | .sp | |
47752f33 | 53 | .BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); |
fea681da MK |
54 | .SH DESCRIPTION |
55 | The | |
e511ffb6 | 56 | .BR lseek () |
3ba7aed4 MK |
57 | function repositions the offset of the open file associated with the |
58 | file descriptor | |
47752f33 | 59 | .I fd |
fea681da MK |
60 | to the argument |
61 | .I offset | |
62 | according to the directive | |
63 | .I whence | |
64 | as follows: | |
65 | .TP | |
66 | .B SEEK_SET | |
67 | The offset is set to | |
68 | .I offset | |
69 | bytes. | |
70 | .TP | |
71 | .B SEEK_CUR | |
72 | The offset is set to its current location plus | |
73 | .I offset | |
74 | bytes. | |
75 | .TP | |
76 | .B SEEK_END | |
77 | The offset is set to the size of the file plus | |
78 | .I offset | |
79 | bytes. | |
80 | .PP | |
81 | The | |
e511ffb6 | 82 | .BR lseek () |
2374c178 MK |
83 | function allows the file offset to be set beyond the end |
84 | of the file (but this does not change the size of the file). | |
fea681da | 85 | If data is later written at this point, subsequent reads of the data |
f81fb444 | 86 | in the gap (a "hole") return null bytes (\(aq\\0\(aq) until |
2374c178 | 87 | data is actually written into the gap. |
1e0819c8 MK |
88 | .SS Seeking file data and holes |
89 | Since version 3.1, Linux supports the following additional values for | |
90 | .IR whence : | |
91 | .TP | |
92 | .B SEEK_DATA | |
93 | Adjust the file offset to the next location | |
94 | in the file greater than or equal to | |
95 | .I offset | |
96 | containing data. | |
97 | If | |
98 | .I offset | |
99 | points to data, | |
100 | then the file offset is set to | |
101 | .IR offset . | |
102 | .TP | |
103 | .B SEEK_HOLE | |
104 | Adjust the file offset to the next hole in the file | |
105 | greater than or equal to | |
106 | .IR offset . | |
107 | If | |
108 | .I offset | |
109 | points into the middle of a hole, | |
110 | then the file offset is set to | |
111 | .IR offset . | |
112 | If there is no hole past | |
113 | .IR offset , | |
114 | then the file offset is adjusted to the end of the file | |
115 | (i.e., there is an implicit hole at the end of any file). | |
116 | .PP | |
1976f57a | 117 | In both of the above cases, |
1e0819c8 MK |
118 | .BR lseek () |
119 | fails if | |
120 | .I offset | |
121 | points past the end of the file. | |
122 | ||
123 | These operations allow applications to map holes in a sparsely | |
124 | allocated file. | |
125 | This can be useful for applications such as file backup tools, | |
126 | which can save space when creating backups and preserve holes, | |
127 | if they have a mechanism for discovering holes. | |
128 | ||
fb30b096 | 129 | For the purposes of these operations, a hole is a sequence of zeros that |
1e0819c8 MK |
130 | (normally) has not been allocated in the underlying file storage. |
131 | However, a file system is not obliged to report holes, | |
132 | so these operations are not a guaranteed mechanism for | |
133 | mapping the storage space actually allocated to a file. | |
fb30b096 | 134 | (Furthermore, a sequence of zeros that actually has been written |
1e0819c8 MK |
135 | to the underlying storage may not be reported as a hole.) |
136 | In the simplest implementation, | |
137 | a file system can support the operations by making | |
138 | .BR SEEK_HOLE | |
139 | always return the offset of the end of the file, | |
140 | and making | |
141 | .BR SEEK_DATA | |
142 | always return | |
1e0819c8 MK |
143 | .IR offset |
144 | (i.e., even if the location referred to by | |
145 | .I offset | |
146 | is a hole, | |
fb30b096 | 147 | it can be considered to consist of data that is a sequence of zeros). |
1e0819c8 MK |
148 | .\" https://lkml.org/lkml/2011/4/22/79 |
149 | .\" http://lwn.net/Articles/440255/ | |
150 | .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data | |
47297adb | 151 | .SH RETURN VALUE |
fea681da | 152 | Upon successful completion, |
e511ffb6 | 153 | .BR lseek () |
fea681da | 154 | returns the resulting offset location as measured in bytes from the |
c13182ef | 155 | beginning of the file. |
b3a45270 | 156 | On error, the value \fI(off_t)\ \-1\fP is returned and |
fea681da MK |
157 | .I errno |
158 | is set to indicate the error. | |
159 | .SH ERRORS | |
160 | .TP | |
161 | .B EBADF | |
47752f33 | 162 | .I fd |
fea681da MK |
163 | is not an open file descriptor. |
164 | .TP | |
165 | .B EINVAL | |
166 | .I whence | |
1e0819c8 MK |
167 | is not valid. |
168 | Or: the resulting file offset would be negative, | |
2374c178 | 169 | or beyond the end of a seekable device. |
fea681da | 170 | .\" Some systems may allow negative offsets for character devices |
24d01c53 | 171 | .\" and/or for remote file systems. |
fea681da MK |
172 | .TP |
173 | .B EOVERFLOW | |
2374c178 | 174 | .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) |
c13182ef | 175 | The resulting file offset cannot be represented in an |
2486cacf | 176 | .IR off_t . |
fea681da MK |
177 | .TP |
178 | .B ESPIPE | |
47752f33 | 179 | .I fd |
fea681da | 180 | is associated with a pipe, socket, or FIFO. |
1e0819c8 MK |
181 | .TP |
182 | .B ENXIO | |
183 | .I whence | |
184 | is | |
185 | .B SEEK_DATA | |
186 | or | |
187 | .BR SEEK_HOLE , | |
188 | and the current file offset is beyond the end of the file. | |
47297adb | 189 | .SH CONFORMING TO |
97c1eac8 | 190 | SVr4, 4.3BSD, POSIX.1-2001. |
1e0819c8 MK |
191 | |
192 | .BR SEEK_DATA | |
193 | and | |
194 | .BR SEEK_HOLE | |
25675bff GJ |
195 | are nonstandard extensions also present in Solaris, |
196 | FreeBSD, and DragonFly BSD; | |
1e0819c8 MK |
197 | they are proposed for inclusion in the next POSIX revision (Issue 8). |
198 | .\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future | |
b07cd0a9 | 199 | .SH NOTES |
fea681da | 200 | Some devices are incapable of seeking and POSIX does not specify which |
c13182ef | 201 | devices must support |
97c1eac8 | 202 | .BR lseek (). |
fea681da | 203 | |
b07cd0a9 | 204 | On Linux, using |
60a90ecd | 205 | .BR lseek () |
1285ff3d | 206 | on a terminal device returns |
fea681da MK |
207 | \fBESPIPE\fP. |
208 | .\" Other systems return the number of written characters, | |
209 | .\" using SEEK_SET to set the counter. (Of written characters.) | |
fea681da MK |
210 | |
211 | When converting old code, substitute values for \fIwhence\fP with the | |
212 | following macros: | |
fea681da MK |
213 | .TS |
214 | c c | |
215 | l l. | |
216 | old new | |
217 | 0 SEEK_SET | |
218 | 1 SEEK_CUR | |
219 | 2 SEEK_END | |
220 | L_SET SEEK_SET | |
221 | L_INCR SEEK_CUR | |
222 | L_XTND SEEK_END | |
223 | .TE | |
3284fbc0 MK |
224 | .\" .PP |
225 | .\" SVr1-3 returns \fIlong\fP instead of \fIoff_t\fP, | |
226 | .\" (ancient) BSD returns \fIint\fP. | |
fea681da MK |
227 | .PP |
228 | Note that file descriptors created by | |
229 | .BR dup (2) | |
230 | or | |
231 | .BR fork (2) | |
232 | share the current file position pointer, so seeking on such files may be | |
233 | subject to race conditions. | |
47297adb | 234 | .SH SEE ALSO |
fea681da MK |
235 | .BR dup (2), |
236 | .BR fork (2), | |
237 | .BR open (2), | |
3ba7aed4 | 238 | .BR fseek (3), |
1f0ea6d8 | 239 | .BR lseek64 (3), |
c13182ef | 240 | .BR posix_fallocate (3) |