Debian Codegraph @

upstream/debian-trixie/man7/string_copying.7

raw
1 .\" Copyright 2022 Alejandro Colomar <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: BSD-3-Clause
4 .\"
5 .TH string_copying 7 2024-05-14 "Linux man-pages 6.9.1"
6 .\" ----- NAME :: -----------------------------------------------------/
7 .SH NAME
8 stpcpy,
9 strcpy, strcat,
10 stpecpy,
11 strtcpy,
12 strlcpy, strlcat,
13 stpncpy,
14 strncpy,
15 strncat
16 \- copying strings and character sequences
17 .\" ----- SYNOPSIS :: -------------------------------------------------/
18 .SH SYNOPSIS
19 .\" ----- SYNOPSIS :: (Null-terminated) strings -----------------------/
20 .SS Strings
21 .nf
22 // Chain-copy a string.
23 .BI "char *stpcpy(char *restrict " dst ", const char *restrict " src );
24 .P
25 // Copy/catenate a string.
26 .BI "char *strcpy(char *restrict " dst ", const char *restrict " src );
27 .BI "char *strcat(char *restrict " dst ", const char *restrict " src );
28 .P
29 // Chain-copy a string with truncation.
30 .BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src );
31 .P
32 // Copy/catenate a string with truncation.
33 .BI "ssize_t strtcpy(char " dst "[restrict ." dsize "], \
34 const char *restrict " src ,
35 .BI " size_t " dsize );
36 .BI "size_t strlcpy(char " dst "[restrict ." dsize "], \
37 const char *restrict " src ,
38 .BI " size_t " dsize );
39 .BI "size_t strlcat(char " dst "[restrict ." dsize "], \
40 const char *restrict " src ,
41 .BI " size_t " dsize );
42 .fi
43 .\" ----- SYNOPSIS :: Null-padded character sequences --------/
44 .SS Null-padded character sequences
45 .nf
46 // Fill a fixed-size buffer with characters from a string
47 // and pad with null bytes.
48 .BI "char *strncpy(char " dst "[restrict ." dsize "], \
49 const char *restrict " src ,
50 .BI " size_t " dsize );
51 .BI "char *stpncpy(char " dst "[restrict ." dsize "], \
52 const char *restrict " src ,
53 .BI " size_t " dsize );
54 .P
55 // Chain-copy a null-padded character sequence into a character sequence.
56 .I mempcpy(dst, src, strnlen(src, NITEMS(src)));
57 .P
58 // Chain-copy a null-padded character sequence into a string.
59 .I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]);
60 .P
61 // Catenate a null-padded character sequence into a string.
62 .BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ],
63 .BI " size_t " ssize );
64 .P
65 // Duplicate a null-padded character sequence into a string.
66 .BI "char *strndup(const char " src [. ssize "], size_t " ssize );
67 .fi
68 .\" ----- SYNOPSIS :: Known-length character sequences --------------------/
69 .SS Known-length character sequences
70 .nf
71 // Chain-copy a known-length character sequence.
72 .BI "void *mempcpy(void " dst "[restrict ." len "], \
73 const void " src "[restrict ." len ],
74 .BI " size_t " len );
75 .P
76 // Chain-copy a known-length character sequence into a string.
77 .I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]);
78 .fi
79 .SH DESCRIPTION
80 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/
81 .SS Terms (and abbreviations)
82 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/
83 .TP
84 .IR "string " ( str )
85 is a sequence of zero or more non-null characters followed by a null character.
86 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq
87 .TP
88 .I character sequence
89 is a sequence of zero or more non-null characters.
90 A program should never use a character sequence where a string is required.
91 However, with appropriate care,
92 a string can be used in the place of a character sequence.
93 .RS
94 .TP
95 .I null-padded character sequence
96 Character sequences can be contained in fixed-size buffers,
97 which contain padding null bytes after the character sequence,
98 to fill the rest of the buffer
99 without affecting the character sequence;
100 however, those padding null bytes are not part of the character sequence.
101 Don't confuse null-padded with null-terminated:
102 null-padded means 0 or more padding null bytes,
103 while null-terminated means exactly 1 terminating null character.
104 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: known-length character sequence
105 .TP
106 .I known-length character sequence
107 Character sequence delimited by its length.
108 It may be a slice of a larger character sequence,
109 or even of a string.
110 .RE
111 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: length (len) ----/
112 .TP
113 .IR "length " ( len )
114 is the number of non-null characters in a string or character sequence.
115 It is the return value of
116 .I strlen(str)
117 and of
118 .IR "strnlen(buf, size)" .
119 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: size ------------/
120 .TP
121 .I size
122 refers to the entire buffer
123 where the string or character sequence is contained.
124 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/
125 .TP
126 .I end
127 is the name of a pointer to one past the last element of a buffer.
128 It is equivalent to
129 .IR &str[size] .
130 It is used as a sentinel value,
131 to be able to truncate strings or character sequences
132 instead of overrunning the containing buffer.
133 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: copy ------------/
134 .TP
135 .I copy
136 This term is used when
137 the writing starts at the first element pointed to by
138 .IR dst .
139 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: catenate --------/
140 .TP
141 .I catenate
142 This term is used when
143 a function first finds the terminating null character in
144 .IR dst ,
145 and then starts writing at that position.
146 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/
147 .TP
148 .I chain
149 This term is used when
150 it's the programmer who provides
151 a pointer to the terminating null character in the string
152 .I dst
153 (or one after the last character in a character sequence),
154 and the function starts writing at that location.
155 The function returns
156 a pointer to the new location of the terminating null character
157 (or one after the last character in a character sequence)
158 after the call,
159 so that the programmer can use it to chain such calls.
160 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: duplicate -------/
161 .TP
162 .I duplicate
163 Allocate a new buffer
164 where a copy is placed.
165 .\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/
166 .SS Copy, catenate, and chain-copy
167 Originally,
168 there was a distinction between functions that copy and those that catenate.
169 However, newer functions that copy while allowing chaining
170 cover both use cases with a single API.
171 They are also algorithmically faster,
172 since they don't need to search for
173 the terminating null character of the existing string.
174 However, functions that catenate have a much simpler use,
175 so if performance is not important,
176 it can make sense to use them for improving readability.
177 .P
178 The pointer returned by functions that allow chaining
179 is a byproduct of the copy operation,
180 so it has no performance costs.
181 Functions that return such a pointer,
182 and thus can be chained,
183 have names of the form
184 .RB * stp *(),
185 since it's common to name the pointer just
186 .IR p .
187 .P
188 Chain-copying functions that truncate
189 should accept a pointer to the end of the destination buffer,
190 and have names of the form
191 .RB * stpe *().
192 This allows not having to recalculate the remaining size after each call.
193 .\" ----- DESCRIPTION :: Truncate or not? -----------------------------/
194 .SS Truncate or not?
195 The first thing to note is that programmers should be careful with buffers,
196 so they always have the correct size,
197 and truncation is not necessary.
198 .P
199 In most cases,
200 truncation is not desired,
201 and it is simpler to just do the copy.
202 Simpler code is safer code.
203 Programming against programming mistakes by adding more code
204 just adds more points where mistakes can be made.
205 .P
206 Nowadays,
207 compilers can detect most programmer errors with features like
208 compiler warnings,
209 static analyzers, and
210 .B \%_FORTIFY_SOURCE
211 (see
212 .BR ftm (7)).
213 Keeping the code simple
214 helps these overflow-detection features be more precise.
215 .P
216 When validating user input,
217 code should normally not truncate,
218 but instead fail and prevent the copy at all.
219 .P
220 In some cases,
221 however,
222 it makes sense to truncate.
223 .P
224 Functions that truncate:
225 .IP \[bu] 3
226 .BR stpecpy ()
227 .IP \[bu]
228 .BR strtcpy ()
229 .IP \[bu]
230 .BR strlcpy (3bsd)
231 and
232 .BR strlcat (3bsd)
233 are similar, but have important performance problems; see BUGS.
234 .IP \[bu]
235 .BR stpncpy (3)
236 and
237 .BR strncpy (3)
238 also truncate, but they don't write strings,
239 but rather null-padded character sequences.
240 .\" ----- DESCRIPTION :: Null-padded character sequences --------------/
241 .SS Null-padded character sequences
242 For historic reasons,
243 some standard APIs and file formats,
244 such as
245 .BR utmpx (5)
246 and
247 .BR tar (1),
248 use null-padded character sequences in fixed-size buffers.
249 To interface with them,
250 specialized functions need to be used.
251 .P
252 To copy bytes from strings into these buffers, use
253 .BR strncpy (3)
254 or
255 .BR stpncpy (3).
256 .P
257 To read a null-padded character sequence,
258 use
259 .IR "strnlen(src,\ NITEMS(src))" ,
260 and then you can treat it as a known-length character sequence;
261 or use
262 .BR strncat (3)
263 or
264 .BR strndup (3)
265 directly.
266 .\" ----- DESCRIPTION :: Known-length character sequences -----------------/
267 .SS Known-length character sequences
268 The simplest character sequence copying function is
269 .BR mempcpy (3).
270 It requires always knowing the length of your character sequences,
271 for which structures can be used.
272 It makes the code much faster,
273 since you always know the length of your character sequences,
274 and can do the minimal copies and length measurements.
275 .BR mempcpy (3)
276 copies character sequences,
277 so you need to explicitly set the terminating null character
278 if you need a string.
279 .P
280 In programs that make considerable use of strings or character sequences,
281 and need the best performance,
282 using overlapping character sequences can make a big difference.
283 It allows holding subsequences of a larger character sequence,
284 while not duplicating memory
285 nor using time to do a copy.
286 .P
287 However, this is delicate,
288 since it requires using character sequences.
289 C library APIs use strings,
290 so programs that use character sequences
291 will have to take care of differentiating strings from character sequences.
292 .P
293 To copy a known-length character sequence, use
294 .BR mempcpy (3).
295 .P
296 To copy a known-length character sequence into a string, use
297 .IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" .
298 .P
299 A string is also accepted as input,
300 because
301 .BR mempcpy (3)
302 asks for the length,
303 and a string is composed of a character sequence of the same length
304 plus a terminating null character.
305 .\" ----- DESCRIPTION :: String vs character sequence -----------------/
306 .SS String vs character sequence
307 Some functions only operate on strings.
308 Those require that the input
309 .I src
310 is a string,
311 and guarantee an output string
312 (even when truncation occurs).
313 Functions that catenate
314 also require that
315 .I dst
316 holds a string before the call.
317 List of functions:
318 .IP \[bu] 3
319 .PD 0
320 .BR stpcpy (3)
321 .IP \[bu]
322 .BR strcpy (3),
323 .BR strcat (3)
324 .IP \[bu]
325 .BR stpecpy ()
326 .IP \[bu]
327 .BR strtcpy ()
328 .IP \[bu]
329 .BR strlcpy (3bsd),
330 .BR strlcat (3bsd)
331 .PD
332 .P
333 Other functions require an input string,
334 but create a character sequence as output.
335 These functions have confusing names,
336 and have a long history of misuse.
337 List of functions:
338 .IP \[bu] 3
339 .PD 0
340 .BR stpncpy (3)
341 .IP \[bu]
342 .BR strncpy (3)
343 .PD
344 .P
345 Other functions operate on an input character sequence,
346 and create an output string.
347 Functions that catenate
348 also require that
349 .I dst
350 holds a string before the call.
351 .BR strncat (3)
352 has an even more misleading name than the functions above.
353 List of functions:
354 .IP \[bu] 3
355 .PD 0
356 .BR strncat (3)
357 .IP \[bu]
358 .BR strndup (3)
359 .PD
360 .P
361 Other functions operate on an input character sequence
362 to create an output character sequence.
363 List of functions:
364 .IP \[bu] 3
365 .BR mempcpy (3)
366 .\" ----- DESCRIPTION :: Functions :: ---------------------------------/
367 .SS Functions
368 .\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/
369 .TP
370 .BR stpcpy (3)
371 Copy the input string into a destination string.
372 The programmer is responsible for allocating a buffer large enough.
373 It returns a pointer suitable for chaining.
374 .\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/
375 .TP
376 .BR strcpy (3)
377 .TQ
378 .BR strcat (3)
379 Copy and catenate the input string into a destination string.
380 The programmer is responsible for allocating a buffer large enough.
381 The return value is useless.
382 .IP
383 .BR stpcpy (3)
384 is a faster alternative to these functions.
385 .\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/
386 .TP
387 .BR stpecpy ()
388 Chain-copy the input string into a destination string.
389 If the destination buffer,
390 limited by a pointer to its end,
391 isn't large enough to hold the copy,
392 the resulting string is truncated
393 (but it is guaranteed to be null-terminated).
394 It returns a pointer suitable for chaining.
395 Truncation needs to be detected only once after the last chained call.
396 .IP
397 This function is not provided by any library;
398 see EXAMPLES for a reference implementation.
399 .\" ----- DESCRIPTION :: Functions :: strtcpy() -----------------------/
400 .TP
401 .BR strtcpy ()
402 Copy the input string into a destination string.
403 If the destination buffer isn't large enough to hold the copy,
404 the resulting string is truncated
405 (but it is guaranteed to be null-terminated).
406 It returns the length of the string,
407 or \-1 if it truncated.
408 .IP
409 This function is not provided by any library;
410 see EXAMPLES for a reference implementation.
411 .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/
412 .TP
413 .BR strlcpy (3bsd)
414 .TQ
415 .BR strlcat (3bsd)
416 Copy and catenate the input string into a destination string.
417 If the destination buffer,
418 limited by its size,
419 isn't large enough to hold the copy,
420 the resulting string is truncated
421 (but it is guaranteed to be null-terminated).
422 They return the length of the total string they tried to create.
423 .IP
424 Check BUGS before using these functions.
425 .IP
426 .BR strtcpy ()
427 and
428 .BR stpecpy ()
429 are better alternatives to these functions.
430 .\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/
431 .TP
432 .BR stpncpy (3)
433 Copy the input string into
434 a destination null-padded character sequence in a fixed-size buffer.
435 If the destination buffer,
436 limited by its size,
437 isn't large enough to hold the copy,
438 the resulting character sequence is truncated.
439 Since it creates a character sequence,
440 it doesn't need to write a terminating null character.
441 It's impossible to distinguish truncation by the result of the call,
442 from a character sequence that just fits the destination buffer;
443 truncation should be detected by
444 comparing the length of the input string
445 with the size of the destination buffer.
446 .\" ----- DESCRIPTION :: Functions :: strncpy(3) ----------------------/
447 .TP
448 .BR strncpy (3)
449 This function is identical to
450 .BR stpncpy (3)
451 except for the useless return value.
452 .IP
453 .BR stpncpy (3)
454 is a more useful alternative to this function.
455 .\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/
456 .TP
457 .BR strncat (3)
458 Catenate the input character sequence,
459 contained in a null-padded fixed-size buffer,
460 into a destination string.
461 The programmer is responsible for allocating a buffer large enough.
462 The return value is useless.
463 .IP
464 Do not confuse this function with
465 .BR strncpy (3);
466 they are not related at all.
467 .IP
468 .I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ NITEMS(src))),\ \[dq]\[dq])
469 is a faster alternative to this function.
470 .\" ----- DESCRIPTION :: Functions :: strndup(3) ----------------------/
471 .TP
472 .BR strndup (3)
473 Duplicate the input character sequence,
474 contained in a null-padded fixed-size buffer,
475 into a newly allocated destination string.
476 .IP
477 The string must be freed with
478 .BR free (3).
479 .\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/
480 .TP
481 .BR mempcpy (3)
482 Copy the input character sequence,
483 limited by its length,
484 into a destination character sequence.
485 The programmer is responsible for allocating a buffer large enough.
486 It returns a pointer suitable for chaining.
487 .\" ----- RETURN VALUE :: ---------------------------------------------/
488 .SH RETURN VALUE
489 .TP
490 .BR stpcpy (3)
491 A pointer to the terminating null character in the destination string.
492 .TP
493 .BR stpecpy ()
494 A pointer to the terminating null character in the destination string,
495 on success.
496 On error,
497 NULL is returned,
498 and
499 .I errno
500 is set to indicate the error.
501 .TP
502 .BR mempcpy (3)
503 .TQ
504 .BR stpncpy (3)
505 A pointer to one after the last character
506 in the destination character sequence.
507 .TP
508 .BR strtcpy ()
509 The length of the string,
510 on success.
511 On error,
512 \-1 is returned,
513 and
514 .I errno
515 is set to indicate the error.
516 .TP
517 .BR strlcpy (3bsd)
518 .TQ
519 .BR strlcat (3bsd)
520 The length of the total string that they tried to create
521 (as if truncation didn't occur).
522 .TP
523 .BR strcpy (3)
524 .TQ
525 .BR strcat (3)
526 .TQ
527 .BR strncpy (3)
528 .TQ
529 .BR strncat (3)
530 The
531 .I dst
532 pointer,
533 which is useless.
534 .TP
535 .BR strndup (3)
536 The newly allocated string.
537 .\" ----- ERRORS ------------------------------------------------------/
538 .SH ERRORS
539 Most of these functions don't set
540 .IR errno .
541 .TP
542 .BR stpecpy ()
543 .TQ
544 .BR strtcpy ()
545 .RS
546 .TP
547 .B ENOBUFS
548 .I dsize
549 was
550 .BR 0 .
551 .TP
552 .B E2BIG
553 The string has been truncated.
554 .RE
555 .TP
556 .BR strndup (3)
557 .RS
558 .TP
559 .B ENOMEM
560 Insufficient memory available to allocate duplicate string.
561 .RE
562 .\" ----- NOTES :: strscpy(9) -----------------------------------------/
563 .SH NOTES
564 The Linux kernel has an internal function for copying strings,
565 .BR strscpy (9),
566 which is identical to
567 .BR strtcpy (),
568 except that it returns
569 .B \-E2BIG
570 instead of \-1
571 and it doesn't set
572 .IR errno .
573 .\" ----- CAVEATS :: --------------------------------------------------/
574 .SH CAVEATS
575 Don't mix chain calls to truncating and non-truncating functions.
576 It is conceptually wrong
577 unless you know that the first part of a copy will always fit.
578 Anyway, the performance difference will probably be negligible,
579 so it will probably be more clear if you use consistent semantics:
580 either truncating or non-truncating.
581 Calling a non-truncating function after a truncating one is necessarily wrong.
582 .\" ----- BUGS :: -----------------------------------------------------/
583 .SH BUGS
584 All catenation functions share the same performance problem:
585 .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
586 Shlemiel the painter
587 .UE .
588 As a mitigation,
589 compilers are able to transform some calls to catenation functions
590 into normal copy functions,
591 since
592 .I strlen(dst)
593 is usually a byproduct of the previous copy.
594 .P
595 .BR strlcpy (3)
596 and
597 .BR strlcat (3)
598 need to read the entire
599 .I src
600 string,
601 even if the destination buffer is small.
602 This makes them vulnerable to Denial of Service (DoS) attacks
603 if an attacker can control the length of the
604 .I src
605 string.
606 And if not,
607 they're still unnecessarily slow.
608 .\" ----- EXAMPLES :: -------------------------------------------------/
609 .SH EXAMPLES
610 The following are examples of correct use of each of these functions.
611 .\" ----- EXAMPLES :: stpcpy(3) ---------------------------------------/
612 .TP
613 .BR stpcpy (3)
614 .EX
615 p = buf;
616 p = stpcpy(p, "Hello ");
617 p = stpcpy(p, "world");
618 p = stpcpy(p, "!");
619 len = p \- buf;
620 puts(buf);
621 .EE
622 .\" ----- EXAMPLES :: strcpy(3), strcat(3) ----------------------------/
623 .TP
624 .BR strcpy (3)
625 .TQ
626 .BR strcat (3)
627 .EX
628 strcpy(buf, "Hello ");
629 strcat(buf, "world");
630 strcat(buf, "!");
631 len = strlen(buf);
632 puts(buf);
633 .EE
634 .\" ----- EXAMPLES :: stpecpy() ---------------------------------------/
635 .TP
636 .BR stpecpy ()
637 .EX
638 end = buf + NITEMS(buf);
639 p = buf;
640 p = stpecpy(p, end, "Hello ");
641 p = stpecpy(p, end, "world");
642 p = stpecpy(p, end, "!");
643 if (p == NULL) {
644 len = NITEMS(buf) \- 1;
645 goto toolong;
646 }
647 len = p \- buf;
648 puts(buf);
649 .EE
650 .\" ----- EXAMPLES :: strtcpy() ---------------------------------------/
651 .TP
652 .BR strtcpy ()
653 .EX
654 len = strtcpy(buf, "Hello world!", NITEMS(buf));
655 if (len == \-1)
656 goto toolong;
657 puts(buf);
658 .EE
659 .\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/
660 .TP
661 .BR strlcpy (3bsd)
662 .TQ
663 .BR strlcat (3bsd)
664 .EX
665 if (strlcpy(buf, "Hello ", NITEMS(buf)) >= NITEMS(buf))
666 goto toolong;
667 if (strlcat(buf, "world", NITEMS(buf)) >= NITEMS(buf))
668 goto toolong;
669 len = strlcat(buf, "!", NITEMS(buf));
670 if (len >= NITEMS(buf))
671 goto toolong;
672 puts(buf);
673 .EE
674 .\" ----- EXAMPLES :: stpncpy(3) --------------------------------------/
675 .TP
676 .BR stpncpy (3)
677 .EX
678 p = stpncpy(u->ut_user, "alx", NITEMS(u->ut_user));
679 if (NITEMS(u->ut_user) < strlen("alx"))
680 goto toolong;
681 len = p \- u->ut_user;
682 fwrite(u->ut_user, 1, len, stdout);
683 .EE
684 .\" ----- EXAMPLES :: strncpy(3) --------------------------------------/
685 .TP
686 .BR strncpy (3)
687 .EX
688 strncpy(u->ut_user, "alx", NITEMS(u->ut_user));
689 if (NITEMS(u->ut_user) < strlen("alx"))
690 goto toolong;
691 len = strnlen(u->ut_user, NITEMS(u->ut_user));
692 fwrite(u->ut_user, 1, len, stdout);
693 .EE
694 .\" ----- EXAMPLES :: mempcpy(dst, src, strnlen(src, NITEMS(src))) ----/
695 .TP
696 .I mempcpy(dst, src, strnlen(src, NITEMS(src)))
697 .EX
698 char buf[NITEMS(u->ut_user)];
699 p = buf;
700 p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user)));
701 len = p \- buf;
702 fwrite(buf, 1, len, stdout);
703 .EE
704 .\" ----- EXAMPLES :: stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "")
705 .TP
706 .I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq])
707 .EX
708 char buf[NITEMS(u->ut_user) + 1];
709 p = buf;
710 p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user)));
711 p = stpcpy(p, "");
712 len = p \- buf;
713 puts(buf);
714 .EE
715 .\" ----- EXAMPLES :: strncat(3) --------------------------------------/
716 .TP
717 .BR strncat (3)
718 .EX
719 char buf[NITEMS(u->ut_user) + 1];
720 strcpy(buf, "");
721 strncat(buf, u->ut_user, NITEMS(u->ut_user));
722 len = strlen(buf);
723 puts(buf);
724 .EE
725 .\" ----- EXAMPLES :: strndup(3) --------------------------------------/
726 .TP
727 .BR strndup (3)
728 .EX
729 buf = strndup(u->ut_user, NITEMS(u->ut_user));
730 len = strlen(buf);
731 puts(buf);
732 free(buf);
733 .EE
734 .\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/
735 .TP
736 .BR mempcpy (3)
737 .EX
738 p = buf;
739 p = mempcpy(p, "Hello ", 6);
740 p = mempcpy(p, "world", 5);
741 p = mempcpy(p, "!", 1);
742 len = p \- buf;
743 fwrite(buf, 1, len, stdout);
744 .EE
745 .\" ----- EXAMPLES :: stpcpy(mempcpy(), "") ---------------------------/
746 .TP
747 .I stpcpy(mempcpy(dst, src, len), \[dq]\[dq])
748 .EX
749 p = buf;
750 p = mempcpy(p, "Hello ", 6);
751 p = mempcpy(p, "world", 5);
752 p = mempcpy(p, "!", 1);
753 p = stpcpy(p, "");
754 len = p \- buf;
755 puts(buf);
756 .EE
757 .\" ----- EXAMPLES :: Implementations :: ------------------------------/
758 .SS Implementations
759 Here are reference implementations for functions not provided by libc.
760 .P
761 .in +4n
762 .EX
763 /* This code is in the public domain. */
764 \&
765 .\" ----- EXAMPLES :: Implementations :: stpecpy() --------------------/
766 char *
767 .IR stpecpy "(char *dst, char end[0], const char *restrict src)"
768 {
769 size_t dlen;
770 \&
771 if (dst == NULL)
772 return NULL;
773 \&
774 dlen = strtcpy(dst, src, end \- dst);
775 return (dlen == \-1) ? NULL : dst + dlen;
776 }
777 \&
778 .\" ----- EXAMPLES :: Implementations :: strtcpy() --------------------/
779 ssize_t
780 .IR strtcpy "(char *restrict dst, const char *restrict src, size_t dsize)"
781 {
782 bool trunc;
783 size_t dlen, slen;
784 \&
785 if (dsize == 0) {
786 errno = ENOBUFS;
787 return \-1;
788 }
789 \&
790 slen = strnlen(src, dsize);
791 trunc = (slen == dsize);
792 dlen = slen \- trunc;
793 \&
794 stpcpy(mempcpy(dst, src, dlen), "");
795 if (trunc)
796 errno = E2BIG;
797 return trunc ? \-1 : slen;
798 }
799 .\" ----- SEE ALSO :: -------------------------------------------------/
800 .SH SEE ALSO
801 .BR bzero (3),
802 .BR memcpy (3),
803 .BR memccpy (3),
804 .BR mempcpy (3),
805 .BR stpcpy (3),
806 .BR strlcpy (3bsd),
807 .BR strncat (3),
808 .BR stpncpy (3),
809 .BR string (3)