.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>.
+.\" and Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.TH LSEEK64 3 2014-08-19 "Linux" "Linux Programmer's Manual"
+.TH LSEEK64 3 2021-03-22 "Linux" "Linux Programmer's Manual"
.SH NAME
lseek64 \- reposition 64-bit read/write file offset
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
.SH SYNOPSIS
+.nf
.BR "#define _LARGEFILE64_SOURCE" " /* See feature_test_macros(7) */"
-.br
.B #include <sys/types.h>
-.br
.B #include <unistd.h>
-.sp
+.PP
.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
+.fi
.SH DESCRIPTION
The
-.BR lseek (2)
+.BR lseek ()
family of functions reposition the offset of the open file associated
with the file descriptor
.I fd
or
.BR SEEK_END ,
respectively.
-.LP
+.PP
For more details, return value, and errors, see
.BR lseek (2).
.PP
Four interfaces are available:
-.BR lseek (2),
+.BR lseek (),
.BR lseek64 (),
-.BR llseek (2),
-and the raw system call
-.BR _llseek (2).
-.SS lseek
+.BR llseek (),
+and
+.BR _llseek ().
+.\"
+.\" For some background details, see:
+.\" https://lore.kernel.org/linux-man/CAKgNAkhNSWR3uYhYYaxx74fZfJ3JrpfAAPVrK0AFk_cAOUsbDg@mail.gmail.com/
+.\"
+.SS lseek()
Prototype:
-.nf
-.sp
+.PP
.in +4n
+.EX
.BI "off_t lseek(int " fd ", off_t " offset ", int " whence );
+.EE
.in
-.fi
-.sp
-.BR lseek (2)
-uses the type
+.PP
+The C library's
+.BR lseek ()
+wrapper function uses the type
.IR off_t .
This is a 32-bit signed type on 32-bit architectures, unless one
compiles with
-.nf
-.sp
+.PP
.in +4n
+.EX
#define _FILE_OFFSET_BITS 64
+.EE
.in
-.sp
-.fi
+.PP
in which case it is a 64-bit signed type.
-.SS lseek64
+.SS lseek64()
Prototype:
-.nf
-.sp
+.PP
.in +4n
+.EX
.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
+.EE
.in
-.fi
-.sp
-The library routine
+.PP
+The
.BR lseek64 ()
-uses a 64-bit type even when
+library function uses a 64-bit type even when
.I off_t
is a 32-bit type.
Its prototype (and the type
.IR off64_t )
is available only when one compiles with
-.nf
-.sp
+.PP
.in +4n
+.EX
#define _LARGEFILE64_SOURCE
+.EE
.in
-.sp
-.fi
+.PP
The function
.BR lseek64 ()
.\" in glibc 2.0.94, not in 2.0.6
-is available since glibc 2.1, and is defined to be an alias for
-.BR llseek ().
-.SS llseek
+is available since glibc 2.1.
+.\"
+.SS llseek()
Prototype:
-.nf
-.sp
+.PP
.in +4n
+.EX
.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence );
+.EE
.in
-.fi
-.sp
+.PP
The type
.I loff_t
is a 64-bit signed type.
-The library routine
+The
.BR llseek ()
-.\" in libc 5.0.9, not in 4.7.6
-is available in the glibc and works without special defines.
+library function is available in glibc and works without special defines.
However, the glibc headers do not provide a prototype.
Users should add
the above prototype, or something equivalent, to their own source.
When users complained about data loss caused by a miscompilation of
.BR e2fsck (8),
glibc 2.1.3 added the link-time warning
-.sp
+.PP
.in +4n
"the \`llseek\' function may be dangerous; use \`lseek64\' instead."
.in
-.sp
+.PP
This makes this function unusable if one desires a warning-free
compilation.
-.SS _llseek
-All the above functions are implemented in terms of this system call.
+.PP
+Since glibc 2.28,
+.\" glibc commit 5c5c0dd747070db624c8e2c43691cec854f114ef
+this function symbol is no longer available to newly linked applications.
+.\"
+.SS _llseek()
+On 32-bit architectures,
+this is the system call that is used (by the C library wrapper functions)
+to implement all of the above functions.
The prototype is:
-.nf
-.sp
+.PP
.in +4n
+.EX
.BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo ,
.BI " loff_t *" result ", int " whence );
+.EE
.in
-.fi
-.sp
+.PP
For more details, see
.BR llseek (2).
+.PP
+64-bit systems don't need an
+.BR _llseek ()
+system call.
+Instead, they have an
+.BR lseek (2)
+system call that supports 64-bit file offsets.
+.\" In arch/x86/entry/syscalls/syscall_32.tbl,
+.\" we see the following line:
+.\"
+.\" 140 i386 _llseek sys_llseek
+.\"
+.\" This is essentially telling us that 'sys_llseek' (the name generated
+.\" by SYSCALL_DEFINE5(llseek...)) is exposed to user-space as system call
+.\" number 140, and that system call number will (IIUC) be exposed in
+.\" autogenerated headers with the name "__NR__llseek" (i.e., "_llseek").
+.\" The "i386" is telling us that this happens in i386 (32-bit Intel).
+.\" There is nothing equivalent on x86-64, because 64 bit systems don't
+.\" need an _llseek system call.
.SH ATTRIBUTES
-.SS Multithreading (see pthreads(7))
-The
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR lseek64 ()
+T} Thread safety MT-Safe
+.TE
+.hy
+.ad
+.sp 1
+.SH NOTES
.BR lseek64 ()
-function is thread-safe.
+is one of the functions that was specified in the Large File Summit (LFS)
+specification that was completed in 1996.
+The purpose of the specification was to provide transitional support
+that allowed applications on 32-bit systems to access
+files whose size exceeds that which can be represented with a 32-bit
+.I off_t
+type.
+As noted above, this symbol is exposed by header files if the
+.B _LARGEFILE64_SOURCE
+feature test macro is defined.
+ALternatively, on a 32-bit system, the symbol
+.I lseek
+is aliased to
+.I lseek64
+if the macro
+.B _FILE_OFFSET_BITS
+is defined with the value 64.
.SH SEE ALSO
.BR llseek (2),
.BR lseek (2)
projects / thirdparty / man-pages.git / blobdiff