Debian Codegraph @

upstream/debian-unstable/man3/lseek64.3

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