safe_sprintf.h 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  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. #ifndef BASE_STRINGS_SAFE_SPRINTF_H_
  5. #define BASE_STRINGS_SAFE_SPRINTF_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include <stdlib.h>
  9. #include "build/build_config.h"
  10. #if BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
  11. // For ssize_t
  12. #include <unistd.h>
  13. #endif
  14. #include "base/base_export.h"
  15. namespace base {
  16. namespace strings {
  17. #if defined(COMPILER_MSVC)
  18. // Define ssize_t inside of our namespace.
  19. #if defined(_WIN64)
  20. typedef __int64 ssize_t;
  21. #else
  22. typedef long ssize_t;
  23. #endif
  24. #endif
  25. // SafeSPrintf() is a type-safe and completely self-contained version of
  26. // snprintf().
  27. //
  28. // SafeSNPrintf() is an alternative function signature that can be used when
  29. // not dealing with fixed-sized buffers. When possible, SafeSPrintf() should
  30. // always be used instead of SafeSNPrintf()
  31. //
  32. // These functions allow for formatting complicated messages from contexts that
  33. // require strict async-signal-safety. In fact, it is safe to call them from
  34. // any low-level execution context, as they are guaranteed to make no library
  35. // or system calls. It deliberately never touches "errno", either.
  36. //
  37. // The only exception to this rule is that in debug builds the code calls
  38. // RAW_CHECK() to help diagnose problems when the format string does not
  39. // match the rest of the arguments. In release builds, no CHECK()s are used,
  40. // and SafeSPrintf() instead returns an output string that expands only
  41. // those arguments that match their format characters. Mismatched arguments
  42. // are ignored.
  43. //
  44. // The code currently only supports a subset of format characters:
  45. // %c, %o, %d, %x, %X, %p, and %s.
  46. //
  47. // SafeSPrintf() aims to be as liberal as reasonably possible. Integer-like
  48. // values of arbitrary width can be passed to all of the format characters
  49. // that expect integers. Thus, it is explicitly legal to pass an "int" to
  50. // "%c", and output will automatically look at the LSB only. It is also
  51. // explicitly legal to pass either signed or unsigned values, and the format
  52. // characters will automatically interpret the arguments accordingly.
  53. //
  54. // It is still not legal to mix-and-match integer-like values with pointer
  55. // values. For instance, you cannot pass a pointer to %x, nor can you pass an
  56. // integer to %p.
  57. //
  58. // The one exception is "0" zero being accepted by "%p". This works-around
  59. // the problem of C++ defining NULL as an integer-like value.
  60. //
  61. // All format characters take an optional width parameter. This must be a
  62. // positive integer. For %d, %o, %x, %X and %p, if the width starts with
  63. // a leading '0', padding is done with '0' instead of ' ' characters.
  64. //
  65. // There are a few features of snprintf()-style format strings, that
  66. // SafeSPrintf() does not support at this time.
  67. //
  68. // If an actual user showed up, there is no particularly strong reason they
  69. // couldn't be added. But that assumes that the trade-offs between complexity
  70. // and utility are favorable.
  71. //
  72. // For example, adding support for negative padding widths, and for %n are all
  73. // likely to be viewed positively. They are all clearly useful, low-risk, easy
  74. // to test, don't jeopardize the async-signal-safety of the code, and overall
  75. // have little impact on other parts of SafeSPrintf() function.
  76. //
  77. // On the other hands, adding support for alternate forms, positional
  78. // arguments, grouping, wide characters, localization or floating point numbers
  79. // are all unlikely to ever be added.
  80. //
  81. // SafeSPrintf() and SafeSNPrintf() mimic the behavior of snprintf() and they
  82. // return the number of bytes needed to store the untruncated output. This
  83. // does *not* include the terminating NUL byte.
  84. //
  85. // They return -1, iff a fatal error happened. This typically can only happen,
  86. // if the buffer size is a) negative, or b) zero (i.e. not even the NUL byte
  87. // can be written). The return value can never be larger than SSIZE_MAX-1.
  88. // This ensures that the caller can always add one to the signed return code
  89. // in order to determine the amount of storage that needs to be allocated.
  90. //
  91. // While the code supports type checking and while it is generally very careful
  92. // to avoid printing incorrect values, it tends to be conservative in printing
  93. // as much as possible, even when given incorrect parameters. Typically, in
  94. // case of an error, the format string will not be expanded. (i.e. something
  95. // like SafeSPrintf(buf, "%p %d", 1, 2) results in "%p 2"). See above for
  96. // the use of RAW_CHECK() in debug builds, though.
  97. //
  98. // Basic example:
  99. // char buf[20];
  100. // base::strings::SafeSPrintf(buf, "The answer: %2d", 42);
  101. //
  102. // Example with dynamically sized buffer (async-signal-safe). This code won't
  103. // work on Visual studio, as it requires dynamically allocating arrays on the
  104. // stack. Consider picking a smaller value for |kMaxSize| if stack size is
  105. // limited and known. On the other hand, if the parameters to SafeSNPrintf()
  106. // are trusted and not controllable by the user, you can consider eliminating
  107. // the check for |kMaxSize| altogether. The current value of SSIZE_MAX is
  108. // essentially a no-op that just illustrates how to implement an upper bound:
  109. // const size_t kInitialSize = 128;
  110. // const size_t kMaxSize = std::numeric_limits<ssize_t>::max();
  111. // size_t size = kInitialSize;
  112. // for (;;) {
  113. // char buf[size];
  114. // size = SafeSNPrintf(buf, size, "Error message \"%s\"\n", err) + 1;
  115. // if (sizeof(buf) < kMaxSize && size > kMaxSize) {
  116. // size = kMaxSize;
  117. // continue;
  118. // } else if (size > sizeof(buf))
  119. // continue;
  120. // write(2, buf, size-1);
  121. // break;
  122. // }
  123. namespace internal {
  124. // Helpers that use C++ overloading, templates, and specializations to deduce
  125. // and record type information from function arguments. This allows us to
  126. // later write a type-safe version of snprintf().
  127. struct Arg {
  128. enum Type { INT, UINT, STRING, POINTER };
  129. // Any integer-like value.
  130. Arg(signed char c) : type(INT) {
  131. integer.i = c;
  132. integer.width = sizeof(char);
  133. }
  134. Arg(unsigned char c) : type(UINT) {
  135. integer.i = c;
  136. integer.width = sizeof(char);
  137. }
  138. Arg(signed short j) : type(INT) {
  139. integer.i = j;
  140. integer.width = sizeof(short);
  141. }
  142. Arg(unsigned short j) : type(UINT) {
  143. integer.i = j;
  144. integer.width = sizeof(short);
  145. }
  146. Arg(signed int j) : type(INT) {
  147. integer.i = j;
  148. integer.width = sizeof(int);
  149. }
  150. Arg(unsigned int j) : type(UINT) {
  151. integer.i = j;
  152. integer.width = sizeof(int);
  153. }
  154. Arg(signed long j) : type(INT) {
  155. integer.i = j;
  156. integer.width = sizeof(long);
  157. }
  158. Arg(unsigned long j) : type(UINT) {
  159. integer.i = static_cast<int64_t>(j);
  160. integer.width = sizeof(long);
  161. }
  162. Arg(signed long long j) : type(INT) {
  163. integer.i = j;
  164. integer.width = sizeof(long long);
  165. }
  166. Arg(unsigned long long j) : type(UINT) {
  167. integer.i = static_cast<int64_t>(j);
  168. integer.width = sizeof(long long);
  169. }
  170. // A C-style text string.
  171. Arg(const char* s) : str(s), type(STRING) { }
  172. Arg(char* s) : str(s), type(STRING) { }
  173. // Any pointer value that can be cast to a "void*".
  174. template<class T> Arg(T* p) : ptr((void*)p), type(POINTER) { }
  175. union {
  176. // An integer-like value.
  177. struct {
  178. int64_t i;
  179. unsigned char width;
  180. } integer;
  181. // A C-style text string.
  182. const char* str;
  183. // A pointer to an arbitrary object.
  184. const void* ptr;
  185. };
  186. const enum Type type;
  187. };
  188. // This is the internal function that performs the actual formatting of
  189. // an snprintf()-style format string.
  190. BASE_EXPORT ssize_t SafeSNPrintf(char* buf, size_t sz, const char* fmt,
  191. const Arg* args, size_t max_args);
  192. #if !defined(NDEBUG)
  193. // In debug builds, allow unit tests to artificially lower the kSSizeMax
  194. // constant that is used as a hard upper-bound for all buffers. In normal
  195. // use, this constant should always be std::numeric_limits<ssize_t>::max().
  196. BASE_EXPORT void SetSafeSPrintfSSizeMaxForTest(size_t max);
  197. BASE_EXPORT size_t GetSafeSPrintfSSizeMaxForTest();
  198. #endif
  199. } // namespace internal
  200. template<typename... Args>
  201. ssize_t SafeSNPrintf(char* buf, size_t N, const char* fmt, Args... args) {
  202. // Use Arg() object to record type information and then copy arguments to an
  203. // array to make it easier to iterate over them.
  204. const internal::Arg arg_array[] = { args... };
  205. return internal::SafeSNPrintf(buf, N, fmt, arg_array, sizeof...(args));
  206. }
  207. template<size_t N, typename... Args>
  208. ssize_t SafeSPrintf(char (&buf)[N], const char* fmt, Args... args) {
  209. // Use Arg() object to record type information and then copy arguments to an
  210. // array to make it easier to iterate over them.
  211. const internal::Arg arg_array[] = { args... };
  212. return internal::SafeSNPrintf(buf, N, fmt, arg_array, sizeof...(args));
  213. }
  214. // Fast-path when we don't actually need to substitute any arguments.
  215. BASE_EXPORT ssize_t SafeSNPrintf(char* buf, size_t N, const char* fmt);
  216. template<size_t N>
  217. inline ssize_t SafeSPrintf(char (&buf)[N], const char* fmt) {
  218. return SafeSNPrintf(buf, N, fmt);
  219. }
  220. } // namespace strings
  221. } // namespace base
  222. #endif // BASE_STRINGS_SAFE_SPRINTF_H_