lib/libc/sys/lseek.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  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     8.3 (Berkeley) 4/19/94
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd April 19, 1994
  36 .Dt LSEEK 2
  37 .Os
  38 .Sh NAME
  39 .Nm lseek
  40 .Nd reposition read/write file offset
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft off_t
  46 .Fn lseek "int fildes" "off_t offset" "int whence"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn lseek
  50 system call repositions the offset of the file descriptor
  51 .Fa fildes
  52 to the
  53 argument
  54 .Fa offset
  55 according to the directive
  56 .Fa whence .
  57 The argument
  58 .Fa fildes
  59 must be an open
  60 file descriptor.
  61 The
  62 .Fn lseek
  63 system call
  64 repositions the file position pointer associated with the file
  65 descriptor
  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 .El
  95 .Pp
  96 The
  97 .Fn lseek
  98 system call allows the file offset to be set beyond the end
  99 of the existing end-of-file of the file.
 100 If data is later written
 101 at this point, subsequent reads of the data in the gap return
 102 bytes of zeros (until data is actually written into the gap).
 103 .Pp
 104 Some devices are incapable of seeking.
 105 The value of the pointer
 106 associated with such a device is undefined.
 107 .Sh RETURN VALUES
 108 Upon successful completion,
 109 .Fn lseek
 110 returns the resulting offset location as measured in bytes from the
 111 beginning of the file.
 112 Otherwise,
 113 a value of -1 is returned and
 114 .Va errno
 115 is set to indicate
 116 the error.
 117 .Sh ERRORS
 118 The
 119 .Fn lseek
 120 system call
 121 will fail and the file position pointer will remain unchanged if:
 122 .Bl -tag -width Er
 123 .It Bq Er EBADF
 124 The
 125 .Fa fildes
 126 argument
 127 is not an open file descriptor.
 128 .It Bq Er EINVAL
 129 The
 130 .Fa whence
 131 argument
 132 is not a proper value
 133 or the resulting file offset would
 134 be negative for a non-character special file.
 135 .It Bq Er EOVERFLOW
 136 The resulting file offset would be a value which cannot be represented
 137 correctly in an object of type
 138 .Fa off_t .
 139 .It Bq Er ESPIPE
 140 The
 141 .Fa fildes
 142 argument
 143 is associated with a pipe, socket, or FIFO.
 144 .El
 145 .Sh SEE ALSO
 146 .Xr dup 2 ,
 147 .Xr open 2
 148 .Sh STANDARDS
 149 The
 150 .Fn lseek
 151 system call is expected to conform to
 152 .St -p1003.1-90 .
 153 .Sh HISTORY
 154 The
 155 .Fn lseek
 156 function appeared in
 157 .At v7 .
 158 .Sh BUGS
 159 This document's use of
 160 .Fa whence
 161 is incorrect English, but is maintained for historical reasons.