1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)lseek.2 8.3 (Berkeley) 04/19/94 7.\" 8.Dd 9.Dt LSEEK 2 10.Os BSD 4 11.Sh NAME 12.Nm lseek 13.Nd reposition read/write file offset 14.Sh SYNOPSIS 15.Fd #include <unistd.h> 16.Ft off_t 17.Fn lseek "int fildes" "off_t offset" "int whence" 18.Sh DESCRIPTION 19The 20.Fn lseek 21function repositions the offset of the file descriptor 22.Fa fildes 23to the 24argument 25.Fa offset 26according to the directive 27.Fa whence. 28The argument 29.Fa fildes 30must be an open 31file descriptor. 32.Fn Lseek 33repositions the file pointer 34.Fa fildes 35as follows: 36.Bl -item -offset indent 37.It 38If 39.Fa whence 40is 41.Dv SEEK_SET , 42the offset is set to 43.Fa offset 44bytes. 45.It 46If 47.Fa whence 48is 49.Dv SEEK_CUR , 50the offset is set to its current location plus 51.Fa offset 52bytes. 53.It 54If 55.Fa whence 56is 57.Dv SEEK_END , 58the offset is set to the size of the 59file plus 60.Fa offset 61bytes. 62.El 63.Pp 64The 65.Fn lseek 66function allows the file offset to be set beyond the end 67of the existing end-of-file of the file. If data is later written 68at this point, subsequent reads of the data in the gap return 69bytes of zeros (until data is actually written into the gap). 70.Pp 71Some devices are incapable of seeking. The value of the pointer 72associated with such a device is undefined. 73.Sh RETURN VALUES 74Upon successful completion, 75.Fn lseek 76returns the resulting offset location as measured in bytes from the 77beginning of the file. 78Otherwise, 79a value of -1 is returned and 80.Va errno 81is set to indicate 82the error. 83.Sh ERRORS 84.Fn Lseek 85will fail and the file pointer will remain unchanged if: 86.Bl -tag -width [EINVAL] 87.It Bq Er EBADF 88.Em Fildes 89is not an open file descriptor. 90.It Bq Er ESPIPE 91.Em Fildes 92is associated with a pipe, socket, or FIFO. 93.It Bq Er EINVAL 94.Fa Whence 95is not a proper value. 96.El 97.Sh SEE ALSO 98.Xr dup 2 , 99.Xr open 2 100.Sh BUGS 101This document's use of 102.Fa whence 103is incorrect English, but is maintained for historical reasons. 104.Sh STANDARDS 105The 106.Fn lseek 107function 108conforms to IEEE Std 1003.1-1988 109.Pq Dq Tn POSIX . 110