summaryrefslogtreecommitdiffstats
path: root/man3/lseek64.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/lseek64.3')
-rw-r--r--man3/lseek64.3207
1 files changed, 207 insertions, 0 deletions
diff --git a/man3/lseek64.3 b/man3/lseek64.3
new file mode 100644
index 0000000..aee84ed
--- /dev/null
+++ b/man3/lseek64.3
@@ -0,0 +1,207 @@
+'\" t
+.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>.
+.\" and Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH lseek64 3 2023-07-20 "Linux man-pages 6.05.01"
+.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) */"
+.B #include <sys/types.h>
+.B #include <unistd.h>
+.PP
+.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
+.fi
+.SH DESCRIPTION
+The
+.BR lseek ()
+family of functions reposition the offset of the open file associated
+with the file descriptor
+.I fd
+to
+.I offset
+bytes relative to the start, current position, or end of the file,
+when
+.I whence
+has the value
+.BR SEEK_SET ,
+.BR SEEK_CUR ,
+or
+.BR SEEK_END ,
+respectively.
+.PP
+For more details, return value, and errors, see
+.BR lseek (2).
+.PP
+Four interfaces are available:
+.BR lseek (),
+.BR lseek64 (),
+.BR llseek (),
+and
+.BR _llseek ().
+.\"
+.\" For some background details, see:
+.\" https://lore.kernel.org/linux-man/CAKgNAkhNSWR3uYhYYaxx74fZfJ3JrpfAAPVrK0AFk_cAOUsbDg@mail.gmail.com/
+.\"
+.SS lseek()
+Prototype:
+.PP
+.in +4n
+.EX
+.BI "off_t lseek(int " fd ", off_t " offset ", int " whence );
+.EE
+.in
+.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
+.PP
+.in +4n
+.EX
+#define _FILE_OFFSET_BITS 64
+.EE
+.in
+.PP
+in which case it is a 64-bit signed type.
+.SS lseek64()
+Prototype:
+.PP
+.in +4n
+.EX
+.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
+.EE
+.in
+.PP
+The
+.BR lseek64 ()
+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
+.PP
+.in +4n
+.EX
+#define _LARGEFILE64_SOURCE
+.EE
+.in
+.PP
+The function
+.BR lseek64 ()
+.\" in glibc 2.0.94, not in glibc 2.0.6
+is available since glibc 2.1.
+.\"
+.SS llseek()
+Prototype:
+.PP
+.in +4n
+.EX
+.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence );
+.EE
+.in
+.PP
+The type
+.I loff_t
+is a 64-bit signed type.
+The
+.BR llseek ()
+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
+.PP
+.in +4n
+"the \`llseek\' function may be dangerous; use \`lseek64\' instead."
+.in
+.PP
+This makes this function unusable if one desires a warning-free
+compilation.
+.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:
+.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
+.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
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR lseek64 ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH NOTES
+.BR lseek64 ()
+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)