From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-3.4 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 8993 invoked from network); 9 Jul 2023 06:11:07 -0000 Received: from second.openwall.net (193.110.157.125) by inbox.vuxu.org with ESMTPUTF8; 9 Jul 2023 06:11:07 -0000 Received: (qmail 20244 invoked by uid 550); 9 Jul 2023 06:11:00 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-ID: Reply-To: musl@lists.openwall.com Received: (qmail 20194 invoked from network); 9 Jul 2023 06:11:00 -0000 DKIM-Filter: OpenDKIM Filter v2.10.3 mail.cs.ucla.edu C4B813C011BD6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cs.ucla.edu; s=9D0B346E-2AEB-11ED-9476-E14B719DCE6C; t=1688883045; bh=cgPuasBwtiMV/C1s/9eiqlempgm38wvmiPIbje1R1qs=; h=From:To:Date:Message-ID:MIME-Version; b=W/BFlU3EJZPBMRdA6D1SfimfISJyJQ4Kd9iJZ1S0Y4dMfjzQadeob3bZXFtNeki97 WjP1DE3CnE0NWkpTLmCuix2SlICqtTuWvL1+7ZYGSp5iKPi3EiqOTpOPC3SdYgmz3L +0BMSgAska19skoXc6qB4yA6W6YBOYkb+mNsDqONwgz4Dz956iccgGqT3jQV3c01lc tHI6CnbqB1zV4mNaxlalVKs4lZojPlchtVMDn9ITY/esTxa/qrVfvTCfBaPVLzkaRj 8XkZTZOkZ6mqQ0td+C3ekJT4CYtO8Sdz1eQTHD3lj1z1qmpAgQUrlciYpF+psKxRDj Q+l6u8/AfkFoQ== X-Virus-Scanned: amavisd-new at mail.cs.ucla.edu From: Paul Eggert To: Alejandro Colomar , "A . Wilcox" , libc-coord@lists.openwall.com, Jonathan Wakely , Rich Felker , linux-man@vger.kernel.org, libc-alpha@sourceware.org, musl@lists.openwall.com, Sam James , Szabolcs Nagy , Jakub Wilk Cc: Paul Eggert Date: Sat, 8 Jul 2023 23:07:55 -0700 Message-ID: <20230709061011.1885809-1-eggert@cs.ucla.edu> X-Mailer: git-send-email 2.41.0 In-Reply-To: <78b648da-dde7-d331-7384-03214b977e6d@kernel.org> References: <78b648da-dde7-d331-7384-03214b977e6d@kernel.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Subject: [musl] [PATCH v4] off64_t: prefer off_t for splice, etc. For the few functions that come only in 64-bit off_t flavors, document their APIs as using off_t instead of off64_t, and say also that code should #define _FILE_OFFSET_BITS 64. This documents what user code is (and should be) doing anyway, if it needs to work on traditional x86 and ARM Linux. --- man2/copy_file_range.2 | 20 +++++++++++++++++--- man2/readahead.2 | 11 ++++++++++- man2/splice.2 | 17 +++++++++++++++-- man2/sync_file_range.2 | 12 ++++++++++-- man3/fopencookie.3 | 17 ++++++++++++++--- man7/feature_test_macros.7 | 12 ++++++++---- 6 files changed, 74 insertions(+), 15 deletions(-) diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 index 6f3aa4971..42b950d66 100644 --- a/man2/copy_file_range.2 +++ b/man2/copy_file_range.2 @@ -11,10 +11,11 @@ Standard C library .SH SYNOPSIS .nf .B #define _GNU_SOURCE +.B #define _FILE_OFFSET_BITS 64 .B #include .PP -.BI "ssize_t copy_file_range(int " fd_in ", off64_t *_Nullable " off_in = , -.BI " int " fd_out ", off64_t *_Nullable " off_ou= t , +.BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in , +.BI " int " fd_out ", off_t *_Nullable " off_out = , .BI " size_t " len ", unsigned int " flags ); .fi .SH DESCRIPTION @@ -224,6 +225,18 @@ gives filesystems an opportunity to implement "copy = acceleration" techniques, such as the use of reflinks (i.e., two or more inodes that share pointers to the same copy-on-write disk blocks) or server-side-copy (in the case of NFS). +.PP +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I off_in +or +.I off_out +or that takes the address of +.BR copy_file_range , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. .SH BUGS In Linux 5.3 to Linux 5.18, cross-filesystem copies were implemented by the kernel, @@ -234,6 +247,7 @@ the call failed to copy, while still reporting succes= s. .\" SRC BEGIN (copy_file_range.c) .EX #define _GNU_SOURCE +#define _FILE_OFFSET_BITS 64 #include #include #include @@ -244,7 +258,7 @@ int main(int argc, char *argv[]) { int fd_in, fd_out; - off64_t len, ret; + off_t len, ret; struct stat stat; \& if (argc !=3D 3) { diff --git a/man2/readahead.2 b/man2/readahead.2 index d69795979..64e57cdca 100644 --- a/man2/readahead.2 +++ b/man2/readahead.2 @@ -14,9 +14,10 @@ Standard C library .SH SYNOPSIS .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */= " +.B #define _FILE_OFFSET_BITS 64 .B #include .PP -.BI "ssize_t readahead(int " fd ", off64_t " offset ", size_t " count ); +.BI "ssize_t readahead(int " fd ", off_t " offset ", size_t " count ); .fi .SH DESCRIPTION .BR readahead () @@ -73,6 +74,14 @@ Linux. .SH HISTORY Linux 2.4.13, glibc 2.3. +.SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses a pointer to +.BR readahead , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. .SH BUGS .BR readahead () attempts to schedule the reads in the background and return immediately. diff --git a/man2/splice.2 b/man2/splice.2 index dd78e8cd4..cd4ed35cb 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -12,10 +12,11 @@ Standard C library .SH SYNOPSIS .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#define _FILE_OFFSET_BITS 64 .B #include .PP -.BI "ssize_t splice(int " fd_in ", off64_t *_Nullable " off_in , -.BI " int " fd_out ", off64_t *_Nullable " off_out , +.BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in , +.BI " int " fd_out ", off_t *_Nullable " off_out , .BI " size_t " len ", unsigned int " flags ); .\" Return type was long before glibc 2.7 .fi @@ -242,6 +243,18 @@ only pointers are copied, not the pages of the buffe= r. .\" the data and choose to forward it to two or more different .\" users - for things like logging etc.). .\" +.PP +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I off_in +or +.I off_out +or that takes the address of +.BR splice , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. .SH EXAMPLES See .BR tee (2). diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index d633b08ff..31d7e5112 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -16,9 +16,10 @@ Standard C library .SH SYNOPSIS .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 .B #include .PP -.BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbyte= s , +.BI "int sync_file_range(int " fd ", off_t " offset ", off_t " nbytes , .BI " unsigned int " flags ); .fi .SH DESCRIPTION @@ -176,7 +177,7 @@ system call that orders the arguments suitably: .in +4n .EX .BI "int sync_file_range2(int " fd ", unsigned int " flags , -.BI " off64_t " offset ", off64_t " nbytes ); +.BI " off_t " offset ", off_t " nbytes ); .EE .in .PP @@ -198,6 +199,13 @@ glibc transparently wraps under the name .BR sync_file_range (). .SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that takes the address of +.BR sync_file_range , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. .SH SEE ALSO .BR fdatasync (2), .BR fsync (2), diff --git a/man3/fopencookie.3 b/man3/fopencookie.3 index 409a3c81a..3a68746cc 100644 --- a/man3/fopencookie.3 +++ b/man3/fopencookie.3 @@ -13,6 +13,7 @@ Standard C library .SH SYNOPSIS .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 .B #include .PP .BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict "= mode , @@ -169,7 +170,7 @@ When called, it receives three arguments: .IP .in +4n .EX -int seek(void *cookie, off64_t *offset, int whence); +int seek(void *cookie, off_t *offset, int whence); .EE .in .IP @@ -351,9 +352,9 @@ memfile_read(void *c, char *buf, size_t size) } \& int -memfile_seek(void *c, off64_t *offset, int whence) +memfile_seek(void *c, off_t *offset, int whence) { - off64_t new_offset; + off_t new_offset; struct memfile_cookie *cookie =3D c; \& if (whence =3D=3D SEEK_SET) @@ -451,6 +452,16 @@ main(int argc, char *argv[]) } .EE .\" SRC END +.SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I seek +or that takes the address of +.BR fopencookie , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. .SH SEE ALSO .BR fclose (3), .BR fmemopen (3), diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index f1620611c..10e973dbc 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -113,15 +113,16 @@ feature test macro requirements (this example from .RS +4 .EX .B #define _GNU_SOURCE +.B #define _FILE_OFFSET_BITS 64 .B #include .PP -.BI "ssize_t readahead(int " fd ", off64_t *" offset ", size_t " count )= ; +.BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); .EE .RE .PP -This format is employed in cases where only a single -feature test macro can be used to expose the function -declaration, and that macro is not defined by default. +This format is employed when the feature test macros ensure +that the proper function declarations are visible, +and the macros are not defined by default. .SS Feature test macros understood by glibc The paragraphs below explain how feature test macros are handled in glibc 2.\fIx\fP, @@ -406,6 +407,9 @@ related to file I/O and filesystem operations into re= ferences to their 64-bit counterparts. This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. +It is also useful when calling functions like +.BR copy_file_range (2) +that were added more recently and that come only in 64-bit flavors. (Defining this macro permits correctly written programs to use large files with only a recompilation being required.) .IP --=20 2.41.0