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

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