1 // Copyright 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef BASE_STRINGS_SAFE_SPRINTF_H_
6 #define BASE_STRINGS_SAFE_SPRINTF_H_
8 #include "build/build_config.h"
19 #include "base/base_export.h"
20 #include "base/basictypes.h"
26 // Define ssize_t inside of our namespace.
28 typedef __int64 ssize_t
;
34 // SafeSPrintf() is a type-safe and completely self-contained version of
37 // SafeSNPrintf() is an alternative function signature that can be used when
38 // not dealing with fixed-sized buffers. When possible, SafeSPrintf() should
39 // always be used instead of SafeSNPrintf()
41 // These functions allow for formatting complicated messages from contexts that
42 // require strict async-signal-safety. In fact, it is safe to call them from
43 // any low-level execution context, as they are guaranteed to make no library
44 // or system calls. It deliberately never touches "errno", either.
46 // The only exception to this rule is that in debug builds the code calls
47 // RAW_CHECK() to help diagnose problems when the format string does not
48 // match the rest of the arguments. In release builds, no CHECK()s are used,
49 // and SafeSPrintf() instead returns an output string that expands only
50 // those arguments that match their format characters. Mismatched arguments
53 // The code currently only supports a subset of format characters:
54 // %c, %o, %d, %x, %X, %p, and %s.
56 // SafeSPrintf() aims to be as liberal as reasonably possible. Integer-like
57 // values of arbitrary width can be passed to all of the format characters
58 // that expect integers. Thus, it is explicitly legal to pass an "int" to
59 // "%c", and output will automatically look at the LSB only. It is also
60 // explicitly legal to pass either signed or unsigned values, and the format
61 // characters will automatically interpret the arguments accordingly.
63 // It is still not legal to mix-and-match integer-like values with pointer
64 // values. For instance, you cannot pass a pointer to %x, nor can you pass an
67 // The one exception is "0" zero being accepted by "%p". This works-around
68 // the problem of C++ defining NULL as an integer-like value.
70 // All format characters take an optional width parameter. This must be a
71 // positive integer. For %d, %o, %x, %X and %p, if the width starts with
72 // a leading '0', padding is done with '0' instead of ' ' characters.
74 // There are a few features of snprintf()-style format strings, that
75 // SafeSPrintf() does not support at this time.
77 // If an actual user showed up, there is no particularly strong reason they
78 // couldn't be added. But that assumes that the trade-offs between complexity
79 // and utility are favorable.
81 // For example, adding support for negative padding widths, and for %n are all
82 // likely to be viewed positively. They are all clearly useful, low-risk, easy
83 // to test, don't jeopardize the async-signal-safety of the code, and overall
84 // have little impact on other parts of SafeSPrintf() function.
86 // On the other hands, adding support for alternate forms, positional
87 // arguments, grouping, wide characters, localization or floating point numbers
88 // are all unlikely to ever be added.
90 // SafeSPrintf() and SafeSNPrintf() mimic the behavior of snprintf() and they
91 // return the number of bytes needed to store the untruncated output. This
92 // does *not* include the terminating NUL byte.
94 // They return -1, iff a fatal error happened. This typically can only happen,
95 // if the buffer size is a) negative, or b) zero (i.e. not even the NUL byte
96 // can be written). The return value can never be larger than SSIZE_MAX-1.
97 // This ensures that the caller can always add one to the signed return code
98 // in order to determine the amount of storage that needs to be allocated.
100 // While the code supports type checking and while it is generally very careful
101 // to avoid printing incorrect values, it tends to be conservative in printing
102 // as much as possible, even when given incorrect parameters. Typically, in
103 // case of an error, the format string will not be expanded. (i.e. something
104 // like SafeSPrintf(buf, "%p %d", 1, 2) results in "%p 2"). See above for
105 // the use of RAW_CHECK() in debug builds, though.
109 // base::strings::SafeSPrintf(buf, "The answer: %2d", 42);
111 // Example with dynamically sized buffer (async-signal-safe). This code won't
112 // work on Visual studio, as it requires dynamically allocating arrays on the
113 // stack. Consider picking a smaller value for |kMaxSize| if stack size is
114 // limited and known. On the other hand, if the parameters to SafeSNPrintf()
115 // are trusted and not controllable by the user, you can consider eliminating
116 // the check for |kMaxSize| altogether. The current value of SSIZE_MAX is
117 // essentially a no-op that just illustrates how to implement an upper bound:
118 // const size_t kInitialSize = 128;
119 // const size_t kMaxSize = std::numeric_limits<ssize_t>::max();
120 // size_t size = kInitialSize;
123 // size = SafeSNPrintf(buf, size, "Error message \"%s\"\n", err) + 1;
124 // if (sizeof(buf) < kMaxSize && size > kMaxSize) {
127 // } else if (size > sizeof(buf))
129 // write(2, buf, size-1);
134 // Helpers that use C++ overloading, templates, and specializations to deduce
135 // and record type information from function arguments. This allows us to
136 // later write a type-safe version of snprintf().
139 enum Type
{ INT
, UINT
, STRING
, POINTER
};
141 // Any integer-like value.
142 Arg(signed char c
) : type(INT
) {
144 integer
.width
= sizeof(char);
146 Arg(unsigned char c
) : type(UINT
) {
148 integer
.width
= sizeof(char);
150 Arg(signed short j
) : type(INT
) {
152 integer
.width
= sizeof(short);
154 Arg(unsigned short j
) : type(UINT
) {
156 integer
.width
= sizeof(short);
158 Arg(signed int j
) : type(INT
) {
160 integer
.width
= sizeof(int);
162 Arg(unsigned int j
) : type(UINT
) {
164 integer
.width
= sizeof(int);
166 Arg(signed long j
) : type(INT
) {
168 integer
.width
= sizeof(long);
170 Arg(unsigned long j
) : type(UINT
) {
172 integer
.width
= sizeof(long);
174 Arg(signed long long j
) : type(INT
) {
176 integer
.width
= sizeof(long long);
178 Arg(unsigned long long j
) : type(UINT
) {
180 integer
.width
= sizeof(long long);
183 // A C-style text string.
184 Arg(const char* s
) : str(s
), type(STRING
) { }
185 Arg(char* s
) : str(s
), type(STRING
) { }
187 // Any pointer value that can be cast to a "void*".
188 template<class T
> Arg(T
* p
) : ptr((void*)p
), type(POINTER
) { }
191 // An integer-like value.
197 // A C-style text string.
200 // A pointer to an arbitrary object.
203 const enum Type type
;
206 // This is the internal function that performs the actual formatting of
207 // an snprintf()-style format string.
208 BASE_EXPORT ssize_t
SafeSNPrintf(char* buf
, size_t sz
, const char* fmt
,
209 const Arg
* args
, size_t max_args
);
212 // In debug builds, allow unit tests to artificially lower the kSSizeMax
213 // constant that is used as a hard upper-bound for all buffers. In normal
214 // use, this constant should always be std::numeric_limits<ssize_t>::max().
215 BASE_EXPORT
void SetSafeSPrintfSSizeMaxForTest(size_t max
);
216 BASE_EXPORT
size_t GetSafeSPrintfSSizeMaxForTest();
219 } // namespace internal
221 // TODO(markus): C++11 has a much more concise and readable solution for
222 // expressing what we are doing here.
224 template<class T0
, class T1
, class T2
, class T3
, class T4
,
225 class T5
, class T6
, class T7
, class T8
, class T9
>
226 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
227 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
228 T5 arg5
, T6 arg6
, T7 arg7
, T8 arg8
, T9 arg9
) {
229 // Use Arg() object to record type information and then copy arguments to an
230 // array to make it easier to iterate over them.
231 const internal::Arg arg_array
[] = {
232 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
, arg7
, arg8
, arg9
234 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
238 class T0
, class T1
, class T2
, class T3
, class T4
,
239 class T5
, class T6
, class T7
, class T8
, class T9
>
240 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
,
241 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
242 T5 arg5
, T6 arg6
, T7 arg7
, T8 arg8
, T9 arg9
) {
243 // Use Arg() object to record type information and then copy arguments to an
244 // array to make it easier to iterate over them.
245 const internal::Arg arg_array
[] = {
246 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
, arg7
, arg8
, arg9
248 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
251 template<class T0
, class T1
, class T2
, class T3
, class T4
,
252 class T5
, class T6
, class T7
, class T8
>
253 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
254 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
255 T5 arg5
, T6 arg6
, T7 arg7
, T8 arg8
) {
256 // Use Arg() object to record type information and then copy arguments to an
257 // array to make it easier to iterate over them.
258 const internal::Arg arg_array
[] = {
259 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
, arg7
, arg8
261 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
265 class T0
, class T1
, class T2
, class T3
, class T4
, class T5
,
266 class T6
, class T7
, class T8
>
267 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
,
268 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
269 T5 arg5
, T6 arg6
, T7 arg7
, T8 arg8
) {
270 // Use Arg() object to record type information and then copy arguments to an
271 // array to make it easier to iterate over them.
272 const internal::Arg arg_array
[] = {
273 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
, arg7
, arg8
275 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
278 template<class T0
, class T1
, class T2
, class T3
, class T4
, class T5
,
280 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
281 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
282 T5 arg5
, T6 arg6
, T7 arg7
) {
283 // Use Arg() object to record type information and then copy arguments to an
284 // array to make it easier to iterate over them.
285 const internal::Arg arg_array
[] = {
286 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
, arg7
288 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
292 class T0
, class T1
, class T2
, class T3
, class T4
, class T5
,
294 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
,
295 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
296 T5 arg5
, T6 arg6
, T7 arg7
) {
297 // Use Arg() object to record type information and then copy arguments to an
298 // array to make it easier to iterate over them.
299 const internal::Arg arg_array
[] = {
300 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
, arg7
302 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
305 template<class T0
, class T1
, class T2
, class T3
, class T4
, class T5
,
307 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
308 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
,
310 // Use Arg() object to record type information and then copy arguments to an
311 // array to make it easier to iterate over them.
312 const internal::Arg arg_array
[] = {
313 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
315 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
319 class T0
, class T1
, class T2
, class T3
, class T4
, class T5
,
321 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
,
322 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
, T5 arg5
,
324 // Use Arg() object to record type information and then copy arguments to an
325 // array to make it easier to iterate over them.
326 const internal::Arg arg_array
[] = {
327 arg0
, arg1
, arg2
, arg3
, arg4
, arg5
, arg6
329 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
332 template<class T0
, class T1
, class T2
, class T3
, class T4
, class T5
>
333 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
334 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
, T5 arg5
) {
335 // Use Arg() object to record type information and then copy arguments to an
336 // array to make it easier to iterate over them.
337 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
, arg3
, arg4
, arg5
};
338 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
342 class T0
, class T1
, class T2
, class T3
, class T4
, class T5
>
343 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
,
344 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
, T5 arg5
) {
345 // Use Arg() object to record type information and then copy arguments to an
346 // array to make it easier to iterate over them.
347 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
, arg3
, arg4
, arg5
};
348 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
351 template<class T0
, class T1
, class T2
, class T3
, class T4
>
352 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
353 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
, T4 arg4
) {
354 // Use Arg() object to record type information and then copy arguments to an
355 // array to make it easier to iterate over them.
356 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
, arg3
, arg4
};
357 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
360 template<size_t N
, class T0
, class T1
, class T2
, class T3
, class T4
>
361 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
, T0 arg0
, T1 arg1
,
362 T2 arg2
, T3 arg3
, T4 arg4
) {
363 // Use Arg() object to record type information and then copy arguments to an
364 // array to make it easier to iterate over them.
365 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
, arg3
, arg4
};
366 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
369 template<class T0
, class T1
, class T2
, class T3
>
370 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
371 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
) {
372 // Use Arg() object to record type information and then copy arguments to an
373 // array to make it easier to iterate over them.
374 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
, arg3
};
375 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
378 template<size_t N
, class T0
, class T1
, class T2
, class T3
>
379 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
,
380 T0 arg0
, T1 arg1
, T2 arg2
, T3 arg3
) {
381 // Use Arg() object to record type information and then copy arguments to an
382 // array to make it easier to iterate over them.
383 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
, arg3
};
384 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
387 template<class T0
, class T1
, class T2
>
388 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
,
389 T0 arg0
, T1 arg1
, T2 arg2
) {
390 // Use Arg() object to record type information and then copy arguments to an
391 // array to make it easier to iterate over them.
392 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
};
393 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
396 template<size_t N
, class T0
, class T1
, class T2
>
397 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
, T0 arg0
, T1 arg1
,
399 // Use Arg() object to record type information and then copy arguments to an
400 // array to make it easier to iterate over them.
401 const internal::Arg arg_array
[] = { arg0
, arg1
, arg2
};
402 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
405 template<class T0
, class T1
>
406 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
, T0 arg0
, T1 arg1
) {
407 // Use Arg() object to record type information and then copy arguments to an
408 // array to make it easier to iterate over them.
409 const internal::Arg arg_array
[] = { arg0
, arg1
};
410 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
413 template<size_t N
, class T0
, class T1
>
414 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
, T0 arg0
, T1 arg1
) {
415 // Use Arg() object to record type information and then copy arguments to an
416 // array to make it easier to iterate over them.
417 const internal::Arg arg_array
[] = { arg0
, arg1
};
418 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
422 ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
, T0 arg0
) {
423 // Use Arg() object to record type information and then copy arguments to an
424 // array to make it easier to iterate over them.
425 const internal::Arg arg_array
[] = { arg0
};
426 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
429 template<size_t N
, class T0
>
430 ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
, T0 arg0
) {
431 // Use Arg() object to record type information and then copy arguments to an
432 // array to make it easier to iterate over them.
433 const internal::Arg arg_array
[] = { arg0
};
434 return internal::SafeSNPrintf(buf
, N
, fmt
, arg_array
, arraysize(arg_array
));
437 // Fast-path when we don't actually need to substitute any arguments.
438 BASE_EXPORT ssize_t
SafeSNPrintf(char* buf
, size_t N
, const char* fmt
);
440 inline ssize_t
SafeSPrintf(char (&buf
)[N
], const char* fmt
) {
441 return SafeSNPrintf(buf
, N
, fmt
);
444 } // namespace strings
447 #endif // BASE_STRINGS_SAFE_SPRINTF_H_