1*47208Scael.\" Copyright (c) 1980, 1991 Regents of the University of California. 2*47208Scael.\" All rights reserved. 320077Smckusick.\" 4*47208Scael.\" %sccs.include.redist.man% 520077Smckusick.\" 6*47208Scael.\" @(#)lseek.2 6.5 (Berkeley) 03/10/91 7*47208Scael.\" 8*47208Scael.Dd 9*47208Scael.Dt LSEEK 2 10*47208Scael.Os BSD 4 11*47208Scael.Sh NAME 12*47208Scael.Nm lseek 13*47208Scael.Nd reposition read/write file offset 14*47208Scael.Sh SYNOPSIS 15*47208Scael.Fd #include <unistd.h> 16*47208Scael.Ft off_t 17*47208Scael.Fn lseek "int fildes" "off_t offset" "int whence" 18*47208Scael.Sh DESCRIPTION 19*47208ScaelThe 20*47208Scael.Fn lseek 21*47208Scaelfunction repositions the offset of the file descriptor 22*47208Scael.Fa fildes 23*47208Scaelto the 24*47208Scaelargument 25*47208Scael.Fa offset 26*47208Scaelaccording to the directive 27*47208Scael.Fa whence. 28*47208ScaelThe argument 29*47208Scael.Fa fildes 30*47208Scaelmust be an open 31*47208Scaelfile descriptor. 32*47208Scael.Fn Lseek 33*47208Scaelrepositions the file pointer 34*47208Scael.Fa fildes 3520078Smckusickas follows: 36*47208Scael.Bl -item -offset indent 37*47208Scael.It 3820077SmckusickIf 39*47208Scael.Fa whence 40*47208Scaelis 41*47208Scael.Dv SEEK_SET , 42*47208Scaelthe offset is set to 43*47208Scael.Fa offset 4420077Smckusickbytes. 45*47208Scael.It 4620077SmckusickIf 47*47208Scael.Fa whence 48*47208Scaelis 49*47208Scael.Dv SEEK_CUR , 50*47208Scaelthe offset is set to its current location plus 51*47208Scael.Fa offset 52*47208Scaelbytes. 53*47208Scael.It 5420077SmckusickIf 55*47208Scael.Fa whence 56*47208Scaelis 57*47208Scael.Dv SEEK_END , 58*47208Scaelthe offset is set to the size of the 5920077Smckusickfile plus 60*47208Scael.Fa offset 61*47208Scaelbytes. 62*47208Scael.El 63*47208Scael.Pp 64*47208ScaelThe 65*47208Scael.Fn lseek 66*47208Scaelfunction allows the file offset to be set beyond the end 67*47208Scaelof the existing end-of-file of the file. If data is later written 68*47208Scaelat this point, subsequent reads of the data in the gap return 69*47208Scaelbytes of zeros (until data is actualy written into the gap). 70*47208Scael.Pp 7120078SmckusickSome devices are incapable of seeking. The value of the pointer 7220078Smckusickassociated with such a device is undefined. 73*47208Scael.Sh RETURN VALUES 7425321SmckusickUpon successful completion, 75*47208Scael.Fn lseek 76*47208Scaelreturns the resulting offset location as measured in bytes from the 77*47208Scaelbegining of the file. 7825321SmckusickOtherwise, 79*47208Scaela value of -1 is returned and 80*47208Scael.Va errno 81*47208Scaelis set to indicate 8220078Smckusickthe error. 83*47208Scael.Sh ERRORS 84*47208Scael.Fn Lseek 8520078Smckusickwill fail and the file pointer will remain unchanged if: 86*47208Scael.Bl -tag -width [EINVAL] 87*47208Scael.It Bq Er EBADF 88*47208Scael.Em Fildes 8920078Smckusickis not an open file descriptor. 90*47208Scael.It Bq Er ESPIPE 91*47208Scael.Em Fildes 92*47208Scaelis associated with a pipe, socket, or FIFO. 93*47208Scael.It Bq Er EINVAL 94*47208Scael.Fa Whence 9520078Smckusickis not a proper value. 96*47208Scael.El 97*47208Scael.Sh SEE ALSO 98*47208Scael.Xr dup 2 , 99*47208Scael.Xr open 2 100*47208Scael.Sh BUGS 10120078SmckusickThis document's use of 102*47208Scael.Fa whence 10320078Smckusickis incorrect English, but maintained for historical reasons. 104*47208Scael.Sh STANDARDS 105*47208ScaelThe 106*47208Scael.Fn lseek 107*47208Scaelfunction 108*47208Scaelconforms to IEEE Std 1003.1-1988 109*47208Scael.Pq Dq Tn POSIX . 110