From: Alejandro Colomar <alx@kernel.org>
To: linux-man@vger.kernel.org
Cc: Alejandro Colomar <alx@kernel.org>,
libc-alpha@sourceware.org, DJ Delorie <dj@redhat.com>,
Jonny Grant <jg@jguk.org>,
Matthew House <mattlloydhouse@gmail.com>,
Oskari Pirhonen <xxc3ncoredxx@gmail.com>,
Thorsten Kukuk <kukuk@suse.com>,
Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>,
Zack Weinberg <zack@owlfolio.org>,
"G. Branden Robinson" <g.branden.robinson@gmail.com>,
Carlos O'Donell <carlos@redhat.com>
Subject: [PATCH] stpncpy.3, string_copying.7: Clarify that st[rp]ncpy() do NOT produce a string
Date: Wed, 8 Nov 2023 23:17:07 +0100 [thread overview]
Message-ID: <20231108221638.37101-2-alx@kernel.org> (raw)
In-Reply-To: <ZUwCwxyPfur-hfea@debian>
[-- Attachment #1: Type: text/plain, Size: 3837 bytes --]
These copy *from* a string. But the destination is a simple character
sequence within an array; not a string.
Suggested-by: DJ Delorie <dj@redhat.com>
Cc: Jonny Grant <jg@jguk.org>
Cc: Matthew House <mattlloydhouse@gmail.com>
Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Thorsten Kukuk <kukuk@suse.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
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,
--
2.42.0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2023-11-08 22:17 UTC|newest]
Thread overview: 77+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <cfbd8674-fe6a-4430-95f1-ec8bde7da32e@jguk.org>
[not found] ` <ZUacobMq0l_O8gjg@debian>
[not found] ` <aeb55af5-1017-4ffd-9824-30b43d5748e3@jguk.org>
[not found] ` <ZUgl2HPJvUge7XYN@debian>
[not found] ` <d40fffcb-524d-44b6-a252-b55a8ddc9fee@jguk.org>
[not found] ` <ZUo6btEFD_z_3NcF@devuan>
[not found] ` <929865e3-17b4-49c4-8fa9-8383885e9904@jguk.org>
[not found] ` <ZUpjI1AHNOMOjdFk@devuan>
[not found] ` <ZUsoIbhrJar6ojux@dj3ntoo>
2023-11-08 9:51 ` strncpy clarify result may not be null terminated Alejandro Colomar
2023-11-08 9:59 ` Thorsten Kukuk
2023-11-08 15:09 ` Alejandro Colomar
[not found] ` <6bcad2492ab843019aa63895beaea2ce@DB6PR04MB3255.eurprd04.prod.outlook.com>
2023-11-08 15:44 ` Thorsten Kukuk
2023-11-08 17:26 ` Adhemerval Zanella Netto
2023-11-08 14:06 ` Zack Weinberg
2023-11-08 15:07 ` Alejandro Colomar
2023-11-08 21:35 ` Carlos O'Donell
2023-11-08 22:11 ` Alejandro Colomar
2023-11-08 23:31 ` Paul Eggert
2023-11-09 0:29 ` Alejandro Colomar
2023-11-09 10:13 ` Jonny Grant
2023-11-09 11:08 ` catenate vs concatenate (was: strncpy clarify result may not be null terminated) Alejandro Colomar
2023-11-09 14:06 ` catenate vs concatenate Jonny Grant
2023-11-27 14:33 ` catenate vs concatenate (was: strncpy clarify result may not be null terminated) Zack Weinberg
2023-11-27 15:08 ` Alejandro Colomar
2023-11-27 15:13 ` Alejandro Colomar
2023-11-27 16:59 ` G. Branden Robinson
2023-11-27 18:35 ` Zack Weinberg
2023-11-27 23:45 ` G. Branden Robinson
2023-11-09 11:13 ` strncpy clarify result may not be null terminated Alejandro Colomar
2023-11-09 14:05 ` Jonny Grant
2023-11-09 15:04 ` Alejandro Colomar
2023-11-08 19:04 ` DJ Delorie
2023-11-08 19:40 ` Alejandro Colomar
2023-11-08 19:58 ` DJ Delorie
2023-11-08 20:13 ` Alejandro Colomar
2023-11-08 21:07 ` DJ Delorie
2023-11-08 21:50 ` Alejandro Colomar
2023-11-08 22:17 ` Alejandro Colomar [this message]
2023-11-08 23:06 ` [PATCH] stpncpy.3, string_copying.7: Clarify that st[rp]ncpy() do NOT produce a string Paul Eggert
2023-11-08 23:28 ` DJ Delorie
2023-11-09 0:24 ` Alejandro Colomar
2023-11-09 14:11 ` Jonny Grant
2023-11-09 14:35 ` Alejandro Colomar
2023-11-09 14:47 ` Jonny Grant
2023-11-09 15:02 ` Alejandro Colomar
2023-11-09 17:30 ` DJ Delorie
2023-11-09 17:54 ` Andreas Schwab
2023-11-09 18:00 ` Alejandro Colomar
2023-11-09 19:42 ` Jonny Grant
2023-11-09 7:23 ` Oskari Pirhonen
2023-11-09 15:20 ` [PATCH v2 1/2] " Alejandro Colomar
2023-11-09 15:20 ` [PATCH v2 2/2] stpncpy.3, string.3, string_copying.7: Clarify that st[rp]ncpy() pad with null bytes Alejandro Colomar
2023-11-10 5:47 ` Oskari Pirhonen
2023-11-10 10:47 ` Alejandro Colomar
[not found] ` <20231108021240.176996-1-mattlloydhouse@gmail.com>
[not found] ` <ZUvilH5kuQfTuZjy@debian>
[not found] ` <20231109031345.245703-1-mattlloydhouse@gmail.com>
2023-11-09 10:31 ` strncpy clarify result may not be null terminated Jonny Grant
2023-11-09 11:38 ` Alejandro Colomar
2023-11-09 12:43 ` Alejandro Colomar
2023-11-09 12:51 ` Xi Ruoyao
2023-11-09 14:01 ` Alejandro Colomar
2023-11-09 18:11 ` Paul Eggert
2023-11-09 23:48 ` Alejandro Colomar
2023-11-10 5:36 ` Paul Eggert
2023-11-10 11:05 ` Alejandro Colomar
2023-11-10 11:47 ` Alejandro Colomar
2023-11-10 17:58 ` Paul Eggert
2023-11-10 18:36 ` Alejandro Colomar
2023-11-10 20:19 ` Alejandro Colomar
2023-11-10 23:44 ` Jonny Grant
2023-11-10 19:52 ` Alejandro Colomar
2023-11-10 22:14 ` Paul Eggert
2023-11-11 21:13 ` Alejandro Colomar
2023-11-11 22:20 ` Paul Eggert
2023-11-12 9:52 ` Jonny Grant
2023-11-12 10:59 ` Alejandro Colomar
2023-11-10 11:36 ` Jonny Grant
2023-11-10 13:15 ` Alejandro Colomar
2023-11-10 11:23 ` Jonny Grant
[not found] ` <CACKs7VDsTdSNwbC6+2LtQ67J_eJiD814xkw2_5XM1Q=iMjLXJA@mail.gmail.com>
2023-11-10 11:06 ` Jonny Grant
2023-11-12 9:17 ` [PATCH 0/2] Expand BUGS section of string_copying(7) Alejandro Colomar
2023-11-12 9:18 ` [PATCH 1/2] string_copying.7: BUGS: *cat(3) functions aren't always bad Alejandro Colomar
2023-11-12 9:18 ` [PATCH 2/2] string_copying.7: BUGS: Document strl{cpy,cat}(3)'s performance problems Alejandro Colomar
2023-11-12 11:26 ` [PATCH v2 0/3] Improve string_copying(7) Alejandro Colomar
2023-11-12 11:26 ` [PATCH v2 1/3] string_copying.7: BUGS: *cat(3) functions aren't always bad Alejandro Colomar
2023-11-12 11:26 ` [PATCH v2 2/3] string_copying.7: BUGS: Document strl{cpy,cat}(3)'s performance problems Alejandro Colomar
2023-11-12 11:27 ` [PATCH v2 3/3] strtcpy.3, string_copying.7: Add strtcpy(3) Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20231108221638.37101-2-alx@kernel.org \
--to=alx@kernel.org \
--cc=adhemerval.zanella@linaro.org \
--cc=carlos@redhat.com \
--cc=dj@redhat.com \
--cc=g.branden.robinson@gmail.com \
--cc=jg@jguk.org \
--cc=kukuk@suse.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
--cc=mattlloydhouse@gmail.com \
--cc=xxc3ncoredxx@gmail.com \
--cc=zack@owlfolio.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).