vsprintf.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * (C) Copyright 2000-2009
  4. * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
  5. */
  6. #ifndef __VSPRINTF_H
  7. #define __VSPRINTF_H
  8. #include <stdarg.h>
  9. #include <linux/types.h>
  10. /**
  11. * simple_strtoul - convert a string to an unsigned long
  12. *
  13. * @param cp The string to be converted
  14. * @param endp Updated to point to the first character not converted
  15. * @param base The number base to use (0 for the default)
  16. * Return: value decoded from string (0 if invalid)
  17. *
  18. * Converts a string to an unsigned long. If there are invalid characters at
  19. * the end these are ignored. In the worst case, if all characters are invalid,
  20. * 0 is returned
  21. *
  22. * A hex prefix is supported (e.g. 0x123) regardless of the value of @base.
  23. * If found, the base is set to hex (16).
  24. *
  25. * If @base is 0:
  26. * - an octal '0' prefix (e.g. 0777) sets the base to octal (8).
  27. * - otherwise the base defaults to decimal (10).
  28. */
  29. ulong simple_strtoul(const char *cp, char **endp, unsigned int base);
  30. /**
  31. * hex_strtoul - convert a string in hex to an unsigned long
  32. *
  33. * @param cp The string to be converted
  34. * @param endp Updated to point to the first character not converted
  35. * Return: value decoded from string (0 if invalid)
  36. *
  37. * Converts a hex string to an unsigned long. If there are invalid characters at
  38. * the end these are ignored. In the worst case, if all characters are invalid,
  39. * 0 is returned
  40. */
  41. unsigned long hextoul(const char *cp, char **endp);
  42. /**
  43. * dec_strtoul - convert a string in decimal to an unsigned long
  44. *
  45. * @param cp The string to be converted
  46. * @param endp Updated to point to the first character not converted
  47. * Return: value decoded from string (0 if invalid)
  48. *
  49. * Converts a decimal string to an unsigned long. If there are invalid
  50. * characters at the end these are ignored. In the worst case, if all characters
  51. * are invalid, 0 is returned
  52. */
  53. unsigned long dectoul(const char *cp, char **endp);
  54. /**
  55. * strict_strtoul - convert a string to an unsigned long strictly
  56. * @param cp The string to be converted
  57. * @param base The number base to use (0 for the default)
  58. * @param res The converted result value
  59. * Return: 0 if conversion is successful and *res is set to the converted
  60. * value, otherwise it returns -EINVAL and *res is set to 0.
  61. *
  62. * strict_strtoul converts a string to an unsigned long only if the
  63. * string is really an unsigned long string, any string containing
  64. * any invalid char at the tail will be rejected and -EINVAL is returned,
  65. * only a newline char at the tail is acceptible because people generally
  66. * change a module parameter in the following way:
  67. *
  68. * echo 1024 > /sys/module/e1000/parameters/copybreak
  69. *
  70. * echo will append a newline to the tail.
  71. *
  72. * A hex prefix is supported (e.g. 0x123) regardless of the value of @base.
  73. * If found, the base is set to hex (16).
  74. *
  75. * If @base is 0:
  76. * - an octal '0' prefix (e.g. 0777) sets the base to octal (8).
  77. * - otherwise the base defaults to decimal (10).
  78. *
  79. * Copied this function from Linux 2.6.38 commit ID:
  80. * 521cb40b0c44418a4fd36dc633f575813d59a43d
  81. *
  82. */
  83. int strict_strtoul(const char *cp, unsigned int base, unsigned long *res);
  84. unsigned long long simple_strtoull(const char *cp, char **endp,
  85. unsigned int base);
  86. long simple_strtol(const char *cp, char **endp, unsigned int base);
  87. long long simple_strtoll(const char *cp, char **endp, unsigned int base);
  88. /**
  89. * trailing_strtol() - extract a trailing integer from a string
  90. *
  91. * Given a string this finds a trailing number on the string and returns it.
  92. * For example, "abc123" would return 123.
  93. *
  94. * @str: String to exxamine
  95. * Return: training number if found, else -1
  96. */
  97. long trailing_strtol(const char *str);
  98. /**
  99. * trailing_strtoln() - extract a trailing integer from a fixed-length string
  100. *
  101. * Given a fixed-length string this finds a trailing number on the string
  102. * and returns it. For example, "abc123" would return 123. Only the
  103. * characters between @str and @end - 1 are examined. If @end is NULL, it is
  104. * set to str + strlen(str).
  105. *
  106. * @str: String to exxamine
  107. * @end: Pointer to end of string to examine, or NULL to use the
  108. * whole string
  109. * Return: training number if found, else -1
  110. */
  111. long trailing_strtoln(const char *str, const char *end);
  112. /**
  113. * panic() - Print a message and reset/hang
  114. *
  115. * Prints a message on the console(s) and then resets. If CONFIG_PANIC_HANG is
  116. * defined, then it will hang instead of resetting.
  117. *
  118. * @param fmt: printf() format string for message, which should not include
  119. * \n, followed by arguments
  120. */
  121. void panic(const char *fmt, ...)
  122. __attribute__ ((format (__printf__, 1, 2), noreturn));
  123. /**
  124. * panic_str() - Print a message and reset/hang
  125. *
  126. * Prints a message on the console(s) and then resets. If CONFIG_PANIC_HANG is
  127. * defined, then it will hang instead of resetting.
  128. *
  129. * This function can be used instead of panic() when your board does not
  130. * already use printf(), * to keep code size small.
  131. *
  132. * @param fmt: string to display, which should not include \n
  133. */
  134. void panic_str(const char *str) __attribute__ ((noreturn));
  135. /**
  136. * Format a string and place it in a buffer
  137. *
  138. * @param buf The buffer to place the result into
  139. * @param fmt The format string to use
  140. * @param ... Arguments for the format string
  141. *
  142. * The function returns the number of characters written
  143. * into @buf.
  144. *
  145. * See the vsprintf() documentation for format string extensions over C99.
  146. */
  147. int sprintf(char *buf, const char *fmt, ...)
  148. __attribute__ ((format (__printf__, 2, 3)));
  149. /**
  150. * Format a string and place it in a buffer (va_list version)
  151. *
  152. * @param buf The buffer to place the result into
  153. * @param fmt The format string to use
  154. * @param args Arguments for the format string
  155. * Return: the number of characters which have been written into
  156. * the @buf not including the trailing '\0'.
  157. *
  158. * If you're not already dealing with a va_list consider using scnprintf().
  159. *
  160. * See the vsprintf() documentation for format string extensions over C99.
  161. */
  162. int vsprintf(char *buf, const char *fmt, va_list args);
  163. /**
  164. * simple_itoa() - convert an unsigned integer to a string
  165. *
  166. * This returns a static string containing the decimal representation of the
  167. * given value. The returned value may be overwritten by other calls to other
  168. * simple_... functions, so should be used immediately
  169. *
  170. * @val: Value to convert
  171. * Return: string containing the decimal representation of @val
  172. */
  173. char *simple_itoa(ulong val);
  174. /**
  175. * simple_xtoa() - convert an unsigned integer to a hex string
  176. *
  177. * This returns a static string containing the hexadecimal representation of the
  178. * given value. The returned value may be overwritten by other calls to other
  179. * simple_... functions, so should be used immediately
  180. *
  181. * @val: Value to convert
  182. * Return: string containing the hexecimal representation of @val
  183. */
  184. char *simple_xtoa(ulong num);
  185. /**
  186. * Format a string and place it in a buffer
  187. *
  188. * @param buf The buffer to place the result into
  189. * @param size The size of the buffer, including the trailing null space
  190. * @param fmt The format string to use
  191. * @param ... Arguments for the format string
  192. * Return: the number of characters which would be
  193. * generated for the given input, excluding the trailing null,
  194. * as per ISO C99. If the return is greater than or equal to
  195. * @size, the resulting string is truncated.
  196. *
  197. * See the vsprintf() documentation for format string extensions over C99.
  198. */
  199. int snprintf(char *buf, size_t size, const char *fmt, ...)
  200. __attribute__ ((format (__printf__, 3, 4)));
  201. /**
  202. * Format a string and place it in a buffer
  203. *
  204. * @param buf The buffer to place the result into
  205. * @param size The size of the buffer, including the trailing null space
  206. * @param fmt The format string to use
  207. * @param ... Arguments for the format string
  208. *
  209. * The return value is the number of characters written into @buf not including
  210. * the trailing '\0'. If @size is == 0 the function returns 0.
  211. *
  212. * See the vsprintf() documentation for format string extensions over C99.
  213. */
  214. int scnprintf(char *buf, size_t size, const char *fmt, ...)
  215. __attribute__ ((format (__printf__, 3, 4)));
  216. /**
  217. * Format a string and place it in a buffer (base function)
  218. *
  219. * @param buf The buffer to place the result into
  220. * @param size The size of the buffer, including the trailing null space
  221. * @param fmt The format string to use
  222. * @param args Arguments for the format string
  223. * Return: The number characters which would be generated for the given
  224. * input, excluding the trailing '\0', as per ISO C99. Note that fewer
  225. * characters may be written if this number of characters is >= size.
  226. *
  227. * This function follows C99 vsnprintf, but has some extensions:
  228. * %pS output the name of a text symbol
  229. * %pF output the name of a function pointer
  230. * %pR output the address range in a struct resource
  231. *
  232. * The function returns the number of characters which would be
  233. * generated for the given input, excluding the trailing '\0',
  234. * as per ISO C99.
  235. *
  236. * Call this function if you are already dealing with a va_list.
  237. * You probably want snprintf() instead.
  238. */
  239. int vsnprintf(char *buf, size_t size, const char *fmt, va_list args);
  240. /**
  241. * Format a string and place it in a buffer (va_list version)
  242. *
  243. * @param buf The buffer to place the result into
  244. * @param size The size of the buffer, including the trailing null space
  245. * @param fmt The format string to use
  246. * @param args Arguments for the format string
  247. * Return: the number of characters which have been written into
  248. * the @buf not including the trailing '\0'. If @size is == 0 the function
  249. * returns 0.
  250. *
  251. * If you're not already dealing with a va_list consider using scnprintf().
  252. *
  253. * See the vsprintf() documentation for format string extensions over C99.
  254. */
  255. int vscnprintf(char *buf, size_t size, const char *fmt, va_list args);
  256. /**
  257. * print_grouped_ull() - print a value with digits grouped by ','
  258. *
  259. * This prints a value with grouped digits, like 12,345,678 to make it easier
  260. * to read.
  261. *
  262. * @val: Value to print
  263. * @digits: Number of digiits to print
  264. */
  265. void print_grouped_ull(unsigned long long int_val, int digits);
  266. bool str2off(const char *p, loff_t *num);
  267. bool str2long(const char *p, ulong *num);
  268. /**
  269. * strmhz() - Convert a value to a Hz string
  270. *
  271. * This creates a string indicating the number of MHz of a value. For example,
  272. * 2700000 produces "2.7".
  273. * @buf: Buffer to hold output string, which must be large enough
  274. * @hz: Value to convert
  275. */
  276. char *strmhz(char *buf, unsigned long hz);
  277. /**
  278. * str_to_upper() - Convert a string to upper case
  279. *
  280. * This simply uses toupper() on each character of the string.
  281. *
  282. * @in: String to convert (must be large enough to hold the output string)
  283. * @out: Buffer to put converted string
  284. * @len: Number of bytes available in @out (SIZE_MAX for all)
  285. */
  286. void str_to_upper(const char *in, char *out, size_t len);
  287. /**
  288. * vsscanf - Unformat a buffer into a list of arguments
  289. * @buf: input buffer
  290. * @fmt: format of buffer
  291. * @args: arguments
  292. */
  293. int vsscanf(const char *inp, char const *fmt0, va_list ap);
  294. /**
  295. * sscanf - Unformat a buffer into a list of arguments
  296. * @buf: input buffer
  297. * @fmt: formatting of buffer
  298. * @...: resulting arguments
  299. */
  300. int sscanf(const char *buf, const char *fmt, ...);
  301. #endif