diff options
Diffstat (limited to 'man3/strcpy.3')
| -rw-r--r-- | man3/strcpy.3 | 234 |
1 files changed, 150 insertions, 84 deletions
diff --git a/man3/strcpy.3 b/man3/strcpy.3 index 685a8e77a3..79c0d1c7bf 100644 --- a/man3/strcpy.3 +++ b/man3/strcpy.3 @@ -1,21 +1,11 @@ '\" t -.\" 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 +stpcpy, strcpy, strcat \- copy or catenate a string .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) @@ -23,27 +13,89 @@ Standard C library .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 , +into a string +at the buffer pointed to by +.IR dst . +The programmer is responsible for allocating a destination buffer large enough, +that is, +.IR "strlen(src) + 1" . +For the difference between the two functions, see RETURN VALUE. +.TP +.BR strcat () +This function catenates 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.) +after the string pointed to by +.I dst +(overwriting its terminating null byte). +The programmer is responsible for allocating a destination 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 *p; + + p = mempcpy(dst, src, strlen(src)); + *p = \(aq\e0\(aq; + + return p; +} + +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 of the copied string. +.TP .BR strcpy () -function returns a pointer to -the destination string -.IR dest . +.TQ +.BR strcat () +These functions return +.IR dst . .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7). @@ -55,73 +107,87 @@ lbx lb lb 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 +If the destination buffer is not large enough, +the behavior is undefined. +See +.B _FORTIFY_SOURCE +in +.BR feature_test_macros (7). +.PP +.BR strcat () +can be very inefficient. +Read about +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.SH EXAMPLES +.\" SRC BEGIN (strcpy.c) .EX -size_t strlcpy(char *dest, const char *src, size_t size); +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +int +main(void) +{ + char *p; + char *buf1; + char *buf2; + size_t len, maxsize; + + maxsize = strlen("Hello ") + strlen("world") + strlen("!") + 1; + buf1 = malloc(sizeof(*buf1) * maxsize); + buf2 = malloc(sizeof(*buf2) * maxsize); + + p = buf1; + p = stpcpy(p, "Hello "); + p = stpcpy(p, "world"); + p = stpcpy(p, "!"); + len = p \- buf1; + + printf("[len = %zu]: ", len); + puts(buf1); // "Hello world!" + free(buf1); + + strcpy(buf2, "Hello "); + strcat(buf2, "world"); + strcat(buf2, "!"); + len = strlen(buf2); + + printf("[len = %zu]: ", len); + puts(buf2); // "Hello world!" + free(buf2); + + exit(EXIT_SUCCESS); +} .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. -.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. +.\" SRC END .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_copying (7) |