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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)lseek.2     8.3 (Berkeley) 4/19/94
  29 .\" $FreeBSD: src/lib/libc/sys/lseek.2,v 1.10.2.6 2001/12/14 18:34:01 ru Exp $
  30 .\" $DragonFly: src/lib/libc/sys/lseek.2,v 1.3 2006/02/17 19:35:06 swildner Exp $
  31 .\"
  32 .Dd April 19, 1994
  33 .Dt LSEEK 2
  34 .Os
  35 .Sh NAME
  36 .Nm lseek
  37 .Nd reposition read/write file offset
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In 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 position pointer associated with the file
  60 descriptor
  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.  The value of the pointer
 100 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 position pointer will remain unchanged if:
 114 .Bl -tag -width Er
 115 .It Bq Er EBADF
 116 .Em Fildes
 117 is not an open file descriptor.
 118 .It Bq Er ESPIPE
 119 .Em Fildes
 120 is associated with a pipe, socket, or FIFO.
 121 .It Bq Er EINVAL
 122 .Fa Whence
 123 is not a proper value.
 124 .El
 125 .Sh SEE ALSO
 126 .Xr dup 2 ,
 127 .Xr open 2
 128 .Sh STANDARDS
 129 The
 130 .Fn lseek
 131 function call is expected to conform to
 132 .St -p1003.1-90 .
 133 .Sh HISTORY
 134 A
 135 .Fn lseek
 136 function call appeared in
 137 .At v7 .
 138 .Sh BUGS
 139 This document's use of
 140 .Fa whence
 141 is incorrect English, but is maintained for historical reasons.