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