diff options
| author | Alejandro Colomar <alx@kernel.org> | 2022-12-04 23:14:48 +0100 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2022-12-04 23:15:01 +0100 |
| commit | d93ff1314bd864d95d83fc9c754e8c255afb291c (patch) | |
| tree | a35c0435cb440cc26fcb9dedd5dd1548cddcdc72 /man3/strcpy.3 | |
| parent | d7a0778dac4ec72c870ada2db783060f9154627f (diff) | |
| download | man-pages-d93ff1314bd864d95d83fc9c754e8c255afb291c.tar.gz | |
strcpy.3, strncpy.3: Split the page and document them separately
strncpy(3) is completely unrelated to strcpy(3). Rewrite its
documentation to be more explicit about this.
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man3/strcpy.3')
| -rw-r--r-- | man3/strcpy.3 | 124 |
1 files changed, 7 insertions, 117 deletions
diff --git a/man3/strcpy.3 b/man3/strcpy.3 index 1b41e08a2f..74c3180ae3 100644 --- a/man3/strcpy.3 +++ b/man3/strcpy.3 @@ -14,7 +14,7 @@ .\" .TH strcpy 3 (date) "Linux man-pages (unreleased)" .SH NAME -strcpy, strncpy \- copy a string +strcpy \- copy a string .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) @@ -23,9 +23,6 @@ Standard C library .B #include <string.h> .PP .BI "char *strcpy(char *restrict " dest ", const char *restrict " src ); -.BI "char *strncpy(char " dest "[restrict ." n "], \ -const char " src "[restrict ." n ], -.BI " size_t " n ); .fi .SH DESCRIPTION The @@ -40,61 +37,10 @@ The strings may not overlap, and the destination string must be large enough to receive the copy. .I Beware of buffer overruns! (See BUGS.) -.PP -The -.BR strncpy () -function is similar, except that at most -.I n -bytes of -.I src -are copied. -.BR Warning : -If there is no null byte -among the first -.I n -bytes of -.IR src , -the string placed in -.I dest -will not be null-terminated. -.PP -If the length of -.I src -is less than -.IR n , -.BR strncpy () -writes additional null bytes to -.I dest -to ensure that a total of -.I n -bytes are written. -.PP -A simple implementation of -.BR strncpy () -might be: -.PP -.in +4n -.EX -char * -strncpy(char *dest, const char *src, size_t n) -{ - size_t i; - - for (i = 0; i < n && src[i] != \(aq\e0\(aq; i++) - dest[i] = src[i]; - for ( ; i < n; i++) - dest[i] = \(aq\e0\(aq; - - return dest; -} -.EE -.in .SH RETURN VALUE The .BR strcpy () -and -.BR strncpy () -functions return a pointer to +function returns a pointer to the destination string .IR dest . .SH ATTRIBUTES @@ -108,8 +54,7 @@ lbx lb lb l l l. Interface Attribute Value T{ -.BR strcpy (), -.BR strncpy () +.BR strcpy () T} Thread safety MT-Safe .TE .hy @@ -118,57 +63,6 @@ T} Thread safety MT-Safe .SH STANDARDS POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. .SH NOTES -Some programmers consider -.BR strncpy () -to be inefficient and error prone. -If the programmer knows (i.e., includes code to test!) -that the size of -.I dest -is greater than -the length of -.IR src , -then -.BR strcpy () -can be used. -.PP -One valid (and intended) use of -.BR strncpy () -is to copy a C string to a fixed-length buffer -while ensuring both that the buffer is not overflowed -and that unused bytes in the destination buffer are zeroed out -(perhaps to prevent information leaks if the buffer is to be -written to media or transmitted to another process via an -interprocess communication technique). -.PP -If there is no terminating null byte in the first -.I n -bytes of -.IR src , -.BR strncpy () -produces an unterminated string in -.IR dest . -If -.I buf -has length -.IR buflen , -you can force termination using something like the following: -.PP -.in +4n -.EX -if (buflen > 0) { - strncpy(buf, str, buflen \- 1); - buf[buflen \- 1]= \(aq\e0\(aq; -} -.EE -.in -.PP -(Of course, the above technique ignores the fact that, if -.I src -contains more than -.I "buflen\ \-\ 1" -bytes, information is lost in the copying to -.IR dest .) -.\" .SS strlcpy() Some systems (the BSDs, Solaris, and others) provide the following function: .PP @@ -182,17 +76,15 @@ size_t strlcpy(char *dest, const char *src, size_t size); .\" "strlcpy and strlcat - consistent, safe, string copy and concatenation" .\" 1999 USENIX Annual Technical Conference This function is similar to -.BR strncpy (), +.BR strcpy (), but it copies at most .I size\-1 bytes to .IR dest , -always adds a terminating null byte, -and does not pad the destination with (further) null bytes. +truncating the string as necessary. +It always adds a terminating null byte. This function fixes some of the problems of .BR strcpy () -and -.BR strncpy (), but the caller must still handle the possibility of data loss if .I size is too small. @@ -229,8 +121,6 @@ in ways that may make the impossible possible. .BR memcpy (3), .BR memmove (3), .BR stpcpy (3), -.BR stpncpy (3), .BR strdup (3), .BR string (3), -.BR wcscpy (3), -.BR wcsncpy (3) +.BR wcscpy (3) |