vsprintf.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371
  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. * @cp: The string to be converted
  14. * @endp: Updated to point to the first character not converted
  15. * @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. * @cp: The string to be converted
  34. * @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. * @cp: The string to be converted
  46. * @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. * @cp: The string to be converted
  57. * @base: The number base to use (0 for the default)
  58. * @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. * Note that this does not handle a string without a prefix. See dectoul() for
  95. * that case.
  96. *
  97. * @str: String to examine
  98. * Return: trailing number if found, else -1
  99. */
  100. long trailing_strtol(const char *str);
  101. /**
  102. * trailing_strtoln() - extract a trailing integer from a fixed-length string
  103. *
  104. * Given a fixed-length string this finds a trailing number on the string
  105. * and returns it. For example, "abc123" would return 123. Only the
  106. * characters between @str and @end - 1 are examined. If @end is NULL, it is
  107. * set to str + strlen(str).
  108. *
  109. * @str: String to examine
  110. * @end: Pointer to end of string to examine, or NULL to use the
  111. * whole string
  112. * Return: trailing number if found, else -1
  113. */
  114. long trailing_strtoln(const char *str, const char *end);
  115. /**
  116. * trailing_strtoln_end() - extract trailing integer from a fixed-length string
  117. *
  118. * Given a fixed-length string this finds a trailing number on the string
  119. * and returns it. For example, "abc123" would return 123. Only the
  120. * characters between @str and @end - 1 are examined. If @end is NULL, it is
  121. * set to str + strlen(str).
  122. *
  123. * @str: String to examine
  124. * @end: Pointer to end of string to examine, or NULL to use the
  125. * whole string
  126. * @endp: If non-NULL, this is set to point to the character where the
  127. * number starts, e.g. for "mmc0" this would be point to the '0'; if no
  128. * trailing number is found, it is set to the end of the string
  129. * Return: training number if found, else -1
  130. */
  131. long trailing_strtoln_end(const char *str, const char *end, char const **endp);
  132. /**
  133. * panic() - Print a message and reset/hang
  134. *
  135. * Prints a message on the console(s) and then resets. If CONFIG_PANIC_HANG is
  136. * defined, then it will hang instead of resetting.
  137. *
  138. * @fmt: printf() format string for message, which should not include
  139. * \n, followed by arguments
  140. */
  141. void panic(const char *fmt, ...)
  142. __attribute__ ((format (__printf__, 1, 2), noreturn));
  143. /**
  144. * panic_str() - Print a message and reset/hang
  145. *
  146. * Prints a message on the console(s) and then resets. If CONFIG_PANIC_HANG is
  147. * defined, then it will hang instead of resetting.
  148. *
  149. * This function can be used instead of panic() when your board does not
  150. * already use printf(), * to keep code size small.
  151. *
  152. * @str: string to display, which should not include \n
  153. */
  154. void panic_str(const char *str) __attribute__ ((noreturn));
  155. /**
  156. * Format a string and place it in a buffer
  157. *
  158. * @buf: The buffer to place the result into
  159. * @fmt: The format string to use
  160. * @...: Arguments for the format string
  161. *
  162. * The function returns the number of characters written
  163. * into @buf.
  164. *
  165. * See the vsprintf() documentation for format string extensions over C99.
  166. */
  167. int sprintf(char *buf, const char *fmt, ...)
  168. __attribute__ ((format (__printf__, 2, 3)));
  169. /**
  170. * Format a string and place it in a buffer (va_list version)
  171. *
  172. * @buf: The buffer to place the result into
  173. * @fmt: The format string to use
  174. * @args: Arguments for the format string
  175. * Return: the number of characters which have been written into
  176. * the @buf not including the trailing '\0'.
  177. *
  178. * If you're not already dealing with a va_list consider using scnprintf().
  179. *
  180. * See the vsprintf() documentation for format string extensions over C99.
  181. */
  182. int vsprintf(char *buf, const char *fmt, va_list args);
  183. /**
  184. * simple_itoa() - convert an unsigned integer to a string
  185. *
  186. * This returns a static string containing the decimal representation of the
  187. * given value. The returned value may be overwritten by other calls to other
  188. * simple... functions, so should be used immediately
  189. *
  190. * @val: Value to convert
  191. * Return: string containing the decimal representation of @val
  192. */
  193. char *simple_itoa(ulong val);
  194. /**
  195. * simple_xtoa() - convert an unsigned integer to a hex string
  196. *
  197. * This returns a static string containing the hexadecimal representation of the
  198. * given value. The returned value may be overwritten by other calls to other
  199. * simple... functions, so should be used immediately
  200. *
  201. * @num: Value to convert
  202. * Return: string containing the hexecimal representation of @val
  203. */
  204. char *simple_xtoa(ulong num);
  205. /**
  206. * Format a string and place it in a buffer
  207. *
  208. * @buf: The buffer to place the result into
  209. * @size: The size of the buffer, including the trailing null space
  210. * @fmt: The format string to use
  211. * @...: Arguments for the format string
  212. * Return: the number of characters which would be
  213. * generated for the given input, excluding the trailing null,
  214. * as per ISO C99. If the return is greater than or equal to
  215. * @size, the resulting string is truncated.
  216. *
  217. * See the vsprintf() documentation for format string extensions over C99.
  218. */
  219. int snprintf(char *buf, size_t size, const char *fmt, ...)
  220. __attribute__ ((format (__printf__, 3, 4)));
  221. /**
  222. * Format a string and place it in a buffer
  223. *
  224. * @buf: The buffer to place the result into
  225. * @size: The size of the buffer, including the trailing null space
  226. * @fmt: The format string to use
  227. * @...: Arguments for the format string
  228. *
  229. * The return value is the number of characters written into @buf not including
  230. * the trailing '\0'. If @size is == 0 the function returns 0.
  231. *
  232. * See the vsprintf() documentation for format string extensions over C99.
  233. */
  234. int scnprintf(char *buf, size_t size, const char *fmt, ...)
  235. __attribute__ ((format (__printf__, 3, 4)));
  236. /**
  237. * Format a string and place it in a buffer (base function)
  238. *
  239. * @buf: The buffer to place the result into
  240. * @size: The size of the buffer, including the trailing null space
  241. * @fmt: The format string to use
  242. * @args: Arguments for the format string
  243. * Return: The number characters which would be generated for the given
  244. * input, excluding the trailing '\0', as per ISO C99. Note that fewer
  245. * characters may be written if this number of characters is >= size.
  246. *
  247. * This function follows C99 vsnprintf, but has some extensions:
  248. * %pS output the name of a text symbol
  249. * %pF output the name of a function pointer
  250. * %pR output the address range in a struct resource
  251. *
  252. * The function returns the number of characters which would be
  253. * generated for the given input, excluding the trailing '\0',
  254. * as per ISO C99.
  255. *
  256. * Call this function if you are already dealing with a va_list.
  257. * You probably want snprintf() instead.
  258. */
  259. int vsnprintf(char *buf, size_t size, const char *fmt, va_list args);
  260. /**
  261. * Format a string and place it in a buffer (va_list version)
  262. *
  263. * @buf: The buffer to place the result into
  264. * @size: The size of the buffer, including the trailing null space
  265. * @fmt: The format string to use
  266. * @args: Arguments for the format string
  267. * Return: the number of characters which have been written into
  268. * the @buf not including the trailing '\0'. If @size is == 0 the function
  269. * returns 0.
  270. *
  271. * If you're not already dealing with a va_list consider using scnprintf().
  272. *
  273. * See the vsprintf() documentation for format string extensions over C99.
  274. */
  275. int vscnprintf(char *buf, size_t size, const char *fmt, va_list args);
  276. /**
  277. * print_grouped_ull() - print a value with digits grouped by ','
  278. *
  279. * This prints a value with grouped digits, like 12,345,678 to make it easier
  280. * to read.
  281. *
  282. * @int_val: Value to print
  283. * @digits: Number of digiits to print
  284. */
  285. void print_grouped_ull(unsigned long long int_val, int digits);
  286. bool str2off(const char *p, loff_t *num);
  287. bool str2long(const char *p, ulong *num);
  288. /**
  289. * strmhz() - Convert a value to a Hz string
  290. *
  291. * This creates a string indicating the number of MHz of a value. For example,
  292. * 2700000 produces "2.7".
  293. * @buf: Buffer to hold output string, which must be large enough
  294. * @hz: Value to convert
  295. */
  296. char *strmhz(char *buf, unsigned long hz);
  297. /**
  298. * str_to_upper() - Convert a string to upper case
  299. *
  300. * This simply uses toupper() on each character of the string.
  301. *
  302. * @in: String to convert (must be large enough to hold the output string)
  303. * @out: Buffer to put converted string
  304. * @len: Number of bytes available in @out (SIZE_MAX for all)
  305. */
  306. void str_to_upper(const char *in, char *out, size_t len);
  307. /**
  308. * str_to_list() - Convert a string to a list of string pointers
  309. *
  310. * Splits a string containing space-delimited substrings into a number of
  311. * separate strings, e.g. "this is" becomes {"this", "is", NULL}. If @instr is
  312. * empty then this returns just {NULL}. The string should have only a single
  313. * space between items, with no leading or trailing spaces.
  314. *
  315. * @instr: String to process (this is alloced by this function)
  316. * Returns: List of string pointers, terminated by NULL. Each entry points to
  317. * a string. If @instr is empty, the list consists just of a single NULL entry.
  318. * Note that the first entry points to the alloced string.
  319. * Returns NULL if out of memory
  320. */
  321. const char **str_to_list(const char *instr);
  322. /**
  323. * str_free_list() - Free a string list
  324. *
  325. * @ptr: String list to free, as created by str_to_list(). This can also be
  326. * NULL, in which case the function does nothing
  327. */
  328. void str_free_list(const char **ptr);
  329. /**
  330. * vsscanf - Unformat a buffer into a list of arguments
  331. * @inp: input buffer
  332. * @fmt0: format of buffer
  333. * @ap: arguments
  334. */
  335. int vsscanf(const char *inp, char const *fmt0, va_list ap);
  336. /**
  337. * sscanf - Unformat a buffer into a list of arguments
  338. * @buf: input buffer
  339. * @fmt: formatting of buffer
  340. * @...: resulting arguments
  341. */
  342. int sscanf(const char *buf, const char *fmt, ...);
  343. #endif