From patchwork Thu Nov 9 15:20:34 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 79494 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 6FDF53857359 for ; Thu, 9 Nov 2023 15:20:56 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by sourceware.org (Postfix) with ESMTPS id EA1E53858D1E for ; Thu, 9 Nov 2023 15:20:39 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org EA1E53858D1E 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 EA1E53858D1E Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2604:1380:4641:c500::1 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699543241; cv=none; b=xLAItWhszzSmAdh2MlfJttUO8nOBC1FRKvqDEbP+VtbYpXDCVAliJTSjahuz1AsDCukVXfR6EBdoAwg/RHinv4htAyuBC+sYTIiwAlo6Q1g0bV+OXuTVBxhaxhB+eFb7+7ygH/Z47RhtTcVNEF6HIGvUBZVcnXnya0FGqRWi1V0= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699543241; c=relaxed/simple; bh=Cz5yLL/KZDRFwBI7XXp+cRnzHEn71BxpFjPK1oN8QY4=; h=DKIM-Signature:Date:From:To:Subject:Message-ID:MIME-Version; b=sz/o2gESC6BjRPNjKS8CtW1Sl4S9Cp2v46s+CTJG5TDL3Rfl+gFIiYyZKIuIjctck10dcETb+bsnc8w0hT4ZgwzXkid1mHq2RU3fRWMWFlELq4WHT9VBiXcOvPph2tTRMvY+hOAwxpa9QKeFdsPHHnQLQoE0fu6xWbNw8/QCsAw= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 7F422617BE; Thu, 9 Nov 2023 15:20:39 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6FEE9C433C7; Thu, 9 Nov 2023 15:20:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1699543239; bh=Cz5yLL/KZDRFwBI7XXp+cRnzHEn71BxpFjPK1oN8QY4=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=O8YnmXeGCul3rJkEKRMsS43QRukXys47vbDoP7IFe6e7uQx/10rWd46603a8s2GtG 8D47M5N8hHzV4R33zuMdx82T7Ed9/84JDbjHaVhNBEfebyRxAe2ZPLWmzTzsp5b7mG iSiB9dMXSf7NaHKwWhsMADUUoq3/u3RCe7fYq71oUnzCB+sai8DByF1Mrcl9nkaGeK +mjo130DdHh1Yar2PYGIfpamotN2nVisKmJmaPlZzO+07WcfsiZIruGTRyqzJi/6qC X/YBGIrIst7A1OzUh8Ob4BFhI7Q5dBbr988htn4/thF4B4ynUU5fbRuB3LBKy07mU3 nzi/a7HoM4K2A== Date: Thu, 9 Nov 2023 16:20:34 +0100 From: Alejandro Colomar To: linux-man@vger.kernel.org Cc: Alejandro Colomar , libc-alpha@sourceware.org, DJ Delorie , Oskari Pirhonen , Jonny Grant , Matthew House , Thorsten Kukuk , Adhemerval Zanella Netto , Zack Weinberg , "G. Branden Robinson" , Carlos O'Donell , Paul Eggert , Xi Ruoyao Subject: [PATCH v2 1/2] stpncpy.3, string_copying.7: Clarify that st[rp]ncpy() do NOT produce a string Message-ID: <20231109151947.11174-2-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=-9.7 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 Acked-by: Oskari Pirhonen Cc: Jonny Grant Cc: Matthew House 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 --- Patch 1/2 is just a resend, with more CCs. Patch 2/2 is a new one further clarifying the wording, after Jonny's suggestions. 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,