On Wed, Nov 08, 2023 at 23:17:07 +0100, Alejandro Colomar wrote:
> These copy *from* a string. But the destination is a simple character
> sequence within an array; not a string.
>
> Suggested-by: DJ Delorie <dj@xxxxxxxxxx>
> Cc: Jonny Grant <jg@xxxxxxxx>
> Cc: Matthew House <mattlloydhouse@xxxxxxxxx>
> Cc: Oskari Pirhonen <xxc3ncoredxx@xxxxxxxxx>
> Cc: Thorsten Kukuk <kukuk@xxxxxxxx>
> Cc: Adhemerval Zanella Netto <adhemerval.zanella@xxxxxxxxxx>
> Cc: Zack Weinberg <zack@xxxxxxxxxxxx>
> Cc: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
> Cc: Carlos O'Donell <carlos@xxxxxxxxxx>
> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
> ---
I like the "with bytes from a string" wording. Good call.
- Oskari
>
> 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:
signature.asc
Description: PGP signature
