Debian Codegraph @

upstream/debian-unstable/man3/snprintf.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH snprintf 3 2025-12-07 "Linux man-pages 6.18"
7 .SH NAME
8 snprintf,
9 vsnprintf
10 \-
11 string print formatted
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <stdio.h>
18 .P
19 .BR "int snprintf(" "size_t size;"
20 .BI " char " str "[restrict " size "], size_t " size ,
21 .BI " const char *restrict " format ", ...);"
22 .BR "int vsnprintf(" "size_t size;"
23 .BI " char " str "[restrict " size "], size_t " size ,
24 .BI " const char *restrict " format ", va_list " ap );
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 snprintf (),
33 .BR vsnprintf ():
34 .nf
35 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
36 || /* glibc <= 2.19: */ _BSD_SOURCE
37 .fi
38 .SH DESCRIPTION
39 These functions are similar to
40 .BR printf (3),
41 except that they write to the character string
42 .I str
43 instead of a stream.
44 .P
45 The functions
46 .BR snprintf ()
47 and
48 .BR vsnprintf ()
49 write at most
50 .I size
51 bytes (including the terminating null byte (\[aq]\[rs]0\[aq])) to
52 .IR str .
53 .P
54 .BR vsnprintf ()
55 is equivalent to
56 .BR snprintf (),
57 except that it is called with a
58 .I va_list
59 instead of a variable number of arguments.
60 This function does not call the
61 .I va_end
62 macro.
63 Because it invokes the
64 .I va_arg
65 macro, the value of
66 .I ap
67 is undefined after the call.
68 See
69 .BR stdarg (3).
70 .P
71 C99 and POSIX.1-2001 specify that the results are undefined if a call to
72 .BR snprintf ()
73 or
74 .BR vsnprintf ()
75 would cause copying to take place between objects that overlap
76 (e.g., if the target string array and one of the supplied input arguments
77 refer to the same buffer).
78 See CAVEATS.
79 .SS Format of the format string
80 See
81 .BR printf (3).
82 .SH RETURN VALUE
83 Upon successful return, these functions return the number of bytes
84 printed (excluding the null byte used to end output to strings).
85 .P
86 The functions
87 .BR snprintf ()
88 and
89 .BR vsnprintf ()
90 do not write more than
91 .I size
92 bytes (including the terminating null byte (\[aq]\[rs]0\[aq])).
93 If the output was truncated due to this limit, then the return value
94 is the number of characters (excluding the terminating null byte)
95 which would have been written to the final string if enough space
96 had been available.
97 Thus, a return value of
98 .I size
99 or more means that the output was truncated.
100 (See also below under CAVEATS.)
101 .P
102 On error,
103 a negative value is returned,
104 and
105 .I errno
106 is set to indicate the error.
107 .SH ERRORS
108 See
109 .BR printf (3).
110 .SH ATTRIBUTES
111 For an explanation of the terms used in this section, see
112 .BR attributes (7).
113 .TS
114 allbox;
115 lbx lb lb
116 l l l.
117 Interface Attribute Value
118 T{
119 .na
120 .nh
121 .BR snprintf (),
122 .BR vsnprintf ()
123 T} Thread safety MT-Safe locale
124 .TE
125 .SH STANDARDS
126 C11, POSIX.1-2008.
127 .SH HISTORY
128 SUSv2, C99, POSIX.1-2001.
129 .IP
130 Concerning the return value,
131 SUSv2 and C99 contradict each other: when
132 .BR snprintf ()
133 is called with
134 .IR size =0
135 then SUSv2 stipulates an unspecified return value less than 1,
136 while C99 allows
137 .I str
138 to be NULL in this case, and gives the return value (as always)
139 as the number of characters that would have been written in case
140 the output string has been large enough.
141 POSIX.1-2001 and later align their specification of
142 .BR snprintf ()
143 with C99.
144 .SH CAVEATS
145 Some programs imprudently rely on code such as the following
146 .P
147 .in +4n
148 .EX
149 snprintf(buf, countof(buf), "%s some further text", buf);
150 .EE
151 .in
152 .P
153 to append text to
154 .IR buf .
155 However, the standards explicitly note that the results are undefined
156 if source and destination buffers overlap when calling
157 .BR snprintf ()
158 and
159 .BR vsnprintf ().
160 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
161 Depending on the version of
162 .BR gcc (1)
163 used, and the compiler options employed, calls such as the above will
164 .B not
165 produce the expected results.
166 .P
167 The glibc implementation of the functions
168 .BR snprintf ()
169 and
170 .BR vsnprintf ()
171 conforms to the C99 standard, that is, behaves as described above,
172 since glibc 2.1.
173 Until glibc 2.0.6, they would return \-1
174 when the output was truncated.
175 .\" .SH HISTORY
176 .\" UNIX V7 defines the three routines
177 .\" .BR sprintf ().
178 .\" 2.11BSD has
179 .\" .BR vsprintf ().
180 .\" 4.4BSD introduces the functions
181 .\" .BR snprintf ()
182 .\" and
183 .\" .BR vsnprintf ().
184 .\" FreeBSD also has functions
185 .\" .BR asprintf ()
186 .\" and
187 .\" .BR vasprintf (),
188 .\" that allocate a buffer large enough for
189 .\" .BR sprintf ().
190 .SH BUGS
191 See
192 .BR printf (3).
193 .SH EXAMPLES
194 To allocate a sufficiently large string and print into it
195 (code correct for both glibc 2.0 and glibc 2.1):
196 .P
197 .EX
198 #include <stdio.h>
199 #include <stdlib.h>
200 #include <stdarg.h>
201 \&
202 char *
203 make_message(const char *fmt, ...)
204 {
205 int n = 0;
206 size_t size = 0;
207 char *p = NULL;
208 va_list ap;
209 \&
210 /* Determine required size. */
211 \&
212 va_start(ap, fmt);
213 n = vsnprintf(p, size, fmt, ap);
214 va_end(ap);
215 \&
216 if (n < 0)
217 return NULL;
218 \&
219 size = (size_t) n + 1; /* One extra byte for \[aq]\[rs]0\[aq] */
220 p = malloc(size);
221 if (p == NULL)
222 return NULL;
223 \&
224 va_start(ap, fmt);
225 n = vsnprintf(p, size, fmt, ap);
226 va_end(ap);
227 \&
228 if (n < 0) {
229 free(p);
230 return NULL;
231 }
232 \&
233 return p;
234 }
235 .EE
236 .P
237 If truncation occurs in glibc versions prior to glibc 2.0.6,
238 this is treated as an error instead of being handled gracefully.
239 .SH SEE ALSO
240 .BR printf (1),
241 .BR asprintf (3),
242 .BR printf (3),
243 .BR puts (3),
244 .BR scanf (3),
245 .BR setlocale (3),
246 .BR strfromd (3),
247 .BR wcrtomb (3),
248 .BR wprintf (3),
249 .BR locale (5)