]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright (c) Intel Corporation. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | /** \file | |
35 | * String utility functions | |
36 | */ | |
37 | ||
38 | #ifndef SPDK_STRING_H | |
39 | #define SPDK_STRING_H | |
40 | ||
11fdf7f2 TL |
41 | #include "spdk/stdinc.h" |
42 | ||
7c673cae FG |
43 | #ifdef __cplusplus |
44 | extern "C" { | |
45 | #endif | |
46 | ||
7c673cae FG |
47 | /** |
48 | * sprintf with automatic buffer allocation. | |
49 | * | |
11fdf7f2 TL |
50 | * The return value is the formatted string, which should be passed to free() |
51 | * when no longer needed. | |
52 | * | |
53 | * \param format Format for the string to print. | |
54 | * | |
55 | * \return the formatted string on success, or NULL on failure. | |
7c673cae FG |
56 | */ |
57 | char *spdk_sprintf_alloc(const char *format, ...) __attribute__((format(printf, 1, 2))); | |
58 | ||
59 | /** | |
60 | * vsprintf with automatic buffer allocation. | |
61 | * | |
11fdf7f2 TL |
62 | * The return value is the formatted string, which should be passed to free() |
63 | * when no longer needed. | |
64 | * | |
65 | * \param format Format for the string to print. | |
66 | * \param args A value that identifies a variable arguments list. | |
67 | * | |
68 | * \return the formatted string on success, or NULL on failure. | |
7c673cae FG |
69 | */ |
70 | char *spdk_vsprintf_alloc(const char *format, va_list args); | |
71 | ||
9f95a23c TL |
72 | /** |
73 | * Append string using vsprintf with automatic buffer re-allocation. | |
74 | * | |
75 | * The return value is the formatted string, in which the original string in | |
76 | * buffer is unchanged and the specified formatted string is appended. | |
77 | * | |
78 | * The returned string should be passed to free() when no longer needed. | |
79 | * | |
80 | * If buffer is NULL, the call is equivalent to spdk_sprintf_alloc(). | |
81 | * If the call fails, the original buffer is left untouched. | |
82 | * | |
83 | * \param buffer Buffer which has a formatted string. | |
84 | * \param format Format for the string to print. | |
85 | * | |
86 | * \return the formatted string on success, or NULL on failure. | |
87 | */ | |
88 | char *spdk_sprintf_append_realloc(char *buffer, const char *format, ...); | |
89 | ||
90 | /** | |
91 | * Append string using vsprintf with automatic buffer re-allocation. | |
92 | * The return value is the formatted string, in which the original string in | |
93 | * buffer is unchanged and the specified formatted string is appended. | |
94 | * | |
95 | * The returned string should be passed to free() when no longer needed. | |
96 | * | |
97 | * If buffer is NULL, the call is equivalent to spdk_sprintf_alloc(). | |
98 | * If the call fails, the original buffer is left untouched. | |
99 | * | |
100 | * \param buffer Buffer which has a formatted string. | |
101 | * \param format Format for the string to print. | |
102 | * \param args A value that identifies a variable arguments list. | |
103 | * | |
104 | * \return the formatted string on success, or NULL on failure. | |
105 | */ | |
106 | char *spdk_vsprintf_append_realloc(char *buffer, const char *format, va_list args); | |
107 | ||
7c673cae FG |
108 | /** |
109 | * Convert string to lowercase in place. | |
110 | * | |
111 | * \param s String to convert to lowercase. | |
11fdf7f2 TL |
112 | * |
113 | * \return the converted string. | |
7c673cae FG |
114 | */ |
115 | char *spdk_strlwr(char *s); | |
116 | ||
117 | /** | |
118 | * Parse a delimited string with quote handling. | |
119 | * | |
11fdf7f2 TL |
120 | * Note that the string will be modified in place to add the string terminator |
121 | * to each field. | |
7c673cae | 122 | * |
11fdf7f2 TL |
123 | * \param stringp Pointer to starting location in string. *stringp will be updated |
124 | * to point to the start of the next field, or NULL if the end of the string has | |
125 | * been reached. | |
126 | * \param delim Null-terminated string containing the list of accepted delimiters. | |
7c673cae | 127 | * |
11fdf7f2 | 128 | * \return a pointer to beginning of the current field. |
7c673cae FG |
129 | */ |
130 | char *spdk_strsepq(char **stringp, const char *delim); | |
131 | ||
132 | /** | |
133 | * Trim whitespace from a string in place. | |
134 | * | |
135 | * \param s String to trim. | |
11fdf7f2 TL |
136 | * |
137 | * \return the trimmed string. | |
7c673cae FG |
138 | */ |
139 | char *spdk_str_trim(char *s); | |
140 | ||
141 | /** | |
11fdf7f2 TL |
142 | * Copy the string version of an error into the user supplied buffer |
143 | * | |
144 | * \param errnum Error code. | |
145 | * \param buf Pointer to a buffer in which to place the error message. | |
146 | * \param buflen The size of the buffer in bytes. | |
147 | */ | |
148 | void spdk_strerror_r(int errnum, char *buf, size_t buflen); | |
149 | ||
150 | /** | |
151 | * Return the string version of an error from a static, thread-local buffer. This | |
152 | * function is thread safe. | |
153 | * | |
154 | * \param errnum Error code. | |
155 | * | |
156 | * \return a pointer to buffer upon success. | |
157 | */ | |
158 | const char *spdk_strerror(int errnum); | |
159 | ||
160 | /** | |
161 | * Remove trailing newlines from the end of a string in place. | |
162 | * | |
163 | * Any sequence of trailing \\r and \\n characters is removed from the end of the | |
164 | * string. | |
165 | * | |
166 | * \param s String to remove newline from. | |
167 | * | |
168 | * \return the number of characters removed. | |
169 | */ | |
170 | size_t spdk_str_chomp(char *s); | |
171 | ||
172 | /** | |
173 | * Copy a string into a fixed-size buffer, padding extra bytes with a specific | |
174 | * character. | |
175 | * | |
176 | * If src is longer than size, only size bytes will be copied. | |
7c673cae FG |
177 | * |
178 | * \param dst Pointer to destination fixed-size buffer to fill. | |
179 | * \param src Pointer to source null-terminated string to copy into dst. | |
180 | * \param size Number of bytes to fill in dst. | |
181 | * \param pad Character to pad extra space in dst beyond the size of src. | |
7c673cae FG |
182 | */ |
183 | void spdk_strcpy_pad(void *dst, const char *src, size_t size, int pad); | |
184 | ||
185 | /** | |
186 | * Find the length of a string that has been padded with a specific byte. | |
187 | * | |
188 | * \param str Right-padded string to find the length of. | |
189 | * \param size Size of the full string pointed to by str, including padding. | |
190 | * \param pad Character that was used to pad str up to size. | |
191 | * | |
11fdf7f2 | 192 | * \return the length of the non-padded portion of str. |
7c673cae FG |
193 | */ |
194 | size_t spdk_strlen_pad(const void *str, size_t size, int pad); | |
195 | ||
196 | /** | |
11fdf7f2 TL |
197 | * Parse an IP address into its hostname and port components. This modifies the |
198 | * IP address in place. | |
7c673cae | 199 | * |
11fdf7f2 TL |
200 | * \param ip A null terminated IP address, including port. Both IPv4 and IPv6 |
201 | * are supported. | |
202 | * \param host Will point to the start of the hostname within ip. The string will | |
203 | * be null terminated. | |
204 | * \param port Will point to the start of the port within ip. The string will be | |
205 | * null terminated. | |
7c673cae | 206 | * |
11fdf7f2 | 207 | * \return 0 on success. -EINVAL on failure. |
7c673cae FG |
208 | */ |
209 | int spdk_parse_ip_addr(char *ip, char **host, char **port); | |
210 | ||
11fdf7f2 TL |
211 | /** |
212 | * Parse a string representing a number possibly followed by a binary prefix. | |
213 | * | |
214 | * The string can contain a trailing "B" (KB,MB,GB) but it's not necessary. | |
215 | * "128K" = 128 * 1024; "2G" = 2 * 1024 * 1024; "2GB" = 2 * 1024 * 1024; | |
216 | * Additionally, lowercase "k", "m", "g" are parsed as well. They are processed | |
217 | * the same as their uppercase equivalents. | |
218 | * | |
219 | * \param cap_str Null terminated string. | |
220 | * \param cap Pointer where the parsed capacity (in bytes) will be put. | |
221 | * \param has_prefix Pointer to a flag that will be set to describe whether given | |
222 | * string contains a binary prefix. | |
223 | * | |
224 | * \return 0 on success, or negative errno on failure. | |
225 | */ | |
226 | int spdk_parse_capacity(const char *cap_str, uint64_t *cap, bool *has_prefix); | |
227 | ||
228 | /** | |
229 | * Check if a buffer is all zero (0x00) bytes or not. | |
230 | * | |
231 | * \param data Buffer to check. | |
232 | * \param size Size of data in bytes. | |
233 | * | |
234 | * \return true if data consists entirely of zeroes, or false if any byte in data | |
235 | * is not zero. | |
236 | */ | |
237 | bool spdk_mem_all_zero(const void *data, size_t size); | |
238 | ||
9f95a23c TL |
239 | /** |
240 | * Convert the string in nptr to a long integer value according to the given base. | |
241 | * | |
242 | * spdk_strtol() does the additional error checking and allows only strings that | |
243 | * contains only numbers and is positive number or zero. The caller only has to check | |
244 | * if the return value is not negative. | |
245 | * | |
246 | * \param nptr String containing numbers. | |
247 | * \param base Base which must be between 2 and 32 inclusive, or be the special value 0. | |
248 | * | |
249 | * \return positive number or zero on success, or negative errno on failure. | |
250 | */ | |
251 | long int spdk_strtol(const char *nptr, int base); | |
252 | ||
253 | /** | |
254 | * Convert the string in nptr to a long long integer value according to the given base. | |
255 | * | |
256 | * spdk_strtoll() does the additional error checking and allows only strings that | |
257 | * contains only numbers and is positive number or zero. The caller only has to check | |
258 | * if the return value is not negative. | |
259 | * | |
260 | * \param nptr String containing numbers. | |
261 | * \param base Base which must be between 2 and 32 inclusive, or be the special value 0. | |
262 | * | |
263 | * \return positive number or zero on success, or negative errno on failure. | |
264 | */ | |
265 | long long int spdk_strtoll(const char *nptr, int base); | |
266 | ||
7c673cae FG |
267 | #ifdef __cplusplus |
268 | } | |
269 | #endif | |
270 | ||
271 | #endif |