Re: [PATCH v5 3/5] stpcpy.3, strcpy.3, strcat.3: Document in a single page

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 13361 bytes --]

Hi!

The formatted version of this page was sent accidentally as reply to 2/3.
Since 2/5 are only link pages, there's no formatted page for them.

Cheers,

Alex

On 12/15/22 01:26, Alejandro Colomar wrote:
> Rewrite to be consistent with the new string_copy.7 page.
> 
> Cc: Martin Sebor <msebor@redhat.com>
> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Cc: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
> Cc: Jakub Wilk <jwilk@jwilk.net>
> Cc: Serge Hallyn <serge@hallyn.com>
> Cc: Iker Pedrosa <ipedrosa@redhat.com>
> Cc: Andrew Pinski <pinskia@gmail.com>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>   man3/stpcpy.3 |  13 ---
>   man3/strcat.3 | 161 +----------------------------------
>   man3/strcpy.3 | 226 +++++++++++++++++++++++++++++++-------------------
>   3 files changed, 143 insertions(+), 257 deletions(-)
> 
> diff --git a/man3/stpcpy.3 b/man3/stpcpy.3
> index 5770790fc..d01c0239b 100644
> --- a/man3/stpcpy.3
> +++ b/man3/stpcpy.3
> @@ -14,19 +14,6 @@ .SH SYNOPSIS
>   .PP
>   .BI "char *stpcpy(char *restrict " dest ", const char *restrict " src );
>   .fi
> -.PP
> -.RS -4
> -Feature Test Macro Requirements for glibc (see
> -.BR feature_test_macros (7)):
> -.RE
> -.PP
> -.BR stpcpy ():
> -.nf
> -    Since glibc 2.10:
> -        _POSIX_C_SOURCE >= 200809L
> -    Before glibc 2.10:
> -        _GNU_SOURCE
> -.fi
>   .SH DESCRIPTION
>   The
>   .BR stpcpy ()
> diff --git a/man3/strcat.3 b/man3/strcat.3
> index 277e5b1e4..ff7476a84 100644
> --- a/man3/strcat.3
> +++ b/man3/strcat.3
> @@ -1,160 +1 @@
> -.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
> -.\"
> -.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> -.\"
> -.\" References consulted:
> -.\"     Linux libc source code
> -.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
> -.\"     386BSD man pages
> -.\" Modified Sat Jul 24 18:11:47 1993 by Rik Faith (faith@cs.unc.edu)
> -.\" 2007-06-15, Marc Boyer <marc.boyer@enseeiht.fr> + mtk
> -.\"     Improve discussion of strncat().
> -.TH strcat 3 (date) "Linux man-pages (unreleased)"
> -.SH NAME
> -strcat \- concatenate two strings
> -.SH LIBRARY
> -Standard C library
> -.RI ( libc ", " \-lc )
> -.SH SYNOPSIS
> -.nf
> -.B #include <string.h>
> -.PP
> -.BI "char *strcat(char *restrict " dest ", const char *restrict " src );
> -.fi
> -.SH DESCRIPTION
> -The
> -.BR strcat ()
> -function appends the
> -.I src
> -string to the
> -.I dest
> -string,
> -overwriting the terminating null byte (\(aq\e0\(aq) at the end of
> -.IR dest ,
> -and then adds a terminating null byte.
> -The strings may not overlap, and the
> -.I dest
> -string must have
> -enough space for the result.
> -If
> -.I dest
> -is not large enough, program behavior is unpredictable;
> -.IR "buffer overruns are a favorite avenue for attacking secure programs" .
> -.SH RETURN VALUE
> -The
> -.BR strcat ()
> -function returns a pointer to the resulting string
> -.IR dest .
> -.SH ATTRIBUTES
> -For an explanation of the terms used in this section, see
> -.BR attributes (7).
> -.ad l
> -.nh
> -.TS
> -allbox;
> -lbx lb lb
> -l l l.
> -Interface	Attribute	Value
> -T{
> -.BR strcat (),
> -.BR strncat ()
> -T}	Thread safety	MT-Safe
> -.TE
> -.hy
> -.ad
> -.sp 1
> -.SH STANDARDS
> -POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
> -.SH NOTES
> -Some systems (the BSDs, Solaris, and others) provide the following function:
> -.PP
> -.in +4n
> -.EX
> -size_t strlcat(char *dest, const char *src, size_t size);
> -.EE
> -.in
> -.PP
> -This function appends the null-terminated string
> -.I src
> -to the string
> -.IR dest ,
> -copying at most
> -.I size\-strlen(dest)\-1
> -from
> -.IR src ,
> -and adds a terminating null byte to the result,
> -.I unless
> -.I size
> -is less than
> -.IR strlen(dest) .
> -This function fixes the buffer overrun problem of
> -.BR strcat (),
> -but the caller must still handle the possibility of data loss if
> -.I size
> -is too small.
> -The function returns the length of the string
> -.BR strlcat ()
> -tried to create; if the return value is greater than or equal to
> -.IR size ,
> -data loss occurred.
> -If data loss matters, the caller
> -.I must
> -either check the arguments before the call, or test the function return value.
> -.BR strlcat ()
> -is not present in glibc and is not standardized by POSIX,
> -.\" https://lwn.net/Articles/506530/
> -but is available on Linux via the
> -.I libbsd
> -library.
> -.\"
> -.SH EXAMPLES
> -Because
> -.BR strcat ()
> -must find the null byte that terminates the string
> -.I dest
> -using a search that starts at the beginning of the string,
> -the execution time of this function
> -scales according to the length of the string
> -.IR dest .
> -This can be demonstrated by running the program below.
> -(If the goal is to concatenate many strings to one target,
> -then manually copying the bytes from each source string
> -while maintaining a pointer to the end of the target string
> -will provide better performance.)
> -.\"
> -.SS Program source
> -\&
> -.\" SRC BEGIN (strcat.c)
> -.EX
> -#include <stdint.h>
> -#include <stdio.h>
> -#include <string.h>
> -#include <time.h>
> -
> -int
> -main(void)
> -{
> -#define LIM 4000000
> -    char p[LIM + 1];    /* +1 for terminating null byte */
> -    time_t base;
> -
> -    base = time(NULL);
> -    p[0] = \(aq\e0\(aq;
> -
> -    for (unsigned int j = 0; j < LIM; j++) {
> -        if ((j % 10000) == 0)
> -            printf("%u %jd\en", j, (intmax_t) (time(NULL) \- base));
> -        strcat(p, "a");
> -    }
> -}
> -.EE
> -.\" SRC END
> -.SH SEE ALSO
> -.BR bcopy (3),
> -.BR memccpy (3),
> -.BR memcpy (3),
> -.BR strcpy (3),
> -.BR string (3),
> -.BR strlcat (3bsd),
> -.BR wcscat (3),
> -.BR wcsncat (3)
> +.so man3/strcpy.3
> diff --git a/man3/strcpy.3 b/man3/strcpy.3
> index 74c3180ae..424648c46 100644
> --- a/man3/strcpy.3
> +++ b/man3/strcpy.3
> @@ -1,20 +1,10 @@
> -.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
> +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
>   .\"
>   .\" SPDX-License-Identifier: Linux-man-pages-copyleft
>   .\"
> -.\" References consulted:
> -.\"     Linux libc source code
> -.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
> -.\"     386BSD man pages
> -.\" Modified Sat Jul 24 18:06:49 1993 by Rik Faith (faith@cs.unc.edu)
> -.\" Modified Fri Aug 25 23:17:51 1995 by Andries Brouwer (aeb@cwi.nl)
> -.\" Modified Wed Dec 18 00:47:18 1996 by Andries Brouwer (aeb@cwi.nl)
> -.\" 2007-06-15, Marc Boyer <marc.boyer@enseeiht.fr> + mtk
> -.\"     Improve discussion of strncpy().
> -.\"
>   .TH strcpy 3 (date) "Linux man-pages (unreleased)"
>   .SH NAME
> -strcpy \- copy a string
> +strcpy \- copy or catenate a string
>   .SH LIBRARY
>   Standard C library
>   .RI ( libc ", " \-lc )
> @@ -22,26 +12,87 @@ .SH SYNOPSIS
>   .nf
>   .B #include <string.h>
>   .PP
> -.BI "char *strcpy(char *restrict " dest ", const char *restrict " src );
> +.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src );
> +.BI "char *strcpy(char *restrict " dst ", const char *restrict " src );
> +.BI "char *strcat(char *restrict " dst ", const char *restrict " src );
> +.fi
> +.PP
> +.RS -4
> +Feature Test Macro Requirements for glibc (see
> +.BR feature_test_macros (7)):
> +.RE
> +.PP
> +.BR stpcpy ():
> +.nf
> +    Since glibc 2.10:
> +        _POSIX_C_SOURCE >= 200809L
> +    Before glibc 2.10:
> +        _GNU_SOURCE
>   .fi
>   .SH DESCRIPTION
> -The
> +.TP
> +.BR stpcpy ()
> +.TQ
>   .BR strcpy ()
> -function copies the string pointed to by
> +These functions copy the string pointed to by
>   .IR src ,
> -including the terminating null byte (\(aq\e0\(aq),
> -to the buffer pointed to by
> -.IR dest .
> -The strings may not overlap, and the destination string
> -.I dest
> -must be large enough to receive the copy.
> -.I Beware of buffer overruns!
> -(See BUGS.)
> +into a string
> +at the buffer pointed to by
> +.IR dst .
> +The programmer is responsible for allocating a buffer large enough,
> +that is,
> +.IR "strlen(src) + 1" .
> +They only differ in the return value.
> +.TP
> +.BR strcat ()
> +This function catenates the string pointed to by
> +.IR src ,
> +at the end of the string pointed to by
> +.IR dst .
> +The programmer is responsible for allocating a buffer large enough,
> +that is,
> +.IR "strlen(dst) + strlen(src) + 1" .
> +.PP
> +An implementation of these functions might be:
> +.PP
> +.in +4n
> +.EX
> +char *
> +stpcpy(char *restrict dst, const char *restrict src)
> +{
> +    char  *end;
> +
> +    end = mempcpy(dst, src, strlen(src));
> +    *end = \(aq\e0\(aq;
> +
> +    return end;
> +}
> +
> +char *
> +strcpy(char *restrict dst, const char *restrict src)
> +{
> +    stpcpy(dst, src);
> +    return dst;
> +}
> +
> +char *
> +strcat(char *restrict dst, const char *restrict src)
> +{
> +    stpcpy(dst + strlen(dst), src);
> +    return dst;
> +}
> +.EE
> +.in
>   .SH RETURN VALUE
> -The
> +.TP
> +.BR stpcpy ()
> +This function returns
> +a pointer to the terminating null byte at the end of the copied string.
> +.TP
>   .BR strcpy ()
> -function returns a pointer to
> -the destination string
> +.TQ
> +.BR strcat ()
> +These functions return
>   .IR dest .
>   .SH ATTRIBUTES
>   For an explanation of the terms used in this section, see
> @@ -54,73 +105,80 @@ .SH ATTRIBUTES
>   l l l.
>   Interface	Attribute	Value
>   T{
> -.BR strcpy ()
> +.BR stpcpy (),
> +.BR strcpy (),
> +.BR strcat ()
>   T}	Thread safety	MT-Safe
>   .TE
>   .hy
>   .ad
>   .sp 1
>   .SH STANDARDS
> +.TP
> +.BR stpcpy ()
> +POSIX.1-2008.
> +.TP
> +.BR strcpy ()
> +.TQ
> +.BR strcat ()
>   POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
> -.SH NOTES
> -.SS strlcpy()
> -Some systems (the BSDs, Solaris, and others) provide the following function:
> +.SH CAVEATS
> +The strings
> +.I src
> +and
> +.I dst
> +may not overlap.
>   .PP
> -.in +4n
> -.EX
> -size_t strlcpy(char *dest, const char *src, size_t size);
> -.EE
> -.in
> -.PP
> -.\" http://static.usenix.org/event/usenix99/full_papers/millert/millert_html/index.html
> -.\"     "strlcpy and strlcat - consistent, safe, string copy and concatenation"
> -.\"     1999 USENIX Annual Technical Conference
> -This function is similar to
> -.BR strcpy (),
> -but it copies at most
> -.I size\-1
> -bytes to
> -.IR dest ,
> -truncating the string as necessary.
> -It always adds a terminating null byte.
> -This function fixes some of the problems of
> -.BR strcpy ()
> -but the caller must still handle the possibility of data loss if
> -.I size
> -is too small.
> -The return value of the function is the length of
> -.IR src ,
> -which allows truncation to be easily detected:
> -if the return value is greater than or equal to
> -.IR size ,
> -truncation occurred.
> -If loss of data matters, the caller
> -.I must
> -either check the arguments before the call,
> -or test the function return value.
> -.BR strlcpy ()
> -is not present in glibc and is not standardized by POSIX,
> -.\" https://lwn.net/Articles/506530/
> -but is available on Linux via the
> -.I libbsd
> -library.
> +If the destination buffer is not large enough,
> +the behavior is undefined.
> +See
> +.B _FORTIFY_SOURCE
> +in
> +.BR feature_test_macros (7).
>   .SH BUGS
> -If the destination string of a
> -.BR strcpy ()
> -is not large enough, then anything might happen.
> -Overflowing fixed-length string buffers is a favorite cracker technique
> -for taking complete control of the machine.
> -Any time a program reads or copies data into a buffer,
> -the program first needs to check that there's enough space.
> -This may be unnecessary if you can show that overflow is impossible,
> -but be careful: programs can get changed over time,
> -in ways that may make the impossible possible.
> +.TP
> +.BR strcat ()
> +This function can be very inefficient.
> +Read about
> +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
> +Shlemiel the painter
> +.UE .
> +.SH EXAMPLES
> +.EX
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +
> +int
> +main(void)
> +{
> +    char    *p;
> +    char    buf1[BUFSIZ];
> +    char    buf2[BUFSIZ];
> +    size_t  len;
> +
> +    p = buf1;
> +    p = stpcpy(p, "Hello ");
> +    p = stpcpy(p, "world");
> +    p = stpcpy(p, "!");
> +    len = p \- buf1;
> +
> +    printf("[len = %zu]: ", len);
> +    puts(buf1);  // "Hello world!"
> +
> +    strcpy(buf2, "Hello ");
> +    strcat(buf2, "world");
> +    strcat(buf2, "!");
> +    len = strlen(buf2);
> +
> +    printf("[len = %zu]: ", len);
> +    puts(buf2);  // "Hello world!"
> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
>   .SH SEE ALSO
> -.BR bcopy (3),
> -.BR memccpy (3),
> -.BR memcpy (3),
> -.BR memmove (3),
> -.BR stpcpy (3),
>   .BR strdup (3),
>   .BR string (3),
> -.BR wcscpy (3)
> +.BR wcscpy (3),
> +.BR string_copy (7)

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]