1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2015 Intel Corporation. 3 * Copyright (c) 2022, NVIDIA CORPORATION & AFFILIATES. 4 * All rights reserved. 5 */ 6 7 /** \file 8 * String utility functions 9 */ 10 11 #ifndef SPDK_STRING_H 12 #define SPDK_STRING_H 13 14 #include "spdk/stdinc.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #define _SPDK_STRINGIFY(x) #x 21 #define SPDK_STRINGIFY(x) _SPDK_STRINGIFY(x) 22 23 /** 24 * sprintf with automatic buffer allocation. 25 * 26 * The return value is the formatted string, which should be passed to free() 27 * when no longer needed. 28 * 29 * \param format Format for the string to print. 30 * 31 * \return the formatted string on success, or NULL on failure. 32 */ 33 char *spdk_sprintf_alloc(const char *format, ...) __attribute__((format(printf, 1, 2))); 34 35 /** 36 * vsprintf with automatic buffer allocation. 37 * 38 * The return value is the formatted string, which should be passed to free() 39 * when no longer needed. 40 * 41 * \param format Format for the string to print. 42 * \param args A value that identifies a variable arguments list. 43 * 44 * \return the formatted string on success, or NULL on failure. 45 */ 46 char *spdk_vsprintf_alloc(const char *format, va_list args); 47 48 /** 49 * Append string using vsprintf with automatic buffer re-allocation. 50 * 51 * The return value is the formatted string, in which the original string in 52 * buffer is unchanged and the specified formatted string is appended. 53 * 54 * The returned string should be passed to free() when no longer needed. 55 * 56 * If buffer is NULL, the call is equivalent to spdk_sprintf_alloc(). 57 * If the call fails, the original buffer is left untouched. 58 * 59 * \param buffer Buffer which has a formatted string. 60 * \param format Format for the string to print. 61 * 62 * \return the formatted string on success, or NULL on failure. 63 */ 64 char *spdk_sprintf_append_realloc(char *buffer, const char *format, ...); 65 66 /** 67 * Append string using vsprintf with automatic buffer re-allocation. 68 * The return value is the formatted string, in which the original string in 69 * buffer is unchanged and the specified formatted string is appended. 70 * 71 * The returned string should be passed to free() when no longer needed. 72 * 73 * If buffer is NULL, the call is equivalent to spdk_sprintf_alloc(). 74 * If the call fails, the original buffer is left untouched. 75 * 76 * \param buffer Buffer which has a formatted string. 77 * \param format Format for the string to print. 78 * \param args A value that identifies a variable arguments list. 79 * 80 * \return the formatted string on success, or NULL on failure. 81 */ 82 char *spdk_vsprintf_append_realloc(char *buffer, const char *format, va_list args); 83 84 /** 85 * Convert string to lowercase in place. 86 * 87 * \param s String to convert to lowercase. 88 * 89 * \return the converted string. 90 */ 91 char *spdk_strlwr(char *s); 92 93 /** 94 * Parse a delimited string with quote handling. 95 * 96 * Note that the string will be modified in place to add the string terminator 97 * to each field. 98 * 99 * \param stringp Pointer to starting location in string. *stringp will be updated 100 * to point to the start of the next field, or NULL if the end of the string has 101 * been reached. 102 * \param delim Null-terminated string containing the list of accepted delimiters. 103 * 104 * \return a pointer to beginning of the current field. 105 */ 106 char *spdk_strsepq(char **stringp, const char *delim); 107 108 /** 109 * Trim whitespace from a string in place. 110 * 111 * \param s String to trim. 112 * 113 * \return the trimmed string. 114 */ 115 char *spdk_str_trim(char *s); 116 117 /** 118 * Copy the string version of an error into the user supplied buffer 119 * 120 * \param errnum Error code. 121 * \param buf Pointer to a buffer in which to place the error message. 122 * \param buflen The size of the buffer in bytes. 123 */ 124 void spdk_strerror_r(int errnum, char *buf, size_t buflen); 125 126 /** 127 * Return the string version of an error from a static, thread-local buffer. This 128 * function is thread safe. 129 * 130 * \param errnum Error code. 131 * 132 * \return a pointer to buffer upon success. 133 */ 134 const char *spdk_strerror(int errnum); 135 136 /** 137 * Remove trailing newlines from the end of a string in place. 138 * 139 * Any sequence of trailing \\r and \\n characters is removed from the end of the 140 * string. 141 * 142 * \param s String to remove newline from. 143 * 144 * \return the number of characters removed. 145 */ 146 size_t spdk_str_chomp(char *s); 147 148 /** 149 * Copy a string into a fixed-size buffer, padding extra bytes with a specific 150 * character. 151 * 152 * If src is longer than size, only size bytes will be copied. 153 * 154 * \param dst Pointer to destination fixed-size buffer to fill. 155 * \param src Pointer to source null-terminated string to copy into dst. 156 * \param size Number of bytes to fill in dst. 157 * \param pad Character to pad extra space in dst beyond the size of src. 158 */ 159 void spdk_strcpy_pad(void *dst, const char *src, size_t size, int pad); 160 161 /** 162 * Find the length of a string that has been padded with a specific byte. 163 * 164 * \param str Right-padded string to find the length of. 165 * \param size Size of the full string pointed to by str, including padding. 166 * \param pad Character that was used to pad str up to size. 167 * 168 * \return the length of the non-padded portion of str. 169 */ 170 size_t spdk_strlen_pad(const void *str, size_t size, int pad); 171 172 /** 173 * Parse an IP address into its hostname and port components. This modifies the 174 * IP address in place. 175 * 176 * \param ip A null terminated IP address, including port. Both IPv4 and IPv6 177 * are supported. 178 * \param host Will point to the start of the hostname within ip. The string will 179 * be null terminated. 180 * \param port Will point to the start of the port within ip. The string will be 181 * null terminated. 182 * 183 * \return 0 on success. -EINVAL on failure. 184 */ 185 int spdk_parse_ip_addr(char *ip, char **host, char **port); 186 187 /** 188 * Parse a string representing a number possibly followed by a binary prefix. 189 * 190 * The string can contain a trailing "B" (KB,MB,GB) but it's not necessary. 191 * "128K" = 128 * 1024; "2G" = 2 * 1024 * 1024; "2GB" = 2 * 1024 * 1024; 192 * Additionally, lowercase "k", "m", "g" are parsed as well. They are processed 193 * the same as their uppercase equivalents. 194 * 195 * \param cap_str Null terminated string. 196 * \param cap Pointer where the parsed capacity (in bytes) will be put. 197 * \param has_prefix Pointer to a flag that will be set to describe whether given 198 * string contains a binary prefix (optional). 199 * 200 * \return 0 on success, or negative errno on failure. 201 */ 202 int spdk_parse_capacity(const char *cap_str, uint64_t *cap, bool *has_prefix); 203 204 /** 205 * Check if a buffer is all zero (0x00) bytes or not. 206 * 207 * \param data Buffer to check. 208 * \param size Size of data in bytes. 209 * 210 * \return true if data consists entirely of zeroes, or false if any byte in data 211 * is not zero. 212 */ 213 bool spdk_mem_all_zero(const void *data, size_t size); 214 215 /** 216 * Convert the string in nptr to a long integer value according to the given base. 217 * 218 * spdk_strtol() does the additional error checking and allows only strings that 219 * contains only numbers and is positive number or zero. The caller only has to check 220 * if the return value is not negative. 221 * 222 * \param nptr String containing numbers. 223 * \param base Base which must be between 2 and 32 inclusive, or be the special value 0. 224 * 225 * \return positive number or zero on success, or negative errno on failure. 226 */ 227 long int spdk_strtol(const char *nptr, int base); 228 229 /** 230 * Convert the string in nptr to a long long integer value according to the given base. 231 * 232 * spdk_strtoll() does the additional error checking and allows only strings that 233 * contains only numbers and is positive number or zero. The caller only has to check 234 * if the return value is not negative. 235 * 236 * \param nptr String containing numbers. 237 * \param base Base which must be between 2 and 32 inclusive, or be the special value 0. 238 * 239 * \return positive number or zero on success, or negative errno on failure. 240 */ 241 long long int spdk_strtoll(const char *nptr, int base); 242 243 /** 244 * Build a NULL-terminated array of strings from the given string separated by 245 * the given chars in delim, as if split by strpbrk(). Empty items are pointers 246 * to an empty string. 247 * 248 * \param str Input string 249 * \param delim Separating delimiter set. 250 * 251 * \return the string array, or NULL on failure. 252 */ 253 char **spdk_strarray_from_string(const char *str, const char *delim); 254 255 /** 256 * Duplicate a NULL-terminated array of strings. Returns NULL on failure. 257 * The array, and the strings, are allocated with the standard allocator (e.g. 258 * calloc()). 259 * 260 * \param strarray input array of strings. 261 */ 262 char **spdk_strarray_dup(const char **strarray); 263 264 /** 265 * Free a NULL-terminated array of strings. The array and its strings must have 266 * been allocated with the standard allocator (calloc() etc.). 267 * 268 * \param strarray array of strings. 269 */ 270 void spdk_strarray_free(char **strarray); 271 272 /** 273 * Copy a string into a fixed-size buffer with all occurrences of the search string 274 * replaced with the given replace substring. The fixed-size buffer must not be less 275 * than the string with the replaced values including the terminating null byte. 276 * 277 * \param dst Pointer to destination fixed-size buffer to fill. 278 * \param size Size of the destination fixed-size buffer in bytes. 279 * \param src Pointer to source null-terminated string to copy into dst. 280 * \param search The string being searched for. 281 * \param replace the replacement substring the replaces the found search substring. 282 * 283 * \return 0 on success, or negated errno on failure. 284 */ 285 int spdk_strcpy_replace(char *dst, size_t size, const char *src, const char *search, 286 const char *replace); 287 288 #ifdef __cplusplus 289 } 290 #endif 291 292 #endif 293