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. 4 5 #ifndef BASE_STRINGS_SAFE_SPRINTF_H_ 6 #define BASE_STRINGS_SAFE_SPRINTF_H_ 7 8 #include "build/build_config.h" 9 10 #include <stddef.h> 11 #include <stdint.h> 12 #include <stdlib.h> 13 14 #if defined(OS_POSIX) 15 // For ssize_t 16 #include <unistd.h> 17 #endif 18 19 #include "base/base_export.h" 20 #include "base/basictypes.h" 21 22 namespace base { 23 namespace strings { 24 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 33 34 // SafeSPrintf() is a type-safe and completely self-contained version of 35 // snprintf(). 36 // 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() 40 // 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. 45 // 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. 52 // 53 // The code currently only supports a subset of format characters: 54 // %c, %o, %d, %x, %X, %p, and %s. 55 // 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. 62 // 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. 66 // 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. 69 // 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. 73 // 74 // There are a few features of snprintf()-style format strings, that 75 // SafeSPrintf() does not support at this time. 76 // 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. 80 // 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. 85 // 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. 89 // 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. 93 // 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. 99 // 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. 106 // 107 // Basic example: 108 // char buf[20]; 109 // base::strings::SafeSPrintf(buf, "The answer: %2d", 42); 110 // 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 // } 132 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(). 137 138 struct Arg { 139 enum Type { INT, UINT, STRING, POINTER }; 140 141 // Any integer-like value. 142 Arg(signed char c) : type(INT) { 143 integer.i = c; 144 integer.width = sizeof(char); 145 } 146 Arg(unsigned char c) : type(UINT) { 147 integer.i = c; 148 integer.width = sizeof(char); 149 } 150 Arg(signed short j) : type(INT) { 151 integer.i = j; 152 integer.width = sizeof(short); 153 } 154 Arg(unsigned short j) : type(UINT) { 155 integer.i = j; 156 integer.width = sizeof(short); 157 } 158 Arg(signed int j) : type(INT) { 159 integer.i = j; 160 integer.width = sizeof(int); 161 } 162 Arg(unsigned int j) : type(UINT) { 163 integer.i = j; 164 integer.width = sizeof(int); 165 } 166 Arg(signed long j) : type(INT) { 167 integer.i = j; 168 integer.width = sizeof(long); 169 } 170 Arg(unsigned long j) : type(UINT) { 171 integer.i = j; 172 integer.width = sizeof(long); 173 } 174 Arg(signed long long j) : type(INT) { 175 integer.i = j; 176 integer.width = sizeof(long long); 177 } 178 Arg(unsigned long long j) : type(UINT) { 179 integer.i = j; 180 integer.width = sizeof(long long); 181 } 182 183 // A C-style text string. 184 Arg(const char* s) : str(s), type(STRING) { } 185 Arg(char* s) : str(s), type(STRING) { } 186 187 // Any pointer value that can be cast to a "void*". 188 template<class T> Arg(T* p) : ptr((void*)p), type(POINTER) { } 189 190 union { 191 // An integer-like value. 192 struct { 193 int64_t i; 194 unsigned char width; 195 } integer; 196 197 // A C-style text string. 198 const char* str; 199 200 // A pointer to an arbitrary object. 201 const void* ptr; 202 }; 203 const enum Type type; 204 }; 205 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); 210 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 218 219 } // namespace internal 220 221 // TODO(markus): C++11 has a much more concise and readable solution for 222 // expressing what we are doing here. 223 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 233 }; 234 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 235 } 236 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 247 }; 248 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 249 } 250 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 260 }; 261 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 262 } 263 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 274 }; 275 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 276 } 277 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 287 }; 288 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 289 } 290 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 301 }; 302 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 303 } 304 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 314 }; 315 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 316 } 317 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 328 }; 329 return internal::SafeSNPrintf(buf, N, fmt, arg_array, arraysize(arg_array)); 330 } 331 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)); 339 } 340 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)); 349 } 350 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)); 358 } 359 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)); 367 } 368 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)); 376 } 377 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)); 385 } 386 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)); 394 } 395 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)); 403 } 404 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)); 411 } 412 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)); 419 } 420 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)); 427 } 428 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)); 435 } 436 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); 442 } 443 444 } // namespace strings 445 } // namespace base 446 447 #endif // BASE_STRINGS_SAFE_SPRINTF_H_ 448