man3/lseek64.3

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