d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
231f59920a
freebsd-skq/lib/libc/sys/lseek.2

247 lines
6.3 KiB
Groff
Raw Normal View History

BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.\" Copyright (c) 1980, 1991, 1993
.\" The 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.
Renumber copyright clause 4 Renumber cluase 4 to 3, per what everybody else did when BSD granted them permission to remove clause 3. My insistance on keeping the same numbering for legal reasons is too pedantic, so give up on that point. Submitted by: Jan Schaumann <jschauma@stevens.edu> Pull Request: https://github.com/freebsd/freebsd/pull/96
2017-02-28 23:42:47 +00:00
.\" 3. Neither the name of the University nor the names of its contributors
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.\" 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 8.3 (Berkeley) 4/19/94
$Id$ -> $FreeBSD$
1999-08-28 00:22:10 +00:00
.\" $FreeBSD$
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.\"
lseek(2): Document the seek behavior better and update the POSIX compliance In certain situations lseek(2) will return successful although if no seek was performed. This can happen when operating on devices that don't support seeking (older tape drives) or when operating on changeable media devices (such as DVD or Blu-ray devices) without a medium inserted. Document this within the man page and update the POSIX compliance while here. PR: 162765 Submitted by: arundel@ Reported by: arundel@ Reviewed by: bcr (mentor) Approved by: bcr (mentor) MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D25646
2020-07-13 15:52:57 +00:00
.Dd July 13, 2020
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Dt LSEEK 2
mdoc(7) police: removed HISTORY info from the .Os call.
2001-07-10 13:41:46 +00:00
.Os
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh NAME
.Nm lseek
.Nd reposition read/write file offset
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following.
2000-04-21 09:42:15 +00:00
.Sh LIBRARY
.Lb libc
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh SYNOPSIS
mdoc(7) police: Use the new .In macro for #include statements.
2001-10-01 16:09:29 +00:00
.In unistd.h
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Ft off_t
.Fn lseek "int fildes" "off_t offset" "int whence"
.Sh DESCRIPTION
The
.Fn lseek
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
system call repositions the offset of the file descriptor
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Fa fildes
to the
argument
.Fa offset
according to the directive
mdoc(7) police: split punctuation characters + misc fixes.
2001-02-01 16:38:02 +00:00
.Fa whence .
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
The argument
.Fa fildes
must be an open
file descriptor.
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
The
.Fn lseek
system call
Describe the "file pointer" in lseeks' man page a bit better so that it is less likely someone will confuse it with a "FILE *" type pointer. Submitted by: Based on James Raynard's patch
1996-07-03 02:55:10 +00:00
repositions the file position pointer associated with the file
descriptor
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.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.
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
.It
If
.Fa whence
is
.Dv SEEK_HOLE ,
Clarify the SEEK_HOLE description, it repositions the file pointer. MFC after: 3 days
2012-05-26 05:25:55 +00:00
the offset is set to the start of the next hole greater than or equal
to the supplied
.Fa offset .
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
The definition of a hole is provided below.
.It
If
.Fa whence
is
.Dv SEEK_DATA ,
the offset is set to the start of the next non-hole file region greater
than or equal to the supplied
.Fa offset .
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.El
.Pp
The
.Fn lseek
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
system call allows the file offset to be set beyond the end
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc.
2000-03-02 09:14:21 +00:00
of the existing end-of-file of the file.
If data is later written
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
at this point, subsequent reads of the data in the gap return
bytes of zeros (until data is actually written into the gap).
lseek(2): Document the seek behavior better and update the POSIX compliance In certain situations lseek(2) will return successful although if no seek was performed. This can happen when operating on devices that don't support seeking (older tape drives) or when operating on changeable media devices (such as DVD or Blu-ray devices) without a medium inserted. Document this within the man page and update the POSIX compliance while here. PR: 162765 Submitted by: arundel@ Reported by: arundel@ Reviewed by: bcr (mentor) Approved by: bcr (mentor) MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D25646
2020-07-13 15:52:57 +00:00
However, the
.Fn lseek
system call does not, by itself, extend the size of a file.
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
.Pp
A
.Qq hole
is defined as a contiguous range of bytes in a file, all having the value of
zero, but not all zeros in a file are guaranteed to be represented as holes
returned with
.Dv SEEK_HOLE .
File systems are allowed to expose ranges of zeros with
.Dv SEEK_HOLE ,
but not required to.
Applications can use
.Dv SEEK_HOLE
to optimise their behavior for ranges of zeros, but must not depend on it to
find all such ranges in a file.
Right now, the "virtual hole" API feature of lseek(2) is very vaguely documented and easy to miss. At the same time, it's pretty important for anyone who is trying to use SEEK_HOLE/SEEK_DATA in real app. Try to bridge that gap by making that description more pronounced and also document how it affects failure codes. Reviewed by: kib Differential Revision: https://reviews.freebsd.org/D5162
2016-02-18 18:41:40 +00:00
Each file is presented as having a zero-size virtual hole at the very
end of the file.
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
The existence of a hole at the end of every data region allows for easy
Bump .Dd for r295764 Also fix a spelling and grammar nit while here.
2016-02-18 18:50:03 +00:00
programming and also provides compatibility to the original implementation
Right now, the "virtual hole" API feature of lseek(2) is very vaguely documented and easy to miss. At the same time, it's pretty important for anyone who is trying to use SEEK_HOLE/SEEK_DATA in real app. Try to bridge that gap by making that description more pronounced and also document how it affects failure codes. Reviewed by: kib Differential Revision: https://reviews.freebsd.org/D5162
2016-02-18 18:41:40 +00:00
in Solaris.
Bump .Dd for r295764 Also fix a spelling and grammar nit while here.
2016-02-18 18:50:03 +00:00
It also causes the current file size (i.e., end-of-file offset) to be returned
Right now, the "virtual hole" API feature of lseek(2) is very vaguely documented and easy to miss. At the same time, it's pretty important for anyone who is trying to use SEEK_HOLE/SEEK_DATA in real app. Try to bridge that gap by making that description more pronounced and also document how it affects failure codes. Reviewed by: kib Differential Revision: https://reviews.freebsd.org/D5162
2016-02-18 18:41:40 +00:00
to indicate that there are no more holes past the supplied
.Fa offset .
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
Applications should use
.Fn fpathconf _PC_MIN_HOLE_SIZE
or
.Fn pathconf _PC_MIN_HOLE_SIZE
to determine if a file system supports
.Dv SEEK_HOLE .
See
.Xr pathconf 2 .
.Pp
For file systems that do not supply information about holes, the file will be
represented as one entire data region.
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh RETURN VALUES
Upon successful completion,
.Fn lseek
returns the resulting offset location as measured in bytes from the
beginning of the file.
Otherwise,
a value of -1 is returned and
.Va errno
is set to indicate
the error.
.Sh ERRORS
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
The
.Fn lseek
system call
Describe the "file pointer" in lseeks' man page a bit better so that it is less likely someone will confuse it with a "FILE *" type pointer. Submitted by: Based on James Raynard's patch
1996-07-03 02:55:10 +00:00
will fail and the file position pointer will remain unchanged if:
Use `Er' variable to define first column width in ERRORS section. It was initially suggested by mdoc(7) style, but was broken over the years
2000-05-04 13:09:25 +00:00
.Bl -tag -width Er
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.It Bq Er EBADF
mdoc(7) police: "The .Fa argument.".
2002-12-19 09:40:28 +00:00
The
mdoc(7) police: Fixed abuses of the .Ar and .Em macros.
2002-12-18 13:33:04 +00:00
.Fa fildes
mdoc(7) police: "The .Fa argument.".
2002-12-19 09:40:28 +00:00
argument
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
is not an open file descriptor.
Document new EINVAL, EOVERFLOW cases. Sort ERRORS
2001-08-21 21:44:48 +00:00
.It Bq Er EINVAL
mdoc(7) police: "The .Fa argument.".
2002-12-19 09:40:28 +00:00
The
.Fa whence
argument
Document new EINVAL, EOVERFLOW cases. Sort ERRORS
2001-08-21 21:44:48 +00:00
is not a proper value
or the resulting file offset would
be negative for a non-character special file.
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
.It Bq Er ENXIO
For
.Dv SEEK_DATA ,
there are no more data regions past the supplied offset.
Right now, the "virtual hole" API feature of lseek(2) is very vaguely documented and easy to miss. At the same time, it's pretty important for anyone who is trying to use SEEK_HOLE/SEEK_DATA in real app. Try to bridge that gap by making that description more pronounced and also document how it affects failure codes. Reviewed by: kib Differential Revision: https://reviews.freebsd.org/D5162
2016-02-18 18:41:40 +00:00
Due to existence of the hole at the end of the file, for
.Dv SEEK_HOLE
this error is only returned when the
.Fa offset
already points to the end-of-file position.
Document new EINVAL, EOVERFLOW cases. Sort ERRORS
2001-08-21 21:44:48 +00:00
.It Bq Er EOVERFLOW
The resulting file offset would be a value which cannot be represented
correctly in an object of type
.Fa off_t .
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.It Bq Er ESPIPE
mdoc(7) police: "The .Fa argument.".
2002-12-19 09:40:28 +00:00
The
mdoc(7) police: Fixed abuses of the .Ar and .Em macros.
2002-12-18 13:33:04 +00:00
.Fa fildes
mdoc(7) police: "The .Fa argument.".
2002-12-19 09:40:28 +00:00
argument
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
is associated with a pipe, socket, or FIFO.
.El
.Sh SEE ALSO
.Xr dup 2 ,
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in OpenSolaris. For more information please refer to: http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
2007-04-05 21:10:53 +00:00
.Xr open 2 ,
.Xr pathconf 2
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh STANDARDS
The
.Fn lseek
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
system call is expected to conform to
lseek(2): Document the seek behavior better and update the POSIX compliance In certain situations lseek(2) will return successful although if no seek was performed. This can happen when operating on devices that don't support seeking (older tape drives) or when operating on changeable media devices (such as DVD or Blu-ray devices) without a medium inserted. Document this within the man page and update the POSIX compliance while here. PR: 162765 Submitted by: arundel@ Reported by: arundel@ Reviewed by: bcr (mentor) Approved by: bcr (mentor) MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D25646
2020-07-13 15:52:57 +00:00
.St -p1003.1-2008 .
.Pp
The
.Dv SEEK_HOLE
and
.Dv SEEK_DATA
directives, along with the
.Er ENXIO
error, are extensions to that specification.
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2
1996-08-29 21:24:19 +00:00
.Sh HISTORY
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
The
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2
1996-08-29 21:24:19 +00:00
.Fn lseek
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
function appeared in
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2
1996-08-29 21:24:19 +00:00
.At v7 .
Sort sections.
2005-01-20 09:17:07 +00:00
.Sh BUGS
lseek(2): Document the seek behavior better and update the POSIX compliance In certain situations lseek(2) will return successful although if no seek was performed. This can happen when operating on devices that don't support seeking (older tape drives) or when operating on changeable media devices (such as DVD or Blu-ray devices) without a medium inserted. Document this within the man page and update the POSIX compliance while here. PR: 162765 Submitted by: arundel@ Reported by: arundel@ Reviewed by: bcr (mentor) Approved by: bcr (mentor) MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D25646
2020-07-13 15:52:57 +00:00
If the
.Fn lseek
system call is operating on a device which is incapable of seeking,
it will request the seek operation and return successfully,
even though no seek was performed.
Because the
.Ar offset
argument will be stored unconditionally in the file descriptor of that device,
there is no way to confirm if the seek operation succeeded or not
(e.g. using the
.Fn ftell
function).
Device types which are known to be incapable of seeking include
tape drives.
.Pp
The
.Fn lseek
system call will not detect whether media are present in changeable
media devices such as DVD or Blu-ray devices.
A requested seek operation will therefore return sucessfully when no
medium is present.
.Pp
Sort sections.
2005-01-20 09:17:07 +00:00
This document's use of
.Fa whence
is incorrect English, but is maintained for historical reasons.
Reference in New Issue Copy Permalink