diff options
Diffstat (limited to 'man7/string_copying.7')
| -rw-r--r-- | man7/string_copying.7 | 66 |
1 files changed, 30 insertions, 36 deletions
diff --git a/man7/string_copying.7 b/man7/string_copying.7 index 62365897e..814eabddd 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: BSD-3-Clause .\" -.TH string_copying 7 2023-02-05 "Linux man-pages 6.03" +.TH string_copying 7 2023-07-29 "Linux man-pages 6.05.01" .\" ----- NAME :: -----------------------------------------------------/ .SH NAME stpcpy, @@ -49,7 +49,7 @@ const char *restrict " src , .PP // Zero a fixed-width buffer, and // copy a string into a character sequence with truncation. -.BI "char *strncpy(char " dest "[restrict ." sz "], \ +.BI "char *strncpy(char " dst "[restrict ." sz "], \ const char *restrict " src , .BI " size_t " sz ); .PP @@ -203,7 +203,7 @@ Nowadays, compilers can detect most programmer errors with features like compiler warnings, static analyzers, and -.BR \%_FORTIFY_SOURCE +.B \%_FORTIFY_SOURCE (see .BR ftm (7)). Keeping the code simple @@ -223,8 +223,7 @@ It only requires to check for truncation once after all chained calls. .BR strlcpy (3bsd) and .BR strlcat (3bsd) -are designed to crash if the input string is invalid -(doesn't contain a terminating null byte). +are similar, but less efficient when chained. .IP \[bu] .BR stpncpy (3) and @@ -280,7 +279,7 @@ instead of In programs that make considerable use of strings or character sequences, and need the best performance, using overlapping character sequences can make a big difference. -It allows holding subsequences of a larger character sequence. +It allows holding subsequences of a larger character sequence, while not duplicating memory nor using time to do a copy. .PP @@ -317,12 +316,12 @@ List of functions: .PD 0 .BR stpcpy (3) .IP \[bu] -.BR strcpy "(3), \c" +.BR strcpy (3), .BR strcat (3) .IP \[bu] .BR stpecpy (3) .IP \[bu] -.BR strlcpy "(3bsd), \c" +.BR strlcpy (3bsd), .BR strlcat (3bsd) .PD .PP @@ -397,7 +396,7 @@ It returns a pointer suitable for chaining. Truncation needs to be detected only once after the last chained call. .IP This function is not provided by any library; -See EXAMPLES for a reference implementation. +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP .BR strlcpy (3bsd) @@ -410,9 +409,6 @@ isn't large enough to hold the copy, the resulting string is truncated (but it is guaranteed to be null-terminated). They return the length of the total string they tried to create. -These functions force a SIGSEGV if the -.I src -pointer is not a string. .IP .BR stpecpy (3) is a simpler alternative to these functions. @@ -444,8 +440,8 @@ is a more useful alternative to this function. .\" ----- DESCRIPTION :: Functions :: zustr2ustp(3) --------------------/ .TP .BR zustr2ustp (3) -This function copies the input character sequence -contained in a null-padded wixed-width buffer, +This function copies the input character sequence, +contained in a null-padded fixed-width buffer, into a destination character sequence. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. @@ -455,12 +451,12 @@ since the size of the original character sequence is always known, so it wouldn't be very useful. .IP This function is not provided by any library; -See EXAMPLES for a reference implementation. +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: zustr2stp(3) --------------------/ .TP .BR zustr2stp (3) -This function copies the input character sequence -contained in a null-padded wixed-width buffer, +This function copies the input character sequence, +contained in a null-padded fixed-width buffer, into a destination string. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. @@ -470,7 +466,7 @@ since the size of the original character sequence is always known, so it wouldn't be very useful. .IP This function is not provided by any library; -See EXAMPLES for a reference implementation. +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ .TP .BR strncat (3) @@ -478,8 +474,8 @@ Do not confuse this function with .BR strncpy (3); they are not related at all. .IP -This function catenates the input character sequence -contained in a null-padded wixed-width buffer, +This function catenates the input character sequence, +contained in a null-padded fixed-width buffer, into a destination string. The programmer is responsible for allocating a buffer large enough. The return value is useless. @@ -582,7 +578,6 @@ on truncation. .IP .BR stpecpy (3) is a simpler and faster alternative to this function. -.RE .\" ----- CAVEATS :: --------------------------------------------------/ .SH CAVEATS Don't mix chain calls to truncating and non-truncating functions. @@ -748,63 +743,62 @@ Here are reference implementations for functions not provided by libc. .in +4n .EX /* This code is in the public domain. */ - +\& .\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ char * .IR stpecpy "(char *dst, char end[0], const char *restrict src)" { char *p; - - if (src[strlen(src)] != \[aq]\e0\[aq]) - raise(SIGSEGV); - +\& + if (dst == NULL) + return NULL; if (dst == end) return end; - +\& p = memccpy(dst, src, \[aq]\e0\[aq], end \- dst); if (p != NULL) return p \- 1; - +\& /* truncation detected */ end[\-1] = \[aq]\e0\[aq]; return end; } - +\& .\" ----- EXAMPLES :: Implementations :: zustr2ustp(3) ----------------/ char * .IR zustr2ustp "(char *restrict dst, const char *restrict src, size_t sz)" { return ustpcpy(dst, src, strnlen(src, sz)); } - +\& .\" ----- EXAMPLES :: Implementations :: zustr2stp(3) -----------------/ char * .IR zustr2stp "(char *restrict dst, const char *restrict src, size_t sz)" { char *p; - +\& p = zustr2ustp(dst, src, sz); *p = \[aq]\e0\[aq]; - +\& return p; } - +\& .\" ----- EXAMPLES :: Implementations :: ustpcpy(3) -------------------/ char * .IR ustpcpy "(char *restrict dst, const char *restrict src, size_t len)" { return mempcpy(dst, src, len); } - +\& .\" ----- EXAMPLES :: Implementations :: ustr2stp(3) ------------------/ char * .IR ustr2stp "(char *restrict dst, const char *restrict src, size_t len)" { char *p; - +\& p = ustpcpy(dst, src, len); *p = \[aq]\e0\[aq]; - +\& return p; } .EE |