bsd/man/man2/lseek.2

   1 .\"     $NetBSD: lseek.2,v 1.6 1995/02/27 12:34:09 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)lseek.2     8.3 (Berkeley) 4/19/94
  35 .\"
  36 .Dd April 19, 1994
  37 .Dt LSEEK 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm lseek
  41 .Nd reposition read/write file offset
  42 .Sh SYNOPSIS
  43 .Fd #include <unistd.h>
  44 .Ft off_t
  45 .Fo lseek
  46 .Fa "int fildes"
  47 .Fa "off_t offset"
  48 .Fa "int whence"
  49 .Fc
  50 .Sh DESCRIPTION
  51 The
  52 .Fn lseek
  53 function repositions the offset of the file descriptor
  54 .Fa fildes
  55 to the
  56 argument
  57 .Fa offset ,
  58 according to the directive
  59 .Fa whence .
  60 The argument
  61 .Fa fildes
  62 must be an open
  63 file descriptor.
  64 .Fn lseek
  65 repositions the file pointer
  66 .Fa fildes
  67 as follows:
  68 .Bl -item -offset indent
  69 .It
  70 If
  71 .Fa whence
  72 is
  73 .Dv SEEK_SET ,
  74 the offset is set to
  75 .Fa offset
  76 bytes.
  77 .It
  78 If
  79 .Fa whence
  80 is
  81 .Dv SEEK_CUR ,
  82 the offset is set to its current location plus
  83 .Fa offset
  84 bytes.
  85 .It
  86 If
  87 .Fa whence
  88 is
  89 .Dv SEEK_END ,
  90 the offset is set to the size of the
  91 file plus
  92 .Fa offset
  93 bytes.
  94 .It
  95 If
  96 .Fa whence
  97 is
  98 .Dv SEEK_HOLE ,
  99 the offset is set to the start of the next hole greater than or equal
 100 to the supplied
 101 .Fa offset .
 102 The definition of a hole is provided below.
 103 .It
 104 If
 105 .Fa whence
 106 is
 107 .Dv SEEK_DATA ,
 108 the offset is set to the start of the next non-hole file region greater
 109 than or equal to the supplied
 110 .Fa offset .
 111 .El
 112 .Pp
 113 The
 114 .Fn lseek
 115 function allows the file offset to be set beyond the end
 116 of the existing end-of-file of the file. If data is later written
 117 at this point, subsequent reads of the data in the gap return
 118 bytes of zeros (until data is actually written into the gap).
 119 .Pp
 120 Some devices are incapable of seeking.  The value of the pointer
 121 associated with such a device is undefined.
 122 .Pp
 123 A
 124 .Qq hole
 125 is defined as a contiguous range of bytes in a file, all having the value of
 126 zero, but not all zeros in a file are guaranteed to be represented as holes
 127 returned with
 128 .Dv SEEK_HOLE .
 129 File systems are allowed to expose ranges of zeros with
 130 .Dv SEEK_HOLE ,
 131 but not required to.
 132 Applications can use
 133 .Dv SEEK_HOLE
 134 to optimise their behavior for ranges of zeros, but must not depend on it to
 135 find all such ranges in a file.
 136 Each file is presented as having a zero-size virtual hole at the very
 137 end of the file.
 138 The existence of a hole at the end of every data region allows for easy
 139 programming and also provides compatibility to the original implementation
 140 in Solaris.
 141 It also causes the current file size (i.e., end-of-file offset) to be returned
 142 to indicate that there are no more holes past the supplied
 143 .Fa offset .
 144 Applications should use
 145 .Fn fpathconf _PC_MIN_HOLE_SIZE
 146 or
 147 .Fn pathconf _PC_MIN_HOLE_SIZE
 148 to determine if a file system supports
 149 .Dv SEEK_HOLE .
 150 See
 151 .Xr pathconf 2 .
 152 .Pp
 153 For file systems that do not supply information about holes, the file will be
 154 represented as one entire data region.
 155 .Sh RETURN VALUES
 156 Upon successful completion,
 157 .Fn lseek
 158 returns the resulting offset location as measured in bytes from the
 159 beginning of the file.
 160 Otherwise,
 161 a value of -1 is returned and
 162 .Va errno
 163 is set to indicate
 164 the error.
 165 .Sh ERRORS
 166 .Fn lseek
 167 will fail and the file pointer will remain unchanged if:
 168 .Bl -tag -width Er
 169 .\" ==========
 170 .It Bq Er EBADF
 171 .Em Fildes
 172 is not an open file descriptor.
 173 .\" ==========
 174 .It Bq Er EINVAL
 175 .Fa Whence
 176 is not a proper value.
 177 .\" ==========
 178 .It Bq Er EINVAL
 179 The seek location (calculated from
 180 .Fa offset
 181 and
 182 .Fa whence )
 183 is negative.
 184 .\" ==========
 185 .It Bq Er ENXIO
 186 For
 187 .Dv SEEK_DATA ,
 188 there are no more data regions past the supplied offset.
 189 Due to existence of the hole at the end of the file, for
 190 .Dv SEEK_HOLE
 191 this error is only returned when the
 192 .Fa offset
 193 already points to the end-of-file position.
 194 .It Bq Er EOVERFLOW
 195 The seek location is too large to be stored
 196 in an object of type off_t.
 197 .\" ==========
 198 .It Bq Er ESPIPE
 199 .Em Fildes
 200 is associated with a pipe, socket, or FIFO.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr dup 2 ,
 204 .Xr open 2
 205 .Sh BUGS
 206 This document's use of
 207 .Fa whence
 208 is incorrect English, but is maintained for historical reasons.
 209 .Sh STANDARDS
 210 The
 211 .Fn lseek
 212 function conforms to
 213 .St -p1003.1-88 .