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,