Roll gyp r1967:1970.
[chromium-blink-merge.git] / base / strings / safe_sprintf.h
blobcbd7d0cd6435e202a4c427c0b70f51bbb72c8009
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"
10 #include <stddef.h>
11 #include <stdint.h>
12 #include <stdlib.h>
14 #if defined(OS_POSIX)
15 // For ssize_t
16 #include <unistd.h>
17 #endif
19 #include "base/base_export.h"
20 #include "base/basictypes.h"
22 namespace base {
23 namespace strings {
25 #if defined(_MSC_VER)
26 // Define ssize_t inside of our namespace.
27 #if defined(_WIN64)
28 typedef __int64 ssize_t;
29 #else
30 typedef long ssize_t;
31 #endif
32 #endif
34 // SafeSPrintf() is a type-safe and completely self-contained version of
35 // snprintf().
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
51 // are ignored.
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
65 // integer to %p.
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.
107 // Basic example:
108 // char buf[20];
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;
121 // for (;;) {
122 // char buf[size];
123 // size = SafeSNPrintf(buf, size, "Error message \"%s\"\n", err) + 1;
124 // if (sizeof(buf) < kMaxSize && size > kMaxSize) {
125 // size = kMaxSize;
126 // continue;
127 // } else if (size > sizeof(buf))
128 // continue;
129 // write(2, buf, size-1);
130 // break;
131 // }
133 namespace internal {
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().
138 struct Arg {
139 enum Type { INT, UINT, STRING, POINTER };
141 // Any integer-like value.
142 Arg(signed char c) : type(INT) {
143 integer.i = c;
144 integer.width = sizeof(char);
146 Arg(unsigned char c) : type(UINT) {
147 integer.i = c;
148 integer.width = sizeof(char);
150 Arg(signed short j) : type(INT) {
151 integer.i = j;
152 integer.width = sizeof(short);
154 Arg(unsigned short j) : type(UINT) {
155 integer.i = j;
156 integer.width = sizeof(short);
158 Arg(signed int j) : type(INT) {
159 integer.i = j;
160 integer.width = sizeof(int);
162 Arg(unsigned int j) : type(UINT) {
163 integer.i = j;
164 integer.width = sizeof(int);
166 Arg(signed long j) : type(INT) {
167 integer.i = j;
168 integer.width = sizeof(long);
170 Arg(unsigned long j) : type(UINT) {
171 integer.i = j;
172 integer.width = sizeof(long);
174 Arg(signed long long j) : type(INT) {
175 integer.i = j;
176 integer.width = sizeof(long long);
178 Arg(unsigned long long j) : type(UINT) {
179 integer.i = j;
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) { }
190 union {
191 // An integer-like value.
192 struct {
193 int64_t i;
194 unsigned char width;
195 } integer;
197 // A C-style text string.
198 const char* str;
200 // A pointer to an arbitrary object.
201 const void* ptr;
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);
211 #if !defined(NDEBUG)
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();
217 #endif
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));
237 template<size_t N,
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));
264 template<size_t N,
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,
279 class T6, class T7>
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));
291 template<size_t N,
292 class T0, class T1, class T2, class T3, class T4, class T5,
293 class T6, class T7>
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,
306 class T6>
307 ssize_t SafeSNPrintf(char* buf, size_t N, const char* fmt,
308 T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4,
309 T5 arg5, T6 arg6) {
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));
318 template<size_t N,
319 class T0, class T1, class T2, class T3, class T4, class T5,
320 class T6>
321 ssize_t SafeSPrintf(char (&buf)[N], const char* fmt,
322 T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, T5 arg5,
323 T6 arg6) {
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));
341 template<size_t N,
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,
398 T2 arg2) {
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));
421 template<class T0>
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);
439 template<size_t N>
440 inline ssize_t SafeSPrintf(char (&buf)[N], const char* fmt) {
441 return SafeSNPrintf(buf, N, fmt);
444 } // namespace strings
445 } // namespace base
447 #endif // BASE_STRINGS_SAFE_SPRINTF_H_