[unix-history] / usr / src / lib / libc / sys / lseek.2

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