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 2001-09-24 "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 " fildes ", 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 fildes
  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 ('\\0') 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 Otherwise, a value of \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 fildes
  98 is not an open file descriptor.
  99 .TP
 100 .B EINVAL
 101 .I whence
 102 is not one of SEEK_SET, SEEK_CUR, SEEK_END;
 103 or the resulting file offset would be negative,
 104 or beyond the end of a seekable device.
 105 .\" Some systems may allow negative offsets for character devices
 106 .\" and/or for remote filesystems.
 107 .TP
 108 .B EOVERFLOW
 109 .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW)
 110 The resulting file offset cannot be represented in an
 111 .IR off_t .
 112 .TP
 113 .B ESPIPE
 114 .I fildes
 115 is associated with a pipe, socket, or FIFO.
 116 .SH "CONFORMING TO"
 117 SVr4, 4.3BSD, POSIX.1-2001.
 118 .SH RESTRICTIONS
 119 Some devices are incapable of seeking and POSIX does not specify which
 120 devices must support
 121 .BR lseek ().
 122
 123 Linux specific restrictions: using \fBlseek\fP() on a tty device returns
 124 \fBESPIPE\fP.
 125 .\" Other systems return the number of written characters,
 126 .\" using SEEK_SET to set the counter. (Of written characters.)
 127 .SH NOTES
 128 This document's use of
 129 .I whence
 130 is incorrect English, but maintained for historical reasons.
 131
 132 When converting old code, substitute values for \fIwhence\fP with the
 133 following macros:
 134 .TS
 135 c c
 136 l l.
 137 old     new
 138 0       SEEK_SET
 139 1       SEEK_CUR
 140 2       SEEK_END
 141 L_SET   SEEK_SET
 142 L_INCR  SEEK_CUR
 143 L_XTND  SEEK_END
 144 .TE
 145 .PP
 146 SVr1-3 returns \fIlong\fP instead of \fIoff_t\fP, BSD returns \fIint\fP.
 147 .PP
 148 Note that file descriptors created by
 149 .BR dup (2)
 150 or
 151 .BR fork (2)
 152 share the current file position pointer, so seeking on such files may be
 153 subject to race conditions.
 154 .SH "SEE ALSO"
 155 .BR dup (2),
 156 .BR fork (2),
 157 .BR open (2),
 158 .BR fseek (3),
 159 .BR lseek64 (3),
 160 .BR posix_fallocate (3)