| 1 | #ifndef QEMU_CUTILS_H |
| 2 | #define QEMU_CUTILS_H |
| 3 | |
| 4 | /* |
| 5 | * si_prefix: |
| 6 | * @exp10: exponent of 10, a multiple of 3 between -18 and 18 inclusive. |
| 7 | * |
| 8 | * Return a SI prefix (n, u, m, K, M, etc.) corresponding |
| 9 | * to the given exponent of 10. |
| 10 | */ |
| 11 | const char *si_prefix(unsigned int exp10); |
| 12 | |
| 13 | /* |
| 14 | * iec_binary_prefix: |
| 15 | * @exp2: exponent of 2, a multiple of 10 between 0 and 60 inclusive. |
| 16 | * |
| 17 | * Return an IEC binary prefix (Ki, Mi, etc.) corresponding |
| 18 | * to the given exponent of 2. |
| 19 | */ |
| 20 | const char *iec_binary_prefix(unsigned int exp2); |
| 21 | |
| 22 | /** |
| 23 | * pstrcpy: |
| 24 | * @buf: buffer to copy string into |
| 25 | * @buf_size: size of @buf in bytes |
| 26 | * @str: string to copy |
| 27 | * |
| 28 | * Copy @str into @buf, including the trailing NUL, but do not |
| 29 | * write more than @buf_size bytes. The resulting buffer is |
| 30 | * always NUL terminated (even if the source string was too long). |
| 31 | * If @buf_size is zero or negative then no bytes are copied. |
| 32 | * |
| 33 | * This function is similar to strncpy(), but avoids two of that |
| 34 | * function's problems: |
| 35 | * * if @str fits in the buffer, pstrcpy() does not zero-fill the |
| 36 | * remaining space at the end of @buf |
| 37 | * * if @str is too long, pstrcpy() will copy the first @buf_size-1 |
| 38 | * bytes and then add a NUL |
| 39 | */ |
| 40 | void pstrcpy(char *buf, int buf_size, const char *str); |
| 41 | /** |
| 42 | * strpadcpy: |
| 43 | * @buf: buffer to copy string into |
| 44 | * @buf_size: size of @buf in bytes |
| 45 | * @str: string to copy |
| 46 | * @pad: character to pad the remainder of @buf with |
| 47 | * |
| 48 | * Copy @str into @buf (but *not* its trailing NUL!), and then pad the |
| 49 | * rest of the buffer with the @pad character. If @str is too large |
| 50 | * for the buffer then it is truncated, so that @buf contains the |
| 51 | * first @buf_size characters of @str, with no terminator. |
| 52 | */ |
| 53 | void strpadcpy(char *buf, int buf_size, const char *str, char pad); |
| 54 | /** |
| 55 | * pstrcat: |
| 56 | * @buf: buffer containing existing string |
| 57 | * @buf_size: size of @buf in bytes |
| 58 | * @s: string to concatenate to @buf |
| 59 | * |
| 60 | * Append a copy of @s to the string already in @buf, but do not |
| 61 | * allow the buffer to overflow. If the existing contents of @buf |
| 62 | * plus @str would total more than @buf_size bytes, then write |
| 63 | * as much of @str as will fit followed by a NUL terminator. |
| 64 | * |
| 65 | * @buf must already contain a NUL-terminated string, or the |
| 66 | * behaviour is undefined. |
| 67 | * |
| 68 | * Returns: @buf. |
| 69 | */ |
| 70 | char *pstrcat(char *buf, int buf_size, const char *s); |
| 71 | /** |
| 72 | * strstart: |
| 73 | * @str: string to test |
| 74 | * @val: prefix string to look for |
| 75 | * @ptr: NULL, or pointer to be written to indicate start of |
| 76 | * the remainder of the string |
| 77 | * |
| 78 | * Test whether @str starts with the prefix @val. |
| 79 | * If it does (including the degenerate case where @str and @val |
| 80 | * are equal) then return true. If @ptr is not NULL then a |
| 81 | * pointer to the first character following the prefix is written |
| 82 | * to it. If @val is not a prefix of @str then return false (and |
| 83 | * @ptr is not written to). |
| 84 | * |
| 85 | * Returns: true if @str starts with prefix @val, false otherwise. |
| 86 | */ |
| 87 | int strstart(const char *str, const char *val, const char **ptr); |
| 88 | /** |
| 89 | * stristart: |
| 90 | * @str: string to test |
| 91 | * @val: prefix string to look for |
| 92 | * @ptr: NULL, or pointer to be written to indicate start of |
| 93 | * the remainder of the string |
| 94 | * |
| 95 | * Test whether @str starts with the case-insensitive prefix @val. |
| 96 | * This function behaves identically to strstart(), except that the |
| 97 | * comparison is made after calling qemu_toupper() on each pair of |
| 98 | * characters. |
| 99 | * |
| 100 | * Returns: true if @str starts with case-insensitive prefix @val, |
| 101 | * false otherwise. |
| 102 | */ |
| 103 | int stristart(const char *str, const char *val, const char **ptr); |
| 104 | |
| 105 | /** |
| 106 | * qemu_strsep: |
| 107 | * @input: pointer to string to parse |
| 108 | * @delim: string containing delimiter characters to search for |
| 109 | * |
| 110 | * Locate the first occurrence of any character in @delim within |
| 111 | * the string referenced by @input, and replace it with a NUL. |
| 112 | * The location of the next character after the delimiter character |
| 113 | * is stored into @input. |
| 114 | * If the end of the string was reached without finding a delimiter |
| 115 | * character, then NULL is stored into @input. |
| 116 | * If @input points to a NULL pointer on entry, return NULL. |
| 117 | * The return value is always the original value of *@input (and |
| 118 | * so now points to a NUL-terminated string corresponding to the |
| 119 | * part of the input up to the first delimiter). |
| 120 | * |
| 121 | * This function has the same behaviour as the BSD strsep() function. |
| 122 | * |
| 123 | * Returns: the pointer originally in @input. |
| 124 | */ |
| 125 | char *qemu_strsep(char **input, const char *delim); |
| 126 | #ifdef HAVE_STRCHRNUL |
| 127 | static inline const char *qemu_strchrnul(const char *s, int c) |
| 128 | { |
| 129 | return strchrnul(s, c); |
| 130 | } |
| 131 | #else |
| 132 | const char *qemu_strchrnul(const char *s, int c); |
| 133 | #endif |
| 134 | time_t mktimegm(struct tm *tm); |
| 135 | int qemu_parse_fd(const char *param); |
| 136 | int qemu_strtoi(const char *nptr, const char **endptr, int base, |
| 137 | int *result); |
| 138 | int qemu_strtoui(const char *nptr, const char **endptr, int base, |
| 139 | unsigned int *result); |
| 140 | int qemu_strtol(const char *nptr, const char **endptr, int base, |
| 141 | long *result); |
| 142 | int qemu_strtoul(const char *nptr, const char **endptr, int base, |
| 143 | unsigned long *result); |
| 144 | int qemu_strtoi64(const char *nptr, const char **endptr, int base, |
| 145 | int64_t *result); |
| 146 | int qemu_strtou64(const char *nptr, const char **endptr, int base, |
| 147 | uint64_t *result); |
| 148 | int qemu_strtod(const char *nptr, const char **endptr, double *result); |
| 149 | int qemu_strtod_finite(const char *nptr, const char **endptr, double *result); |
| 150 | |
| 151 | int parse_uint(const char *s, const char **endptr, int base, uint64_t *value); |
| 152 | int parse_uint_full(const char *s, int base, uint64_t *value); |
| 153 | |
| 154 | int qemu_strtosz(const char *nptr, const char **end, uint64_t *result); |
| 155 | int qemu_strtosz_MiB(const char *nptr, const char **end, uint64_t *result); |
| 156 | int qemu_strtosz_metric(const char *nptr, const char **end, uint64_t *result); |
| 157 | |
| 158 | char *size_to_str(uint64_t val); |
| 159 | |
| 160 | /** |
| 161 | * freq_to_str: |
| 162 | * @freq_hz: frequency to stringify |
| 163 | * |
| 164 | * Return human readable string for frequency @freq_hz. |
| 165 | * Use SI units like KHz, MHz, and so forth. |
| 166 | * |
| 167 | * The caller is responsible for releasing the value returned |
| 168 | * with g_free() after use. |
| 169 | */ |
| 170 | char *freq_to_str(uint64_t freq_hz); |
| 171 | |
| 172 | /* used to print char* safely */ |
| 173 | #define STR_OR_NULL(str) ((str) ? (str) : "null") |
| 174 | |
| 175 | /* |
| 176 | * Check if a buffer is all zeroes. |
| 177 | */ |
| 178 | |
| 179 | bool buffer_is_zero_ool(const void *vbuf, size_t len); |
| 180 | bool buffer_is_zero_ge256(const void *vbuf, size_t len); |
| 181 | bool test_buffer_is_zero_next_accel(void); |
| 182 | |
| 183 | static inline bool buffer_is_zero_sample3(const char *buf, size_t len) |
| 184 | { |
| 185 | /* |
| 186 | * For any reasonably sized buffer, these three samples come from |
| 187 | * three different cachelines. In qemu-img usage, we find that |
| 188 | * each byte eliminates more than half of all buffer testing. |
| 189 | * It is therefore critical to performance that the byte tests |
| 190 | * short-circuit, so that we do not pull in additional cache lines. |
| 191 | * Do not "optimize" this to !(a | b | c). |
| 192 | */ |
| 193 | return !buf[0] && !buf[len - 1] && !buf[len / 2]; |
| 194 | } |
| 195 | |
| 196 | #ifdef __OPTIMIZE__ |
| 197 | static inline bool buffer_is_zero(const void *buf, size_t len) |
| 198 | { |
| 199 | return (__builtin_constant_p(len) && len >= 256 |
| 200 | ? buffer_is_zero_sample3(buf, len) && |
| 201 | buffer_is_zero_ge256(buf, len) |
| 202 | : buffer_is_zero_ool(buf, len)); |
| 203 | } |
| 204 | #else |
| 205 | #define buffer_is_zero buffer_is_zero_ool |
| 206 | #endif |
| 207 | |
| 208 | /* |
| 209 | * Implementation of ULEB128 (http://en.wikipedia.org/wiki/LEB128) |
| 210 | * Input is limited to 14-bit numbers |
| 211 | */ |
| 212 | |
| 213 | int uleb128_encode_small(uint8_t *out, uint32_t n); |
| 214 | int uleb128_decode_small(const uint8_t *in, uint32_t *n); |
| 215 | |
| 216 | /** |
| 217 | * qemu_pstrcmp0: |
| 218 | * @str1: a non-NULL pointer to a C string (*str1 can be NULL) |
| 219 | * @str2: a non-NULL pointer to a C string (*str2 can be NULL) |
| 220 | * |
| 221 | * Compares *str1 and *str2 with g_strcmp0(). |
| 222 | * |
| 223 | * Returns: an integer less than, equal to, or greater than zero, if |
| 224 | * *str1 is <, == or > than *str2. |
| 225 | */ |
| 226 | int qemu_pstrcmp0(const char **str1, const char **str2); |
| 227 | |
| 228 | /* Find program directory, and save it for later usage with |
| 229 | * get_relocated_path(). |
| 230 | * Try OS specific API first, if not working, parse from argv0. */ |
| 231 | void qemu_init_exec_dir(const char *argv0); |
| 232 | |
| 233 | /** |
| 234 | * get_relocated_path: |
| 235 | * @dir: the directory (typically a `CONFIG_*DIR` variable) to be relocated. |
| 236 | * |
| 237 | * Returns a path for @dir that uses the directory of the running executable |
| 238 | * as the prefix. |
| 239 | * |
| 240 | * When a directory named `qemu-bundle` exists in the directory of the running |
| 241 | * executable, the path to the directory will be prepended to @dir. For |
| 242 | * example, if the directory of the running executable is `/qemu/build` @dir |
| 243 | * is `/usr/share/qemu`, the result will be |
| 244 | * `/qemu/build/qemu-bundle/usr/share/qemu`. The directory is expected to exist |
| 245 | * in the build tree. |
| 246 | * |
| 247 | * Otherwise, the directory of the running executable will be used as the |
| 248 | * prefix and it appends the relative path from `bindir` to @dir. For example, |
| 249 | * if the directory of the running executable is `/opt/qemu/bin`, `bindir` is |
| 250 | * `/usr/bin` and @dir is `/usr/share/qemu`, the result will be |
| 251 | * `/opt/qemu/bin/../share/qemu`. |
| 252 | * |
| 253 | * The returned string should be freed by the caller. |
| 254 | */ |
| 255 | char *get_relocated_path(const char *dir); |
| 256 | |
| 257 | static inline const char *yes_no(bool b) |
| 258 | { |
| 259 | return b ? "yes" : "no"; |
| 260 | } |
| 261 | |
| 262 | /* |
| 263 | * helper to parse debug environment variables |
| 264 | */ |
| 265 | int parse_debug_env(const char *name, int max, int initial); |
| 266 | |
| 267 | /** |
| 268 | * qemu_hexdump_line: |
| 269 | * @str: GString into which to append |
| 270 | * @buf: buffer to dump |
| 271 | * @len: number of bytes to dump |
| 272 | * @unit_len: add a space between every @unit_len bytes |
| 273 | * @block_len: add an extra space between every @block_len bytes |
| 274 | * |
| 275 | * Append @len bytes of @buf as hexadecimal into @str. |
| 276 | * Add spaces between every @unit_len and @block_len bytes. |
| 277 | * If @str is NULL, allocate a new string and return it; |
| 278 | * otherwise return @str. |
| 279 | */ |
| 280 | GString *qemu_hexdump_line(GString *str, const void *buf, size_t len, |
| 281 | size_t unit_len, size_t block_len); |
| 282 | |
| 283 | /* |
| 284 | * Hexdump a buffer to a file. An optional string prefix is added to every line |
| 285 | */ |
| 286 | |
| 287 | void qemu_hexdump(FILE *fp, const char *prefix, |
| 288 | const void *bufptr, size_t size); |
| 289 | |
| 290 | /** |
| 291 | * qemu_hexdump_to_buffer: |
| 292 | * @buffer: output string buffer |
| 293 | * @buffer_size: amount of available space in buffer. Must be at least |
| 294 | * data_size*2+1. |
| 295 | * @data: input bytes |
| 296 | * @data_size: number of bytes in data |
| 297 | * |
| 298 | * Converts the @data_size bytes in @data into hex digit pairs, writing them to |
| 299 | * @buffer. Finally, a nul terminating character is written; @buffer therefore |
| 300 | * needs space for (data_size*2+1) chars. |
| 301 | */ |
| 302 | void qemu_hexdump_to_buffer(char *restrict buffer, size_t buffer_size, |
| 303 | const uint8_t *restrict data, size_t data_size); |
| 304 | |
| 305 | #endif |