Debian Codegraph @

upstream/debian-unstable/man3/stpncpy.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH stpncpy 3 2026-02-25 "Linux man-pages 6.18"
7 .SH NAME
8 stpncpy, strncpy
9 \-
10 fill a fixed-size buffer with non-null bytes from a string,
11 padding with null bytes as needed
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <string.h>
18 .P
19 .BR "char *strncpy(" "size_t dsize;"
20 .BI " char " dst "[restrict " dsize "], const char *restrict " src ,
21 .BI " size_t " dsize );
22 .BR "char *stpncpy(" "size_t dsize;"
23 .BI " char " dst "[restrict " dsize "], const char *restrict " src ,
24 .BI " size_t " dsize );
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
32 .BR stpncpy ():
33 .nf
34 Since glibc 2.10:
35 _POSIX_C_SOURCE >= 200809L
36 Before glibc 2.10:
37 _GNU_SOURCE
38 .fi
39 .SH DESCRIPTION
40 These functions copy non-null bytes from the string pointed to by
41 .I src
42 into the array pointed to by
43 .IR dst .
44 If the source has too few non-null bytes to fill the destination,
45 the functions pad the destination with trailing null bytes.
46 If the destination buffer,
47 limited by its size,
48 isn't large enough to hold the copy,
49 the resulting character sequence is truncated.
50 For the difference between the two functions, see RETURN VALUE.
51 .TP
52 .BR strncpy ()
53 It is equivalent to
54 .IP
55 .in +4n
56 .EX
57 stpncpy(dst, src, dsize), dst
58 .EE
59 .in
60 .TP
61 .BR stpncpy ()
62 It is equivalent to
63 .IP
64 .in +4n
65 .EX
66 memset(mempcpy(dst, src, strnlen(src, dsize)), \[aq]\[rs]0\[aq],
67 dsize \- strnlen(src, dsize))
68 .EE
69 .in
70 .SH RETURN VALUE
71 .TP
72 .BR strncpy ()
73 returns
74 .IR dst .
75 .TP
76 .BR stpncpy ()
77 returns a pointer to
78 one past the last non-null character written,
79 that is,
80 .IR dest\~+\~strnlen(src,\~n) .
81 .SH ATTRIBUTES
82 For an explanation of the terms used in this section, see
83 .BR attributes (7).
84 .TS
85 allbox;
86 lbx lb lb
87 l l l.
88 Interface Attribute Value
89 T{
90 .na
91 .nh
92 .BR stpncpy (),
93 .BR strncpy ()
94 T} Thread safety MT-Safe
95 .TE
96 .SH STANDARDS
97 .TP
98 .BR strncpy ()
99 C11, POSIX.1-2008.
100 .TP
101 .BR stpncpy ()
102 POSIX.1-2008.
103 .SH HISTORY
104 .TP
105 .BR strncpy ()
106 C89, POSIX.1-2001, SVr4, 4.3BSD.
107 .TP
108 .BR stpncpy ()
109 glibc 1.07.
110 POSIX.1-2008.
111 .SH CAVEATS
112 The name of these functions is confusing.
113 These functions produce a null-padded character sequence,
114 not a string (see
115 .BR string_copying (7)).
116 For example:
117 .P
118 .in +4n
119 .EX
120 strncpy(buf, "1", 5); // { \[aq]1\[aq], 0, 0, 0, 0 }
121 strncpy(buf, "1234", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], 0 }
122 strncpy(buf, "12345", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] }
123 strncpy(buf, "123456", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] }
124 .EE
125 .in
126 .P
127 It's impossible to distinguish truncation by the result of the call,
128 from a character sequence that just fits the destination buffer;
129 truncation should be detected by
130 comparing the length of the input string
131 with the size of the destination buffer.
132 .P
133 If you're going to use this function in chained calls,
134 it would be useful to develop a similar function that accepts
135 a pointer to the end (one after the last element) of the destination buffer
136 instead of its size.
137 .SH EXAMPLES
138 .\" SRC BEGIN (stpncpy.c)
139 .EX
140 #include <err.h>
141 #include <stdio.h>
142 #include <stdlib.h>
143 #include <string.h>
144 \&
145 int
146 main(void)
147 {
148 char *p;
149 char buf1[20];
150 char buf2[20];
151 size_t len;
152 \&
153 if (sizeof(buf2) < strlen("Hello world!"))
154 errx("strncpy: truncating character sequence");
155 strncpy(buf2, "Hello world!", sizeof(buf2));
156 len = strnlen(buf2, sizeof(buf2));
157 \&
158 printf("[len = %zu]: ", len);
159 fwrite(buf2, 1, len, stdout);
160 putchar(\[aq]\[rs]n\[aq]);
161 \&
162 if (sizeof(buf1) < strlen("Hello world!"))
163 errx("stpncpy: truncating character sequence");
164 p = stpncpy(buf1, "Hello world!", sizeof(buf1));
165 len = p \- buf1;
166 \&
167 printf("[len = %zu]: ", len);
168 fwrite(buf1, 1, len, stdout);
169 putchar(\[aq]\[rs]n\[aq]);
170 \&
171 exit(EXIT_SUCCESS);
172 }
173 .EE
174 .\" SRC END
175 .SH SEE ALSO
176 .BR wcpncpy (3),
177 .BR string_copying (7)