man3/lseek64.3

   1 .\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>.
   2 .\" and Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH LSEEK64 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 lseek64 \- reposition 64-bit read/write file offset
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#define _LARGEFILE64_SOURCE" "     /* See feature_test_macros(7) */"
  32 .B #include <sys/types.h>
  33 .B #include <unistd.h>
  34 .PP
  35 .BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR lseek ()
  40 family of functions reposition the offset of the open file associated
  41 with the file descriptor
  42 .I fd
  43 to
  44 .I offset
  45 bytes relative to the start, current position, or end of the file,
  46 when
  47 .I whence
  48 has the value
  49 .BR SEEK_SET ,
  50 .BR SEEK_CUR ,
  51 or
  52 .BR SEEK_END ,
  53 respectively.
  54 .PP
  55 For more details, return value, and errors, see
  56 .BR lseek (2).
  57 .PP
  58 Four interfaces are available:
  59 .BR lseek (),
  60 .BR lseek64 (),
  61 .BR llseek (),
  62 and
  63 .BR _llseek ().
  64 .\"
  65 .\" For some background details, see:
  66 .\" https://lore.kernel.org/linux-man/CAKgNAkhNSWR3uYhYYaxx74fZfJ3JrpfAAPVrK0AFk_cAOUsbDg@mail.gmail.com/
  67 .\"
  68 .SS lseek()
  69 Prototype:
  70 .PP
  71 .in +4n
  72 .EX
  73 .BI "off_t lseek(int " fd ", off_t " offset ", int " whence );
  74 .EE
  75 .in
  76 .PP
  77 The C library's
  78 .BR lseek ()
  79 wrapper function uses the type
  80 .IR off_t .
  81 This is a 32-bit signed type on 32-bit architectures, unless one
  82 compiles with
  83 .PP
  84 .in +4n
  85 .EX
  86 #define _FILE_OFFSET_BITS 64
  87 .EE
  88 .in
  89 .PP
  90 in which case it is a 64-bit signed type.
  91 .SS lseek64()
  92 Prototype:
  93 .PP
  94 .in +4n
  95 .EX
  96 .BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
  97 .EE
  98 .in
  99 .PP
 100 The
 101 .BR lseek64 ()
 102 library function uses a 64-bit type even when
 103 .I off_t
 104 is a 32-bit type.
 105 Its prototype (and the type
 106 .IR off64_t )
 107 is available only when one compiles with
 108 .PP
 109 .in +4n
 110 .EX
 111 #define _LARGEFILE64_SOURCE
 112 .EE
 113 .in
 114 .PP
 115 The function
 116 .BR lseek64 ()
 117 .\" in glibc 2.0.94, not in 2.0.6
 118 is available since glibc 2.1.
 119 .\"
 120 .SS llseek()
 121 Prototype:
 122 .PP
 123 .in +4n
 124 .EX
 125 .BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence );
 126 .EE
 127 .in
 128 .PP
 129 The type
 130 .I loff_t
 131 is a 64-bit signed type.
 132 The
 133 .BR llseek ()
 134 library function is available in glibc and works without special defines.
 135 However, the glibc headers do not provide a prototype.
 136 Users should add
 137 the above prototype, or something equivalent, to their own source.
 138 When users complained about data loss caused by a miscompilation of
 139 .BR e2fsck (8),
 140 glibc 2.1.3 added the link-time warning
 141 .PP
 142 .in +4n
 143 "the \`llseek\' function may be dangerous; use \`lseek64\' instead."
 144 .in
 145 .PP
 146 This makes this function unusable if one desires a warning-free
 147 compilation.
 148 .PP
 149 Since glibc 2.28,
 150 .\" glibc commit 5c5c0dd747070db624c8e2c43691cec854f114ef
 151 this function symbol is no longer available to newly linked applications.
 152 .\"
 153 .SS _llseek()
 154 On 32-bit architectures,
 155 this is the system call that is used (by the C library wrapper functions)
 156 to implement all of the above functions.
 157 The prototype is:
 158 .PP
 159 .in +4n
 160 .EX
 161 .BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo ,
 162 .BI "            loff_t *" result ", int " whence );
 163 .EE
 164 .in
 165 .PP
 166 For more details, see
 167 .BR llseek (2).
 168 .PP
 169 64-bit systems don't need an
 170 .BR _llseek ()
 171 system call.
 172 Instead, they have an
 173 .BR lseek (2)
 174 system call that supports 64-bit file offsets.
 175 .\" In arch/x86/entry/syscalls/syscall_32.tbl,
 176 .\" we see the following line:
 177 .\"
 178 .\"    140     i386    _llseek                 sys_llseek
 179 .\"
 180 .\" This is essentially telling us that 'sys_llseek' (the name generated
 181 .\" by SYSCALL_DEFINE5(llseek...)) is exposed to user-space as system call
 182 .\" number 140, and that system call number will (IIUC) be exposed in
 183 .\" autogenerated headers with the name "__NR__llseek" (i.e., "_llseek").
 184 .\" The "i386" is telling us that this happens in i386 (32-bit Intel).
 185 .\" There is nothing equivalent on x86-64, because 64 bit systems don't
 186 .\" need an _llseek system call.
 187 .SH ATTRIBUTES
 188 For an explanation of the terms used in this section, see
 189 .BR attributes (7).
 190 .ad l
 191 .nh
 192 .TS
 193 allbox;
 194 lbx lb lb
 195 l l l.
 196 Interface       Attribute       Value
 197 T{
 198 .BR lseek64 ()
 199 T}      Thread safety   MT-Safe
 200 .TE
 201 .hy
 202 .ad
 203 .sp 1
 204 .SH NOTES
 205 .BR lseek64 ()
 206 is one of the functions that was specified in the Large File Summit (LFS)
 207 specification that was completed in 1996.
 208 The purpose of the specification was to provide transitional support
 209 that allowed applications on 32-bit systems to access
 210 files whose size exceeds that which can be represented with a 32-bit
 211 .IR off_t
 212 type.
 213 As noted above, this symbol is exposed by header files if the
 214 .B _LARGEFILE64_SOURCE
 215 feature test macro is defined.
 216 ALternatively, on a 32-bit system, the symbol
 217 .I lseek
 218 is aliased to
 219 .I lseek64
 220 if the macro
 221 .B _FILE_OFFSET_BITS
 222 is defined with the value 64.
 223 .SH SEE ALSO
 224 .BR llseek (2),
 225 .BR lseek (2)