diff options
Diffstat (limited to 'man/man3/lseek64.3')
| -rw-r--r-- | man/man3/lseek64.3 | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/man/man3/lseek64.3 b/man/man3/lseek64.3 new file mode 100644 index 000000000..e62a7238e --- /dev/null +++ b/man/man3/lseek64.3 @@ -0,0 +1,206 @@ +'\" 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 (date) "Linux man-pages (unreleased)" +.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> +.P +.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. +.P +For more details, return value, and errors, see +.BR lseek (2). +.P +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: +.P +.in +4n +.EX +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.EE +.in +.P +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 +.P +.in +4n +.EX +#define _FILE_OFFSET_BITS 64 +.EE +.in +.P +in which case it is a 64-bit signed type. +.SS lseek64() +Prototype: +.P +.in +4n +.EX +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.EE +.in +.P +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 +.P +.in +4n +.EX +#define _LARGEFILE64_SOURCE +.EE +.in +.P +The function +.BR lseek64 () +.\" in glibc 2.0.94, not in glibc 2.0.6 +is available since glibc 2.1. +.\" +.SS llseek() +Prototype: +.P +.in +4n +.EX +.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence ); +.EE +.in +.P +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 +.P +.in +4n +"the \`llseek\' function may be dangerous; use \`lseek64\' instead." +.in +.P +This makes this function unusable if one desires a warning-free +compilation. +.P +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: +.P +.in +4n +.EX +.BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo , +.BI " loff_t *" result ", int " whence ); +.EE +.in +.P +For more details, see +.BR llseek (2). +.P +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 +.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) |