From patchwork Wed Nov 8 22:17:07 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 79445 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 70E84385696A for ; Wed, 8 Nov 2023 22:17:30 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by sourceware.org (Postfix) with ESMTPS id 7354B3858D1E for ; Wed, 8 Nov 2023 22:17:16 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 7354B3858D1E Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=kernel.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=kernel.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 7354B3858D1E Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=145.40.73.55 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699481838; cv=none; b=QpOLsYe5+j9INZEKPl+UqGSZcgBnrMpk5tLK6NxCisvEXRJ98aaalO7shGisWjqArZzhWG4gK+rscK9AeGnUDphgXw61qbHgU6FEhmJFWrCSOXE+1KkKFbjbuGWoLy0x+5Mg4vFqzcoMOaC/j6Dp88tYA0Dr/ts84679/KIX+2M= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699481838; c=relaxed/simple; bh=2S5sXH+2py0eaUILdptTbOb7kphjdcau/5OLWaDG+WM=; h=DKIM-Signature:Date:From:To:Subject:Message-ID:MIME-Version; b=whcIzj2faZ5YYpeXMXIBipmhrq94SL9Cua7hhVTBce5dhdRqpD9s1Ic2uG6IrkijbWb4LdM8OkRVTkxGk9rr1qNkzR5tA4QOQbcQUfAnww2zXzuLfSm6IA8d6pOYM1IYFONI0FXN7GtiRCJqtYIfv4oMUl8KsxS/hND37Ce7Orw= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id D0F76CE1152; Wed, 8 Nov 2023 22:17:13 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id AD0EDC433C8; Wed, 8 Nov 2023 22:17:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1699481833; bh=2S5sXH+2py0eaUILdptTbOb7kphjdcau/5OLWaDG+WM=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=M0YRAFobUmkhiQPo8+9zicBoNgtMGWnFoCXuyzNpyrsX6EwUIzC97ECPz0Zp9t6zz lMCZxUY87W46xmYv7tuOj92NSaH7pgmG9M8EZwaM8913nNKzgeLQHqxmN/ZEwqridv l5CP9fne7veYipIRqq88/S0GTYiInu/vocvVs7menb3KmMrzLilnt502+ry1vcTxlc V83no/6lrljSa+2o6mzoYLtV0CY56LMcg6wGhw/UZY1mtFOtcomR+flhiNjPdwEyKk gH7bZeyJCCx0qJbI7JGuk90L4dbRmE81MuiiKcWEkxyKt7NgJl3+jhUqp+ukz2rvYA mw84jO27frQQQ== Date: Wed, 8 Nov 2023 23:17:07 +0100 From: Alejandro Colomar To: linux-man@vger.kernel.org Cc: Alejandro Colomar , libc-alpha@sourceware.org, DJ Delorie , Jonny Grant , Matthew House , Oskari Pirhonen , Thorsten Kukuk , Adhemerval Zanella Netto , Zack Weinberg , "G. Branden Robinson" , Carlos O'Donell Subject: [PATCH] stpncpy.3, string_copying.7: Clarify that st[rp]ncpy() do NOT produce a string Message-ID: <20231108221638.37101-2-alx@kernel.org> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: X-Mailer: git-send-email 2.42.0 X-Spam-Status: No, score=-10.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org These copy *from* a string. But the destination is a simple character sequence within an array; not a string. Suggested-by: DJ Delorie Cc: Jonny Grant Cc: Matthew House Cc: Oskari Pirhonen Cc: Thorsten Kukuk Cc: Adhemerval Zanella Netto Cc: Zack Weinberg Cc: "G. Branden Robinson" Cc: Carlos O'Donell Signed-off-by: Alejandro Colomar --- Resending, including the mailing lists, which I forgot. man3/stpncpy.3 | 17 +++++++++++++---- man7/string_copying.7 | 20 ++++++++++---------- 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 index b6bbfd0a3..f86ff8c29 100644 --- a/man3/stpncpy.3 +++ b/man3/stpncpy.3 @@ -6,9 +6,8 @@ .TH stpncpy 3 (date) "Linux man-pages (unreleased)" .SH NAME stpncpy, strncpy -\- zero a fixed-width buffer and -copy a string into a character sequence with truncation -and zero the rest of it +\- +fill a fixed-width null-padded buffer with bytes from a string .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) @@ -37,7 +36,7 @@ .SH SYNOPSIS _GNU_SOURCE .fi .SH DESCRIPTION -These functions copy the string pointed to by +These functions copy bytes from the string pointed to by .I src into a null-padded character sequence at the fixed-width buffer pointed to by .IR dst . @@ -110,6 +109,16 @@ .SH CAVEATS These functions produce a null-padded character sequence, not a string (see .BR string_copying (7)). +For example: +.P +.in +4n +.EX +strncpy(buf, "1", 5); // { \[aq]1\[aq], 0, 0, 0, 0 } +strncpy(buf, "1234", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], 0 } +strncpy(buf, "12345", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +strncpy(buf, "123456", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +.EE +.in .P It's impossible to distinguish truncation by the result of the call, from a character sequence that just fits the destination buffer; diff --git a/man7/string_copying.7 b/man7/string_copying.7 index cadf1c539..0e179ba34 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -41,15 +41,11 @@ .SS Strings .\" ----- SYNOPSIS :: Null-padded character sequences --------/ .SS Null-padded character sequences .nf -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *stpncpy(char " dst "[restrict ." sz "], \ +// Fill a fixed-width null-padded buffer with bytes from a string. +.BI "char *strncpy(char " dst "[restrict ." sz "], \ const char *restrict " src , .BI " size_t " sz ); -.P -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *strncpy(char " dst "[restrict ." sz "], \ +.BI "char *stpncpy(char " dst "[restrict ." sz "], \ const char *restrict " src , .BI " size_t " sz ); .P @@ -240,14 +236,18 @@ .SS Truncate or not? .\" ----- DESCRIPTION :: Null-padded character sequences --------------/ .SS Null-padded character sequences For historic reasons, -some standard APIs, +some standard APIs and file formats, such as -.BR utmpx (5), +.BR utmpx (5) +and +.BR tar (1), use null-padded character sequences in fixed-width buffers. To interface with them, specialized functions need to be used. .P -To copy strings into them, use +To copy bytes from strings into these buffers, use +.BR strncpy (3) +or .BR stpncpy (3). .P To copy from an unterminated string within a fixed-width buffer into a string, From patchwork Thu Nov 9 15:20:39 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 79495 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2DD66385828D for ; Thu, 9 Nov 2023 15:21:02 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from ams.source.kernel.org (ams.source.kernel.org [145.40.68.75]) by sourceware.org (Postfix) with ESMTPS id 61F223858425 for ; Thu, 9 Nov 2023 15:20:45 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 61F223858425 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=kernel.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=kernel.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 61F223858425 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=145.40.68.75 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699543246; cv=none; b=V+JnufTmNRfF0oy2Bia36k8yhWK38MKqAY8p9HFp53Z6fzVj3K6HhB1Cd0BoBdP8uBKeB6J85VXQujApv+ybFGKXunIM73a6lb14tNqSEZI5JPMHy4FIxjLunvFxF9vkr9zobaHjpwY72+JyYVco3tDC6Ea1/40MlukwCywpL4o= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699543246; c=relaxed/simple; bh=YzFuP0/H5/07clwoKJrhupQ0PCXz/xmxy+i2aHumR+Q=; h=DKIM-Signature:Date:From:To:Subject:Message-ID:MIME-Version; b=d8SjUCXdopdNAS59p3b0ZueFtl6pAdQA9bBm6JRP67Zjgmce/5PqyT9ps+Sdgy6v52xQe4BjasbvFTFDZNj1lVZMQ2Xn6IpwS0fkdd9Ay0guia4ZlBXKIl/VFytabgqz3xEoeM0ekCgZWmv72XILDti7jy1GrB+vWMxNUSe2hVI= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by ams.source.kernel.org (Postfix) with ESMTP id 6605FB82128; Thu, 9 Nov 2023 15:20:44 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 172E2C433C7; Thu, 9 Nov 2023 15:20:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1699543243; bh=YzFuP0/H5/07clwoKJrhupQ0PCXz/xmxy+i2aHumR+Q=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=X7QTgezANdVC16Yb/gE1RmdmmPCidqeYeV19rxZgn9Qk0y7L1Hc/S2eD3VbMKXhm+ CqNacaOR7OHnPAspACZVTxZzmHM5bWdQZV6Q16dO0tZPmZr0zjM6UdlSSsgIw6EMtJ +B6UDbf/+WMxsdTw+Fe7kodckTPYW7dl4etOEtmUO99coTD7xrezAtBVSVKZ+1Ba4h 8f3lRanhKcNx3B+E7q+OEWCbAAsvFKI+i/JX486lSoLEi8hnBvaRd76lF0xqHHD1J3 ndaJLOZAMg/K5pWRApjakh3oOOl++W9J4LtfjX4mSE7UhhaWmGw0TJe2HQFnKgVbfL LrI8k6w+XW1HA== Date: Thu, 9 Nov 2023 16:20:39 +0100 From: Alejandro Colomar To: linux-man@vger.kernel.org Cc: Alejandro Colomar , libc-alpha@sourceware.org, Jonny Grant , DJ Delorie , Matthew House , Oskari Pirhonen , Thorsten Kukuk , Adhemerval Zanella Netto , Zack Weinberg , "G. Branden Robinson" , Carlos O'Donell , Paul Eggert , Xi Ruoyao Subject: [PATCH v2 2/2] stpncpy.3, string.3, string_copying.7: Clarify that st[rp]ncpy() pad with null bytes Message-ID: <20231109151947.11174-3-alx@kernel.org> References: <20231108221638.37101-2-alx@kernel.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20231108221638.37101-2-alx@kernel.org> X-Mailer: git-send-email 2.42.0 X-Spam-Status: No, score=-10.1 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org The previous wording could be interpreted as if the nulls were already in place. Clarify that it's this function which pads with null bytes. Also, it copies "characters" from the src string. That's a bit more specific than copying "bytes", and makes it clearer that the terminating null byte in src is not part of the copy. Suggested-by: Jonny Grant Cc: DJ Delorie Cc: Jonny Grant Cc: Matthew House Cc: Oskari Pirhonen Cc: Thorsten Kukuk Cc: Adhemerval Zanella Netto Cc: Zack Weinberg Cc: "G. Branden Robinson" Cc: Carlos O'Donell Cc: Paul Eggert Cc: Xi Ruoyao Signed-off-by: Alejandro Colomar --- man3/stpncpy.3 | 10 ++++++---- man3/string.3 | 11 ++--------- man7/string_copying.7 | 3 ++- 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 index f86ff8c29..3cf4eb371 100644 --- a/man3/stpncpy.3 +++ b/man3/stpncpy.3 @@ -7,7 +7,8 @@ .SH NAME stpncpy, strncpy \- -fill a fixed-width null-padded buffer with bytes from a string +fill a fixed-width buffer with characters from a string +and pad with null bytes .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) @@ -36,10 +37,11 @@ .SH SYNOPSIS _GNU_SOURCE .fi .SH DESCRIPTION -These functions copy bytes from the string pointed to by +These functions copy characters from the string pointed to by .I src -into a null-padded character sequence at the fixed-width buffer pointed to by -.IR dst . +into a character sequence at the fixed-width buffer pointed to by +.IR dst , +and pad with null bytes. If the destination buffer, limited by its size, isn't large enough to hold the copy, diff --git a/man3/string.3 b/man3/string.3 index aba5efd2b..bd8b342a6 100644 --- a/man3/string.3 +++ b/man3/string.3 @@ -179,21 +179,14 @@ .SH SYNOPSIS .I n bytes to .IR dest . -.SS Obsolete functions .TP .nf .BI "char *strncpy(char " dest "[restrict ." n "], \ const char " src "[restrict ." n ], .BI " size_t " n ); .fi -Copy at most -.I n -bytes from string -.I src -to -.IR dest , -returning a pointer to the start of -.IR dest . +Fill a fixed‐width buffer with characters from a string +and pad with null bytes. .SH DESCRIPTION The string functions perform operations on null-terminated strings. diff --git a/man7/string_copying.7 b/man7/string_copying.7 index 0e179ba34..865271c6f 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -41,7 +41,8 @@ .SS Strings .\" ----- SYNOPSIS :: Null-padded character sequences --------/ .SS Null-padded character sequences .nf -// Fill a fixed-width null-padded buffer with bytes from a string. +// Fill a fixed-width buffer with characters from a string +// and pad with null bytes. .BI "char *strncpy(char " dst "[restrict ." sz "], \ const char *restrict " src , .BI " size_t " sz );