1.\" $OpenBSD: lseek.2,v 1.17 2015/09/10 17:55:21 schwarze Exp $ 2.\" $NetBSD: lseek.2,v 1.6 1995/02/27 12:34:09 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)lseek.2 8.3 (Berkeley) 4/19/94 32.\" 33.Dd $Mdocdate: September 10 2015 $ 34.Dt LSEEK 2 35.Os 36.Sh NAME 37.Nm lseek 38.Nd reposition read/write file offset 39.Sh SYNOPSIS 40.In unistd.h 41.Ft off_t 42.Fn lseek "int fildes" "off_t offset" "int whence" 43.Sh DESCRIPTION 44The 45.Fn lseek 46function repositions the offset of the file descriptor 47.Fa fildes 48to the argument 49.Fa offset 50according to the directive 51.Fa whence . 52The argument 53.Fa fildes 54must be an open file descriptor. 55.Fn lseek 56repositions the file pointer 57.Fa fildes 58as follows: 59.Bl -item -offset indent 60.It 61If 62.Fa whence 63is 64.Dv SEEK_SET , 65the offset is set to 66.Fa offset 67bytes. 68.It 69If 70.Fa whence 71is 72.Dv SEEK_CUR , 73the offset is set to its current location plus 74.Fa offset 75bytes. 76.It 77If 78.Fa whence 79is 80.Dv SEEK_END , 81the offset is set to the size of the file plus 82.Fa offset 83bytes. 84.El 85.Pp 86The 87.Fn lseek 88function allows the file offset to be set beyond the end 89of the existing end-of-file of the file. 90If data is later written at this point, subsequent reads of the data in the 91gap return bytes of zeros (until data is actually written into the gap). 92.Pp 93Some devices are incapable of seeking. 94The value of the pointer associated with such a device is undefined. 95.Sh RETURN VALUES 96Upon successful completion, 97.Fn lseek 98returns the resulting offset location as measured in bytes from the 99beginning of the file. 100Otherwise, a value of \-1 is returned and 101.Va errno 102is set to indicate the error. 103.Sh ERRORS 104.Fn lseek 105will fail and the file pointer will remain unchanged if: 106.Bl -tag -width Er 107.It Bq Er EBADF 108.Em fildes 109is not an open file descriptor. 110.It Bq Er ESPIPE 111.Em fildes 112is associated with a pipe, socket, or FIFO. 113.It Bq Er EINVAL 114.Fa whence 115is not a proper value or the resulting offset would be negative 116on a file system or special device that does not allow negative 117offsets to be used. 118.El 119.Sh SEE ALSO 120.Xr dup 2 , 121.Xr open 2 122.Sh STANDARDS 123The 124.Fn lseek 125function conforms to 126.St -p1003.1-2008 . 127.Sh HISTORY 128A 129.Fn seek 130system call first appeared in 131.At v1 . 132In 133.At v7 134it was renamed to 135.Fn lseek 136for 137.Dq long seek 138due to a larger 139.Fa offset 140argument type. 141.Sh BUGS 142This document's use of 143.Fa whence 144is incorrect English, but is maintained for historical reasons. 145