Debian Codegraph @

upstream/debian-unstable/man7/string_copying.7

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