161183Sbostic.\" Copyright (c) 1980, 1991, 1993 261183Sbostic.\" The Regents of the University of California. All rights reserved. 320077Smckusick.\" 447208Scael.\" %sccs.include.redist.man% 520077Smckusick.\" 6*66932Sbostic.\" @(#)lseek.2 8.3 (Berkeley) 04/19/94 747208Scael.\" 847208Scael.Dd 947208Scael.Dt LSEEK 2 1047208Scael.Os BSD 4 1147208Scael.Sh NAME 1247208Scael.Nm lseek 1347208Scael.Nd reposition read/write file offset 1447208Scael.Sh SYNOPSIS 1547208Scael.Fd #include <unistd.h> 1647208Scael.Ft off_t 1747208Scael.Fn lseek "int fildes" "off_t offset" "int whence" 1847208Scael.Sh DESCRIPTION 1947208ScaelThe 2047208Scael.Fn lseek 2147208Scaelfunction repositions the offset of the file descriptor 2247208Scael.Fa fildes 2347208Scaelto the 2447208Scaelargument 2547208Scael.Fa offset 2647208Scaelaccording to the directive 2747208Scael.Fa whence. 2847208ScaelThe argument 2947208Scael.Fa fildes 3047208Scaelmust be an open 3147208Scaelfile descriptor. 3247208Scael.Fn Lseek 3347208Scaelrepositions the file pointer 3447208Scael.Fa fildes 3520078Smckusickas follows: 3647208Scael.Bl -item -offset indent 3747208Scael.It 3820077SmckusickIf 3947208Scael.Fa whence 4047208Scaelis 4147208Scael.Dv SEEK_SET , 4247208Scaelthe offset is set to 4347208Scael.Fa offset 4420077Smckusickbytes. 4547208Scael.It 4620077SmckusickIf 4747208Scael.Fa whence 4847208Scaelis 4947208Scael.Dv SEEK_CUR , 5047208Scaelthe offset is set to its current location plus 5147208Scael.Fa offset 5247208Scaelbytes. 5347208Scael.It 5420077SmckusickIf 5547208Scael.Fa whence 5647208Scaelis 5747208Scael.Dv SEEK_END , 5847208Scaelthe offset is set to the size of the 5920077Smckusickfile plus 6047208Scael.Fa offset 6147208Scaelbytes. 6247208Scael.El 6347208Scael.Pp 6447208ScaelThe 6547208Scael.Fn lseek 6647208Scaelfunction allows the file offset to be set beyond the end 6747208Scaelof the existing end-of-file of the file. If data is later written 6847208Scaelat this point, subsequent reads of the data in the gap return 69*66932Sbosticbytes of zeros (until data is actually written into the gap). 7047208Scael.Pp 7120078SmckusickSome devices are incapable of seeking. The value of the pointer 7220078Smckusickassociated with such a device is undefined. 7347208Scael.Sh RETURN VALUES 7425321SmckusickUpon successful completion, 7547208Scael.Fn lseek 7647208Scaelreturns the resulting offset location as measured in bytes from the 77*66932Sbosticbeginning of the file. 7825321SmckusickOtherwise, 7947208Scaela value of -1 is returned and 8047208Scael.Va errno 8147208Scaelis set to indicate 8220078Smckusickthe error. 8347208Scael.Sh ERRORS 8447208Scael.Fn Lseek 8520078Smckusickwill fail and the file pointer will remain unchanged if: 8647208Scael.Bl -tag -width [EINVAL] 8747208Scael.It Bq Er EBADF 8847208Scael.Em Fildes 8920078Smckusickis not an open file descriptor. 9047208Scael.It Bq Er ESPIPE 9147208Scael.Em Fildes 9247208Scaelis associated with a pipe, socket, or FIFO. 9347208Scael.It Bq Er EINVAL 9447208Scael.Fa Whence 9520078Smckusickis not a proper value. 9647208Scael.El 9747208Scael.Sh SEE ALSO 9847208Scael.Xr dup 2 , 9947208Scael.Xr open 2 10047208Scael.Sh BUGS 10120078SmckusickThis document's use of 10247208Scael.Fa whence 10365100Smckusickis incorrect English, but is maintained for historical reasons. 10447208Scael.Sh STANDARDS 10547208ScaelThe 10647208Scael.Fn lseek 10747208Scaelfunction 10847208Scaelconforms to IEEE Std 1003.1-1988 10947208Scael.Pq Dq Tn POSIX . 110