diff options
Diffstat (limited to 'man7/string_copying.7')
| -rw-r--r-- | man7/string_copying.7 | 134 |
1 files changed, 67 insertions, 67 deletions
diff --git a/man7/string_copying.7 b/man7/string_copying.7 index 281fff8be..d55eea636 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -201,7 +201,7 @@ compiler warnings, static analyzers, and .B \%_FORTIFY_SOURCE (see -.BR ftm (7)). +.MR ftm 7 ). Keeping the code simple helps these overflow-detection features be more precise. .P @@ -219,14 +219,14 @@ Functions that truncate: .IP \[bu] .BR strtcpy () .IP \[bu] -.BR strlcpy (3bsd) +.MR strlcpy 3bsd and -.BR strlcat (3bsd) +.MR strlcat 3bsd are similar, but have important performance problems; see BUGS. .IP \[bu] -.BR stpncpy (3) +.MR stpncpy 3 and -.BR strncpy (3) +.MR strncpy 3 also truncate, but they don't write strings, but rather null-padded character sequences. .\" ----- DESCRIPTION :: Null-padded character sequences --------------/ @@ -234,35 +234,35 @@ but rather null-padded character sequences. For historic reasons, some standard APIs and file formats, such as -.BR utmpx (5) +.MR utmpx 5 and -.BR tar (1), +.MR tar 1 , use null-padded character sequences in fixed-size buffers. To interface with them, specialized functions need to be used. .P To copy bytes from strings into these buffers, use -.BR strncpy (3) +.MR strncpy 3 or -.BR stpncpy (3). +.MR stpncpy 3 . .P To read a null-padded character sequence, use .IR "strnlen(src,\ NITEMS(src))" , and then you can treat it as a known-length character sequence; or use -.BR strncat (3) +.MR strncat 3 directly. .\" ----- DESCRIPTION :: Known-length character sequences -----------------/ .SS Known-length character sequences The simplest character sequence copying function is -.BR mempcpy (3). +.MR mempcpy 3 . It requires always knowing the length of your character sequences, for which structures can be used. It makes the code much faster, since you always know the length of your character sequences, and can do the minimal copies and length measurements. -.BR mempcpy (3) +.MR mempcpy 3 copies character sequences, so you need to explicitly set the terminating null character if you need a string. @@ -281,14 +281,14 @@ so programs that use character sequences will have to take care of differentiating strings from character sequences. .P To copy a known-length character sequence, use -.BR mempcpy (3). +.MR mempcpy 3 . .P To copy a known-length character sequence into a string, use .IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" . .P A string is also accepted as input, because -.BR mempcpy (3) +.MR mempcpy 3 asks for the length, and a string is composed of a character sequence of the same length plus a terminating null character. @@ -307,17 +307,17 @@ holds a string before the call. List of functions: .IP \[bu] 3 .PD 0 -.BR stpcpy (3) +.MR stpcpy 3 .IP \[bu] -.BR strcpy (3), -.BR strcat (3) +.MR strcpy 3 , +.MR strcat 3 .IP \[bu] .BR stpecpy () .IP \[bu] .BR strtcpy () .IP \[bu] -.BR strlcpy (3bsd), -.BR strlcat (3bsd) +.MR strlcpy 3bsd , +.MR strlcat 3bsd .PD .P Other functions require an input string, @@ -327,9 +327,9 @@ and have a long history of misuse. List of functions: .IP \[bu] 3 .PD 0 -.BR stpncpy (3) +.MR stpncpy 3 .IP \[bu] -.BR strncpy (3) +.MR strncpy 3 .PD .P Other functions operate on an input character sequence, @@ -338,35 +338,35 @@ Functions that catenate also require that .I dst holds a string before the call. -.BR strncat (3) +.MR strncat 3 has an even more misleading name than the functions above. List of functions: .IP \[bu] 3 -.BR strncat (3) +.MR strncat 3 .P Other functions operate on an input character sequence to create an output character sequence. List of functions: .IP \[bu] 3 -.BR mempcpy (3) +.MR mempcpy 3 .\" ----- DESCRIPTION :: Functions :: ---------------------------------/ .SS Functions .\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ .TP -.BR stpcpy (3) +.MR stpcpy 3 Copy the input string into a destination string. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. .\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ .TP -.BR strcpy (3) +.MR strcpy 3 .TQ -.BR strcat (3) +.MR strcat 3 Copy and catenate the input string into a destination string. The programmer is responsible for allocating a buffer large enough. The return value is useless. .IP -.BR stpcpy (3) +.MR stpcpy 3 is a faster alternative to these functions. .\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/ .TP @@ -396,9 +396,9 @@ This function is not provided by any library; see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP -.BR strlcpy (3bsd) +.MR strlcpy 3bsd .TQ -.BR strlcat (3bsd) +.MR strlcat 3bsd Copy and catenate the input string into a destination string. If the destination buffer, limited by its size, @@ -415,7 +415,7 @@ and are better alternatives to these functions. .\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ .TP -.BR stpncpy (3) +.MR stpncpy 3 Copy the input string into a destination null-padded character sequence in a fixed-size buffer. If the destination buffer, @@ -431,16 +431,16 @@ comparing the length of the input string with the size of the destination buffer. .\" ----- DESCRIPTION :: Functions :: strncpy(3) ----------------------/ .TP -.BR strncpy (3) +.MR strncpy 3 This function is identical to -.BR stpncpy (3) +.MR stpncpy 3 except for the useless return value. .IP -.BR stpncpy (3) +.MR stpncpy 3 is a more useful alternative to this function. .\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ .TP -.BR strncat (3) +.MR strncat 3 Catenate the input character sequence, contained in a null-padded fixed-size buffer, into a destination string. @@ -448,14 +448,14 @@ The programmer is responsible for allocating a buffer large enough. The return value is useless. .IP Do not confuse this function with -.BR strncpy (3); +.MR strncpy 3 ; they are not related at all. .IP .I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ NITEMS(src))),\ \[dq]\[dq]) is a faster alternative to this function. .\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/ .TP -.BR mempcpy (3) +.MR mempcpy 3 Copy the input character sequence, limited by its length, into a destination character sequence. @@ -464,7 +464,7 @@ It returns a pointer suitable for chaining. .\" ----- RETURN VALUE :: ---------------------------------------------/ .SH RETURN VALUE .TP -.BR stpcpy (3) +.MR stpcpy 3 A pointer to the terminating null character in the destination string. .TP .BR stpecpy () @@ -476,9 +476,9 @@ and .I errno is set to indicate the error. .TP -.BR mempcpy (3) +.MR mempcpy 3 .TQ -.BR stpncpy (3) +.MR stpncpy 3 A pointer to one after the last character in the destination character sequence. .TP @@ -491,19 +491,19 @@ and .I errno is set to indicate the error. .TP -.BR strlcpy (3bsd) +.MR strlcpy 3bsd .TQ -.BR strlcat (3bsd) +.MR strlcat 3bsd The length of the total string that they tried to create (as if truncation didn't occur). .TP -.BR strcpy (3) +.MR strcpy 3 .TQ -.BR strcat (3) +.MR strcat 3 .TQ -.BR strncpy (3) +.MR strncpy 3 .TQ -.BR strncat (3) +.MR strncat 3 The .I dst pointer, @@ -529,7 +529,7 @@ The string has been truncated. .\" ----- NOTES :: strscpy(9) -----------------------------------------/ .SH NOTES The Linux kernel has an internal function for copying strings, -.BR strscpy (9), +.MR strscpy 9 , which is identical to .BR strtcpy (), except that it returns @@ -559,9 +559,9 @@ since .I strlen(dst) is usually a byproduct of the previous copy. .P -.BR strlcpy (3) +.MR strlcpy 3 and -.BR strlcat (3) +.MR strlcat 3 need to read the entire .I src string, @@ -577,7 +577,7 @@ they're still unnecessarily slow. The following are examples of correct use of each of these functions. .\" ----- EXAMPLES :: stpcpy(3) ---------------------------------------/ .TP -.BR stpcpy (3) +.MR stpcpy 3 .EX p = buf; p = stpcpy(p, "Hello "); @@ -588,9 +588,9 @@ puts(buf); .EE .\" ----- EXAMPLES :: strcpy(3), strcat(3) ----------------------------/ .TP -.BR strcpy (3) +.MR strcpy 3 .TQ -.BR strcat (3) +.MR strcat 3 .EX strcpy(buf, "Hello "); strcat(buf, "world"); @@ -625,9 +625,9 @@ puts(buf); .EE .\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ .TP -.BR strlcpy (3bsd) +.MR strlcpy 3bsd .TQ -.BR strlcat (3bsd) +.MR strlcat 3bsd .EX if (strlcpy(buf, "Hello ", NITEMS(buf)) >= NITEMS(buf)) goto toolong; @@ -640,7 +640,7 @@ puts(buf); .EE .\" ----- EXAMPLES :: stpncpy(3) --------------------------------------/ .TP -.BR stpncpy (3) +.MR stpncpy 3 .EX p = stpncpy(u->ut_user, "alx", NITEMS(u->ut_user)); if (NITEMS(u->ut_user) < strlen("alx")) @@ -650,7 +650,7 @@ fwrite(u->ut_user, 1, len, stdout); .EE .\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ .TP -.BR strncpy (3) +.MR strncpy 3 .EX strncpy(u->ut_user, "alx", NITEMS(u->ut_user)); if (NITEMS(u->ut_user) < strlen("alx")) @@ -681,7 +681,7 @@ puts(buf); .EE .\" ----- EXAMPLES :: strncat(3) --------------------------------------/ .TP -.BR strncat (3) +.MR strncat 3 .EX char buf[NITEMS(u->ut_user) + 1]; strcpy(buf, ""); @@ -691,7 +691,7 @@ puts(buf); .EE .\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/ .TP -.BR mempcpy (3) +.MR mempcpy 3 .EX p = buf; p = mempcpy(p, "Hello ", 6); @@ -756,12 +756,12 @@ ssize_t } .\" ----- SEE ALSO :: -------------------------------------------------/ .SH SEE ALSO -.BR bzero (3), -.BR memcpy (3), -.BR memccpy (3), -.BR mempcpy (3), -.BR stpcpy (3), -.BR strlcpy (3bsd), -.BR strncat (3), -.BR stpncpy (3), -.BR string (3) +.MR bzero 3 , +.MR memcpy 3 , +.MR memccpy 3 , +.MR mempcpy 3 , +.MR stpcpy 3 , +.MR strlcpy 3bsd , +.MR strncat 3 , +.MR stpncpy 3 , +.MR string 3 |