original/man2/lseek.2

   1 '\" t
   2 .\" Copyright (c) 1980, 1991 Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)lseek.2     6.5 (Berkeley) 3/10/91
  34 .\"
  35 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
  36 .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl>
  37 .\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com>
  38 .\" Modified 1998-01-17 by Michael Haardt
  39 .\"   <michael@cantor.informatik.rwth-aachen.de>
  40 .\" Modified 2001-09-24 by Michael Haardt <michael@moria.de>
  41 .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl>
  42 .\"
  43 .TH LSEEK 2 2010-09-11 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 lseek \- reposition read/write file offset
  46 .SH SYNOPSIS
  47 .B #include <sys/types.h>
  48 .br
  49 .B #include <unistd.h>
  50 .sp
  51 .BI "off_t lseek(int " fd ", off_t " offset ", int " whence );
  52 .SH DESCRIPTION
  53 The
  54 .BR lseek ()
  55 function repositions the offset of the open file associated with the
  56 file descriptor
  57 .I fd
  58 to the argument
  59 .I offset
  60 according to the directive
  61 .I whence
  62 as follows:
  63 .TP
  64 .B SEEK_SET
  65 The offset is set to
  66 .I offset
  67 bytes.
  68 .TP
  69 .B SEEK_CUR
  70 The offset is set to its current location plus
  71 .I offset
  72 bytes.
  73 .TP
  74 .B SEEK_END
  75 The offset is set to the size of the file plus
  76 .I offset
  77 bytes.
  78 .PP
  79 The
  80 .BR lseek ()
  81 function allows the file offset to be set beyond the end
  82 of the file (but this does not change the size of the file).
  83 If data is later written at this point, subsequent reads of the data
  84 in the gap (a "hole") return null bytes (\(aq\\0\(aq) until
  85 data is actually written into the gap.
  86 .SH "RETURN VALUE"
  87 Upon successful completion,
  88 .BR lseek ()
  89 returns the resulting offset location as measured in bytes from the
  90 beginning of the file.
  91 On error, the value \fI(off_t)\ \-1\fP is returned and
  92 .I errno
  93 is set to indicate the error.
  94 .SH ERRORS
  95 .TP
  96 .B EBADF
  97 .I fd
  98 is not an open file descriptor.
  99 .TP
 100 .B EINVAL
 101 .I whence
 102 is not one of
 103 .BR SEEK_SET ,
 104 .BR SEEK_CUR ,
 105 .BR SEEK_END ;
 106 or the resulting file offset would be negative,
 107 or beyond the end of a seekable device.
 108 .\" Some systems may allow negative offsets for character devices
 109 .\" and/or for remote file systems.
 110 .TP
 111 .B EOVERFLOW
 112 .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW)
 113 The resulting file offset cannot be represented in an
 114 .IR off_t .
 115 .TP
 116 .B ESPIPE
 117 .I fd
 118 is associated with a pipe, socket, or FIFO.
 119 .SH "CONFORMING TO"
 120 SVr4, 4.3BSD, POSIX.1-2001.
 121 .SH NOTES
 122 This document's use of
 123 .I whence
 124 is incorrect English, but maintained for historical reasons.
 125
 126 Some devices are incapable of seeking and POSIX does not specify which
 127 devices must support
 128 .BR lseek ().
 129
 130 On Linux, using
 131 .BR lseek ()
 132 on a tty device returns
 133 \fBESPIPE\fP.
 134 .\" Other systems return the number of written characters,
 135 .\" using SEEK_SET to set the counter. (Of written characters.)
 136
 137 When converting old code, substitute values for \fIwhence\fP with the
 138 following macros:
 139 .TS
 140 c c
 141 l l.
 142 old     new
 143 0       SEEK_SET
 144 1       SEEK_CUR
 145 2       SEEK_END
 146 L_SET   SEEK_SET
 147 L_INCR  SEEK_CUR
 148 L_XTND  SEEK_END
 149 .TE
 150 .\" .PP
 151 .\" SVr1-3 returns \fIlong\fP instead of \fIoff_t\fP,
 152 .\" (ancient) BSD returns \fIint\fP.
 153 .PP
 154 Note that file descriptors created by
 155 .BR dup (2)
 156 or
 157 .BR fork (2)
 158 share the current file position pointer, so seeking on such files may be
 159 subject to race conditions.
 160 .SH "SEE ALSO"
 161 .BR dup (2),
 162 .BR fork (2),
 163 .BR open (2),
 164 .BR fseek (3),
 165 .BR lseek64 (3),
 166 .BR posix_fallocate (3)