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>
Acked-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Jonny Grant <jg@jguk.org>
Cc: Matthew House <mattlloydhouse@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>
Cc: Paul Eggert <eggert@cs.ucla.edu>
Cc: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
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(-)
@@ -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;
@@ -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,