Debian Codegraph @

upstream/debian-trixie/man3/strncat.3

raw
1 '\" t
2 .\" Copyright 2022 Alejandro Colomar <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH strncat 3 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 strncat
9 \-
10 append non-null bytes from a source array to a string,
11 and null-terminate the result
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ", " \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <string.h>
18 .P
19 .BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ],
20 .BI " size_t " ssize );
21 .fi
22 .SH DESCRIPTION
23 This function appends at most
24 .I ssize
25 non-null bytes from the array pointed to by
26 .IR src ,
27 followed by a null character,
28 to the end of the string pointed to by
29 .IR dst .
30 .I dst
31 must point to a string contained in a buffer that is large enough,
32 that is, the buffer size must be at least
33 .IR "strlen(dst) + strnlen(src, ssize) + 1" .
34 .P
35 An implementation of this function might be:
36 .P
37 .in +4n
38 .EX
39 char *
40 strncat(char *restrict dst, const char *restrict src, size_t ssize)
41 {
42 #define strnul(s) (s + strlen(s))
43 \&
44 stpcpy(mempcpy(strnul(dst), src, strnlen(src, ssize)), "");
45 return dst;
46 }
47 .EE
48 .in
49 .SH RETURN VALUE
50 .BR strncat ()
51 returns
52 .IR dst .
53 .SH ATTRIBUTES
54 For an explanation of the terms used in this section, see
55 .BR attributes (7).
56 .TS
57 allbox;
58 lbx lb lb
59 l l l.
60 Interface Attribute Value
61 T{
62 .na
63 .nh
64 .BR strncat ()
65 T} Thread safety MT-Safe
66 .TE
67 .SH STANDARDS
68 C11, POSIX.1-2008.
69 .SH HISTORY
70 POSIX.1-2001, C89, SVr4, 4.3BSD.
71 .SH CAVEATS
72 The name of this function is confusing;
73 it has no relation to
74 .BR strncpy (3).
75 .P
76 If the destination buffer does not already contain a string,
77 or is not large enough,
78 the behavior is undefined.
79 See
80 .B _FORTIFY_SOURCE
81 in
82 .BR feature_test_macros (7).
83 .SH BUGS
84 This function can be very inefficient.
85 Read about
86 .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
87 Shlemiel the painter
88 .UE .
89 .SH EXAMPLES
90 .\" SRC BEGIN (strncat.c)
91 .EX
92 #include <err.h>
93 #include <stdio.h>
94 #include <stdlib.h>
95 #include <string.h>
96 \&
97 #define nitems(arr) (sizeof((arr)) / sizeof((arr)[0]))
98 \&
99 int
100 main(void)
101 {
102 size_t n;
103 \&
104 // Null-padded fixed-size character sequences
105 char pre[4] = "pre.";
106 char new_post[50] = ".foo.bar";
107 \&
108 // Strings
109 char post[] = ".post";
110 char src[] = "some_long_body.post";
111 char *dest;
112 \&
113 n = nitems(pre) + strlen(src) \- strlen(post) + nitems(new_post) + 1;
114 dest = malloc(sizeof(*dest) * n);
115 if (dest == NULL)
116 err(EXIT_FAILURE, "malloc()");
117 \&
118 dest[0] = \[aq]\[rs]0\[aq]; // There's no 'cpy' function to this 'cat'.
119 strncat(dest, pre, nitems(pre));
120 strncat(dest, src, strlen(src) \- strlen(post));
121 strncat(dest, new_post, nitems(new_post));
122 \&
123 puts(dest); // "pre.some_long_body.foo.bar"
124 free(dest);
125 exit(EXIT_SUCCESS);
126 }
127 .EE
128 .\" SRC END
129 .in
130 .SH SEE ALSO
131 .BR string (3),
132 .BR string_copying (7)