lib/libc/sys/lseek.2

   1 .\"     $NetBSD: lseek.2,v 1.24 2010/04/05 07:53:47 wiz 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. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)lseek.2     8.3 (Berkeley) 4/19/94
  31 .\"
  32 .Dd April 3, 2010
  33 .Dt LSEEK 2
  34 .Os
  35 .Sh NAME
  36 .Nm lseek ,
  37 .Nm seek
  38 .Nd reposition read/write file offset
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft off_t
  44 .Fn lseek "int fildes" "off_t offset" "int whence"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn lseek
  48 function repositions the offset of the file descriptor
  49 .Fa fildes
  50 to the
  51 argument
  52 .Fa offset
  53 according to the directive
  54 .Fa whence .
  55 The argument
  56 .Fa fildes
  57 must be an open
  58 file descriptor.
  59 .Fn lseek
  60 repositions the file pointer
  61 .Fa fildes
  62 as follows:
  63 .Bl -item -offset indent
  64 .It
  65 If
  66 .Fa whence
  67 is
  68 .Dv SEEK_SET ,
  69 the offset is set to
  70 .Fa offset
  71 bytes.
  72 .It
  73 If
  74 .Fa whence
  75 is
  76 .Dv SEEK_CUR ,
  77 the offset is set to its current location plus
  78 .Fa offset
  79 bytes.
  80 .It
  81 If
  82 .Fa whence
  83 is
  84 .Dv SEEK_END ,
  85 the offset is set to the size of the
  86 file plus
  87 .Fa offset
  88 bytes.
  89 .El
  90 .Pp
  91 The
  92 .Fn lseek
  93 function allows the file offset to be set beyond the end
  94 of the existing end-of-file of the file.
  95 If data is later written
  96 at this point, subsequent reads of the data in the gap return
  97 bytes of zeros (until data is actually written into the gap).
  98 .Pp
  99 Some devices are incapable of seeking.
 100 The value of the pointer associated with such a device is undefined.
 101 .Sh RETURN VALUES
 102 Upon successful completion,
 103 .Fn lseek
 104 returns the resulting offset location as measured in bytes from the
 105 beginning of the file.
 106 Otherwise,
 107 a value of \-1 is returned and
 108 .Va errno
 109 is set to indicate
 110 the error.
 111 .Sh ERRORS
 112 .Fn lseek
 113 will fail and the file pointer will remain unchanged if:
 114 .Bl -tag -width Er
 115 .It Bq Er EBADF
 116 .Fa fildes
 117 is not an open file descriptor.
 118 .It Bq Er EINVAL
 119 .Fa whence
 120 is not a proper value, or the resulting file offset would be invalid.
 121 .It Bq Er ESPIPE
 122 .Fa fildes
 123 is associated with a pipe, socket, or FIFO.
 124 .El
 125 .Sh SEE ALSO
 126 .Xr dup 2 ,
 127 .Xr open 2
 128 .Sh STANDARDS
 129 The
 130 .Fn lseek
 131 function conforms to
 132 .St -p1003.1-90 .
 133 .Sh HISTORY
 134 A
 135 .Fn seek
 136 function appeared in
 137 .At v2 ,
 138 later renamed into
 139 .Fn lseek
 140 for
 141 .Dq long seek
 142 due to a larger
 143 .Fa offset
 144 argument type.
 145 .Sh BUGS
 146 This document's use of
 147 .Fa whence
 148 is incorrect English, but is maintained for historical reasons.