| '\" t |
| .\" Copyright (c) 1980, 1991 Regents of the University of California. |
| .\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 |
| .\" |
| .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl> |
| .\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 1998-01-17 by Michael Haardt |
| .\" <michael@cantor.informatik.rwth-aachen.de> |
| .\" Modified 2001-09-24 by Michael Haardt <michael@moria.de> |
| .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl> |
| .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE |
| .\" |
| .TH LSEEK 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| lseek \- reposition read/write file offset |
| .SH SYNOPSIS |
| .B #include <sys/types.h> |
| .br |
| .B #include <unistd.h> |
| .PP |
| .BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); |
| .SH DESCRIPTION |
| .BR lseek () |
| repositions the file offset of the open file description |
| associated with the file descriptor |
| .I fd |
| to the argument |
| .I offset |
| according to the directive |
| .I whence |
| as follows: |
| .TP |
| .B SEEK_SET |
| The file offset is set to |
| .I offset |
| bytes. |
| .TP |
| .B SEEK_CUR |
| The file offset is set to its current location plus |
| .I offset |
| bytes. |
| .TP |
| .B SEEK_END |
| The file offset is set to the size of the file plus |
| .I offset |
| bytes. |
| .PP |
| .BR lseek () |
| allows the file offset to be set beyond the end |
| of the file (but this does not change the size of the file). |
| If data is later written at this point, subsequent reads of the data |
| in the gap (a "hole") return null bytes (\(aq\e0\(aq) until |
| data is actually written into the gap. |
| .SS Seeking file data and holes |
| Since version 3.1, Linux supports the following additional values for |
| .IR whence : |
| .TP |
| .B SEEK_DATA |
| Adjust the file offset to the next location |
| in the file greater than or equal to |
| .I offset |
| containing data. |
| If |
| .I offset |
| points to data, |
| then the file offset is set to |
| .IR offset . |
| .TP |
| .B SEEK_HOLE |
| Adjust the file offset to the next hole in the file |
| greater than or equal to |
| .IR offset . |
| If |
| .I offset |
| points into the middle of a hole, |
| then the file offset is set to |
| .IR offset . |
| If there is no hole past |
| .IR offset , |
| then the file offset is adjusted to the end of the file |
| (i.e., there is an implicit hole at the end of any file). |
| .PP |
| In both of the above cases, |
| .BR lseek () |
| fails if |
| .I offset |
| points past the end of the file. |
| .PP |
| These operations allow applications to map holes in a sparsely |
| allocated file. |
| This can be useful for applications such as file backup tools, |
| which can save space when creating backups and preserve holes, |
| if they have a mechanism for discovering holes. |
| .PP |
| For the purposes of these operations, a hole is a sequence of zeros that |
| (normally) has not been allocated in the underlying file storage. |
| However, a filesystem is not obliged to report holes, |
| so these operations are not a guaranteed mechanism for |
| mapping the storage space actually allocated to a file. |
| (Furthermore, a sequence of zeros that actually has been written |
| to the underlying storage may not be reported as a hole.) |
| In the simplest implementation, |
| a filesystem can support the operations by making |
| .BR SEEK_HOLE |
| always return the offset of the end of the file, |
| and making |
| .BR SEEK_DATA |
| always return |
| .IR offset |
| (i.e., even if the location referred to by |
| .I offset |
| is a hole, |
| it can be considered to consist of data that is a sequence of zeros). |
| .\" https://lkml.org/lkml/2011/4/22/79 |
| .\" http://lwn.net/Articles/440255/ |
| .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data |
| .PP |
| The |
| .BR _GNU_SOURCE |
| feature test macro must be defined in order to obtain the definitions of |
| .BR SEEK_DATA |
| and |
| .BR SEEK_HOLE |
| from |
| .IR <unistd.h> . |
| .PP |
| The |
| .BR SEEK_HOLE |
| and |
| .BR SEEK_DATA |
| operations are supported for the following filesystems: |
| .IP * 3 |
| Btrfs (since Linux 3.1) |
| .IP * 3 |
| OCFS (since Linux 3.2) |
| .\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 |
| .IP * |
| XFS (since Linux 3.5) |
| .IP * |
| ext4 (since Linux 3.8) |
| .IP * |
| .BR tmpfs (5) |
| (since Linux 3.8) |
| .IP * |
| NFS (since Linux 3.18) |
| .\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 |
| .\" commit 24bab491220faa446d945624086d838af41d616c |
| .IP * |
| FUSE (since Linux 4.5) |
| .\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 |
| .SH RETURN VALUE |
| Upon successful completion, |
| .BR lseek () |
| returns the resulting offset location as measured in bytes from the |
| beginning of the file. |
| On error, the value \fI(off_t)\ \-1\fP is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I fd |
| is not an open file descriptor. |
| .TP |
| .B EINVAL |
| .I whence |
| is not valid. |
| Or: the resulting file offset would be negative, |
| or beyond the end of a seekable device. |
| .\" Some systems may allow negative offsets for character devices |
| .\" and/or for remote filesystems. |
| .TP |
| .B ENXIO |
| .I whence |
| is |
| .B SEEK_DATA |
| or |
| .BR SEEK_HOLE , |
| and the file offset is beyond the end of the file. |
| .TP |
| .B EOVERFLOW |
| .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) |
| The resulting file offset cannot be represented in an |
| .IR off_t . |
| .TP |
| .B ESPIPE |
| .I fd |
| is associated with a pipe, socket, or FIFO. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
| .PP |
| .BR SEEK_DATA |
| and |
| .BR SEEK_HOLE |
| are nonstandard extensions also present in Solaris, |
| FreeBSD, and DragonFly BSD; |
| they are proposed for inclusion in the next POSIX revision (Issue 8). |
| .\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future |
| .SH NOTES |
| See |
| .BR open (2) |
| for a discussion of the relationship between file descriptors, |
| open file descriptions, and files. |
| .PP |
| If the |
| .B O_APPEND |
| file status flag is set on the open file description, |
| then a |
| .BR write (2) |
| .I always |
| moves the file offset to the end of the file, regardless of the use of |
| .BR lseek (). |
| .PP |
| The |
| .I off_t |
| data type is a signed integer data type specified by POSIX.1. |
| .PP |
| Some devices are incapable of seeking and POSIX does not specify which |
| devices must support |
| .BR lseek (). |
| .PP |
| On Linux, using |
| .BR lseek () |
| on a terminal device fails with the error |
| \fBESPIPE\fP. |
| .\" Other systems return the number of written characters, |
| .\" using SEEK_SET to set the counter. (Of written characters.) |
| .SH SEE ALSO |
| .BR dup (2), |
| .BR fallocate (2), |
| .BR fork (2), |
| .BR open (2), |
| .BR fseek (3), |
| .BR lseek64 (3), |
| .BR posix_fallocate (3) |