Rewrite to be consistent with the new string_copy.7 page.
Cc: Martin Sebor <msebor@xxxxxxxxxx>
Cc: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
Cc: Douglas McIlroy <douglas.mcilroy@xxxxxxxxxxxxx>
Cc: Jakub Wilk <jwilk@xxxxxxxxx>
Cc: Serge Hallyn <serge@xxxxxxxxxx>
Cc: Iker Pedrosa <ipedrosa@xxxxxxxxxx>
Cc: Andrew Pinski <pinskia@xxxxxxxxx>
Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
---
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@xxxxxxxxxxxxxxxxx)
-.\"
-.\" 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@xxxxxxxxxx)
-.\" 2007-06-15, Marc Boyer <marc.boyer@xxxxxxxxxxx> + 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@xxxxxxxxxxxxxxxxx)
+.\" Copyright 2022 Alejandro Colomar <alx@xxxxxxxxxx>
.\"
.\" 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@xxxxxxxxxx)
-.\" Modified Fri Aug 25 23:17:51 1995 by Andries Brouwer (aeb@xxxxxx)
-.\" Modified Wed Dec 18 00:47:18 1996 by Andries Brouwer (aeb@xxxxxx)
-.\" 2007-06-15, Marc Boyer <marc.boyer@xxxxxxxxxxx> + 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)
--
2.38.1
