00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2006, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief String manipulation functions 00021 */ 00022 00023 #ifndef _ASTERISK_STRINGS_H 00024 #define _ASTERISK_STRINGS_H 00025 00026 /* #define DEBUG_OPAQUE */ 00027 00028 #include <ctype.h> 00029 00030 #include "asterisk/utils.h" 00031 #include "asterisk/threadstorage.h" 00032 00033 #if defined(DEBUG_OPAQUE) 00034 #define __AST_STR_USED used2 00035 #define __AST_STR_LEN len2 00036 #define __AST_STR_STR str2 00037 #define __AST_STR_TS ts2 00038 #else 00039 #define __AST_STR_USED used 00040 #define __AST_STR_LEN len 00041 #define __AST_STR_STR str 00042 #define __AST_STR_TS ts 00043 #endif 00044 00045 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */ 00046 00047 #define AS_OR(a,b) (a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b) 00048 00049 #ifdef AST_DEVMODE 00050 #define ast_strlen_zero(foo) _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__) 00051 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line) 00052 { 00053 if (!s || (*s == '\0')) { 00054 return 1; 00055 } 00056 if (!strcmp(s, "(null)")) { 00057 ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n"); 00058 } 00059 return 0; 00060 } 00061 00062 #else 00063 static force_inline int attribute_pure ast_strlen_zero(const char *s) 00064 { 00065 return (!s || (*s == '\0')); 00066 } 00067 #endif 00068 00069 #ifdef SENSE_OF_HUMOR 00070 #define ast_strlen_real(a) (a) ? strlen(a) : 0 00071 #define ast_strlen_imaginary(a) ast_random() 00072 #endif 00073 00074 /*! \brief returns the equivalent of logic or for strings: 00075 * first one if not empty, otherwise second one. 00076 */ 00077 #define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;}) 00078 00079 /*! \brief returns the equivalent of logic or for strings, with an additional boolean check: 00080 * second one if not empty and first one is true, otherwise third one. 00081 * example: S_COR(usewidget, widget, "<no widget>") 00082 */ 00083 #define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);}) 00084 00085 /*! 00086 \brief Gets a pointer to the first non-whitespace character in a string. 00087 \param str the input string 00088 \return a pointer to the first non-whitespace character 00089 */ 00090 AST_INLINE_API( 00091 char * attribute_pure ast_skip_blanks(const char *str), 00092 { 00093 while (*str && ((unsigned char) *str) < 33) 00094 str++; 00095 return (char *) str; 00096 } 00097 ) 00098 00099 /*! 00100 \brief Trims trailing whitespace characters from a string. 00101 \param str the input string 00102 \return a pointer to the modified string 00103 */ 00104 AST_INLINE_API( 00105 char *ast_trim_blanks(char *str), 00106 { 00107 char *work = str; 00108 00109 if (work) { 00110 work += strlen(work) - 1; 00111 /* It's tempting to only want to erase after we exit this loop, 00112 but since ast_trim_blanks *could* receive a constant string 00113 (which we presumably wouldn't have to touch), we shouldn't 00114 actually set anything unless we must, and it's easier just 00115 to set each position to \0 than to keep track of a variable 00116 for it */ 00117 while ((work >= str) && ((unsigned char) *work) < 33) 00118 *(work--) = '\0'; 00119 } 00120 return str; 00121 } 00122 ) 00123 00124 /*! 00125 \brief Gets a pointer to first whitespace character in a string. 00126 \param str the input string 00127 \return a pointer to the first whitespace character 00128 */ 00129 AST_INLINE_API( 00130 char * attribute_pure ast_skip_nonblanks(const char *str), 00131 { 00132 while (*str && ((unsigned char) *str) > 32) 00133 str++; 00134 return (char *) str; 00135 } 00136 ) 00137 00138 /*! 00139 \brief Strip leading/trailing whitespace from a string. 00140 \param s The string to be stripped (will be modified). 00141 \return The stripped string. 00142 00143 This functions strips all leading and trailing whitespace 00144 characters from the input string, and returns a pointer to 00145 the resulting string. The string is modified in place. 00146 */ 00147 AST_INLINE_API( 00148 char *ast_strip(char *s), 00149 { 00150 if ((s = ast_skip_blanks(s))) { 00151 ast_trim_blanks(s); 00152 } 00153 return s; 00154 } 00155 ) 00156 00157 /*! 00158 \brief Strip leading/trailing whitespace and quotes from a string. 00159 \param s The string to be stripped (will be modified). 00160 \param beg_quotes The list of possible beginning quote characters. 00161 \param end_quotes The list of matching ending quote characters. 00162 \return The stripped string. 00163 00164 This functions strips all leading and trailing whitespace 00165 characters from the input string, and returns a pointer to 00166 the resulting string. The string is modified in place. 00167 00168 It can also remove beginning and ending quote (or quote-like) 00169 characters, in matching pairs. If the first character of the 00170 string matches any character in beg_quotes, and the last 00171 character of the string is the matching character in 00172 end_quotes, then they are removed from the string. 00173 00174 Examples: 00175 \code 00176 ast_strip_quoted(buf, "\"", "\""); 00177 ast_strip_quoted(buf, "'", "'"); 00178 ast_strip_quoted(buf, "[{(", "]})"); 00179 \endcode 00180 */ 00181 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes); 00182 00183 /*! 00184 \brief Strip backslash for "escaped" semicolons, 00185 the string to be stripped (will be modified). 00186 \return The stripped string. 00187 */ 00188 char *ast_unescape_semicolon(char *s); 00189 00190 /*! 00191 \brief Convert some C escape sequences \verbatim (\b\f\n\r\t) \endverbatim into the 00192 equivalent characters. The string to be converted (will be modified). 00193 \return The converted string. 00194 */ 00195 char *ast_unescape_c(char *s); 00196 00197 /*! 00198 \brief Size-limited null-terminating string copy. 00199 \param dst The destination buffer. 00200 \param src The source string 00201 \param size The size of the destination buffer 00202 \return Nothing. 00203 00204 This is similar to \a strncpy, with two important differences: 00205 - the destination buffer will \b always be null-terminated 00206 - the destination buffer is not filled with zeros past the copied string length 00207 These differences make it slightly more efficient, and safer to use since it will 00208 not leave the destination buffer unterminated. There is no need to pass an artificially 00209 reduced buffer size to this function (unlike \a strncpy), and the buffer does not need 00210 to be initialized to zeroes prior to calling this function. 00211 */ 00212 AST_INLINE_API( 00213 void ast_copy_string(char *dst, const char *src, size_t size), 00214 { 00215 while (*src && size) { 00216 *dst++ = *src++; 00217 size--; 00218 } 00219 if (__builtin_expect(!size, 0)) 00220 dst--; 00221 *dst = '\0'; 00222 } 00223 ) 00224 00225 /*! 00226 \brief Build a string in a buffer, designed to be called repeatedly 00227 00228 \note This method is not recommended. New code should use ast_str_*() instead. 00229 00230 This is a wrapper for snprintf, that properly handles the buffer pointer 00231 and buffer space available. 00232 00233 \param buffer current position in buffer to place string into (will be updated on return) 00234 \param space remaining space in buffer (will be updated on return) 00235 \param fmt printf-style format string 00236 \retval 0 on success 00237 \retval non-zero on failure. 00238 */ 00239 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4))); 00240 00241 /*! 00242 \brief Build a string in a buffer, designed to be called repeatedly 00243 00244 This is a wrapper for snprintf, that properly handles the buffer pointer 00245 and buffer space available. 00246 00247 \return 0 on success, non-zero on failure. 00248 \param buffer current position in buffer to place string into (will be updated on return) 00249 \param space remaining space in buffer (will be updated on return) 00250 \param fmt printf-style format string 00251 \param ap varargs list of arguments for format 00252 */ 00253 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0))); 00254 00255 /*! 00256 * \brief Make sure something is true. 00257 * Determine if a string containing a boolean value is "true". 00258 * This function checks to see whether a string passed to it is an indication of an "true" value. 00259 * It checks to see if the string is "yes", "true", "y", "t", "on" or "1". 00260 * 00261 * \retval 0 if val is a NULL pointer. 00262 * \retval -1 if "true". 00263 * \retval 0 otherwise. 00264 */ 00265 int attribute_pure ast_true(const char *val); 00266 00267 /*! 00268 * \brief Make sure something is false. 00269 * Determine if a string containing a boolean value is "false". 00270 * This function checks to see whether a string passed to it is an indication of an "false" value. 00271 * It checks to see if the string is "no", "false", "n", "f", "off" or "0". 00272 * 00273 * \retval 0 if val is a NULL pointer. 00274 * \retval -1 if "true". 00275 * \retval 0 otherwise. 00276 */ 00277 int attribute_pure ast_false(const char *val); 00278 00279 /* 00280 * \brief Join an array of strings into a single string. 00281 * \param s the resulting string buffer 00282 * \param len the length of the result buffer, s 00283 * \param w an array of strings to join. 00284 * 00285 * This function will join all of the strings in the array 'w' into a single 00286 * string. It will also place a space in the result buffer in between each 00287 * string from 'w'. 00288 */ 00289 void ast_join(char *s, size_t len, const char * const w[]); 00290 00291 /* 00292 \brief Parse a time (integer) string. 00293 \param src String to parse 00294 \param dst Destination 00295 \param _default Value to use if the string does not contain a valid time 00296 \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details) 00297 \retval 0 on success 00298 \retval non-zero on failure. 00299 */ 00300 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed); 00301 00302 /* 00303 \brief Parse a time (float) string. 00304 \param src String to parse 00305 \param dst Destination 00306 \param _default Value to use if the string does not contain a valid time 00307 \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details) 00308 \return zero on success, non-zero on failure 00309 */ 00310 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed); 00311 00312 /*! 00313 * Support for dynamic strings. 00314 * 00315 * A dynamic string is just a C string prefixed by a few control fields 00316 * that help setting/appending/extending it using a printf-like syntax. 00317 * 00318 * One should never declare a variable with this type, but only a pointer 00319 * to it, e.g. 00320 * 00321 * struct ast_str *ds; 00322 * 00323 * The pointer can be initialized with the following: 00324 * 00325 * ds = ast_str_create(init_len); 00326 * creates a malloc()'ed dynamic string; 00327 * 00328 * ds = ast_str_alloca(init_len); 00329 * creates a string on the stack (not very dynamic!). 00330 * 00331 * ds = ast_str_thread_get(ts, init_len) 00332 * creates a malloc()'ed dynamic string associated to 00333 * the thread-local storage key ts 00334 * 00335 * Finally, the string can be manipulated with the following: 00336 * 00337 * ast_str_set(&buf, max_len, fmt, ...) 00338 * ast_str_append(&buf, max_len, fmt, ...) 00339 * 00340 * and their varargs variant 00341 * 00342 * ast_str_set_va(&buf, max_len, ap) 00343 * ast_str_append_va(&buf, max_len, ap) 00344 * 00345 * \param max_len The maximum allowed capacity of the ast_str. Note that 00346 * if the value of max_len is less than the current capacity of the 00347 * ast_str (as returned by ast_str_size), then the parameter is effectively 00348 * ignored. 00349 * 0 means unlimited, -1 means "at most the available space" 00350 * 00351 * \return All the functions return <0 in case of error, or the 00352 * length of the string added to the buffer otherwise. Note that 00353 * in most cases where an error is returned, characters ARE written 00354 * to the ast_str. 00355 */ 00356 00357 /*! \brief The descriptor of a dynamic string 00358 * XXX storage will be optimized later if needed 00359 * We use the ts field to indicate the type of storage. 00360 * Three special constants indicate malloc, ast_alloca() or static 00361 * variables, all other values indicate a 00362 * struct ast_threadstorage pointer. 00363 */ 00364 struct ast_str { 00365 size_t __AST_STR_LEN; /*!< The current maximum length of the string */ 00366 size_t __AST_STR_USED; /*!< Amount of space used */ 00367 struct ast_threadstorage *__AST_STR_TS; /*!< What kind of storage is this ? */ 00368 #define DS_MALLOC ((struct ast_threadstorage *)1) 00369 #define DS_ALLOCA ((struct ast_threadstorage *)2) 00370 #define DS_STATIC ((struct ast_threadstorage *)3) /* not supported yet */ 00371 char __AST_STR_STR[0]; /*!< The string buffer */ 00372 }; 00373 00374 /*! 00375 * \brief Create a malloc'ed dynamic length string 00376 * 00377 * \param init_len This is the initial length of the string buffer 00378 * 00379 * \return This function returns a pointer to the dynamic string length. The 00380 * result will be NULL in the case of a memory allocation error. 00381 * 00382 * \note The result of this function is dynamically allocated memory, and must 00383 * be free()'d after it is no longer needed. 00384 */ 00385 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE)) 00386 #define ast_str_create(a) _ast_str_create(a,__FILE__,__LINE__,__PRETTY_FUNCTION__) 00387 AST_INLINE_API( 00388 struct ast_str * attribute_malloc _ast_str_create(size_t init_len, 00389 const char *file, int lineno, const char *func), 00390 { 00391 struct ast_str *buf; 00392 00393 buf = (struct ast_str *)__ast_calloc(1, sizeof(*buf) + init_len, file, lineno, func); 00394 if (buf == NULL) 00395 return NULL; 00396 00397 buf->__AST_STR_LEN = init_len; 00398 buf->__AST_STR_USED = 0; 00399 buf->__AST_STR_TS = DS_MALLOC; 00400 00401 return buf; 00402 } 00403 ) 00404 #else 00405 AST_INLINE_API( 00406 struct ast_str * attribute_malloc ast_str_create(size_t init_len), 00407 { 00408 struct ast_str *buf; 00409 00410 buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len); 00411 if (buf == NULL) 00412 return NULL; 00413 00414 buf->__AST_STR_LEN = init_len; 00415 buf->__AST_STR_USED = 0; 00416 buf->__AST_STR_TS = DS_MALLOC; 00417 00418 return buf; 00419 } 00420 ) 00421 #endif 00422 00423 /*! \brief Reset the content of a dynamic string. 00424 * Useful before a series of ast_str_append. 00425 */ 00426 AST_INLINE_API( 00427 void ast_str_reset(struct ast_str *buf), 00428 { 00429 if (buf) { 00430 buf->__AST_STR_USED = 0; 00431 if (buf->__AST_STR_LEN) { 00432 buf->__AST_STR_STR[0] = '\0'; 00433 } 00434 } 00435 } 00436 ) 00437 00438 /*! \brief Update the length of the buffer, after using ast_str merely as a buffer. 00439 * \param buf A pointer to the ast_str string. 00440 */ 00441 AST_INLINE_API( 00442 void ast_str_update(struct ast_str *buf), 00443 { 00444 buf->__AST_STR_USED = strlen(buf->__AST_STR_STR); 00445 } 00446 ) 00447 00448 /*! \brief Trims trailing whitespace characters from an ast_str string. 00449 * \param buf A pointer to the ast_str string. 00450 */ 00451 AST_INLINE_API( 00452 void ast_str_trim_blanks(struct ast_str *buf), 00453 { 00454 if (!buf) { 00455 return; 00456 } 00457 while (buf->__AST_STR_USED && buf->__AST_STR_STR[buf->__AST_STR_USED - 1] < 33) { 00458 buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0'; 00459 } 00460 } 00461 ) 00462 00463 /*!\brief Returns the current length of the string stored within buf. 00464 * \param buf A pointer to the ast_str structure. 00465 */ 00466 AST_INLINE_API( 00467 size_t attribute_pure ast_str_strlen(const struct ast_str *buf), 00468 { 00469 return buf->__AST_STR_USED; 00470 } 00471 ) 00472 00473 /*!\brief Returns the current maximum length (without reallocation) of the current buffer. 00474 * \param buf A pointer to the ast_str structure. 00475 * \retval Current maximum length of the buffer. 00476 */ 00477 AST_INLINE_API( 00478 size_t attribute_pure ast_str_size(const struct ast_str *buf), 00479 { 00480 return buf->__AST_STR_LEN; 00481 } 00482 ) 00483 00484 /*!\brief Returns the string buffer within the ast_str buf. 00485 * \param buf A pointer to the ast_str structure. 00486 * \retval A pointer to the enclosed string. 00487 */ 00488 AST_INLINE_API( 00489 char * attribute_pure ast_str_buffer(const struct ast_str *buf), 00490 { 00491 /* for now, cast away the const qualifier on the pointer 00492 * being returned; eventually, it should become truly const 00493 * and only be modified via accessor functions 00494 */ 00495 return (char *) buf->__AST_STR_STR; 00496 } 00497 ) 00498 00499 /*!\brief Truncates the enclosed string to the given length. 00500 * \param buf A pointer to the ast_str structure. 00501 * \param len Maximum length of the string. If len is larger than the 00502 * current maximum length, things will explode. If it is negative 00503 * at most -len characters will be trimmed off the end. 00504 * \retval A pointer to the resulting string. 00505 */ 00506 AST_INLINE_API( 00507 char *ast_str_truncate(struct ast_str *buf, ssize_t len), 00508 { 00509 if (len < 0) { 00510 if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) { 00511 buf->__AST_STR_USED = 0; 00512 } else { 00513 buf->__AST_STR_USED += len; 00514 } 00515 } else { 00516 buf->__AST_STR_USED = len; 00517 } 00518 buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0'; 00519 return buf->__AST_STR_STR; 00520 } 00521 ) 00522 00523 /* 00524 * AST_INLINE_API() is a macro that takes a block of code as an argument. 00525 * Using preprocessor #directives in the argument is not supported by all 00526 * compilers, and it is a bit of an obfuscation anyways, so avoid it. 00527 * As a workaround, define a macro that produces either its argument 00528 * or nothing, and use that instead of #ifdef/#endif within the 00529 * argument to AST_INLINE_API(). 00530 */ 00531 #if defined(DEBUG_THREADLOCALS) 00532 #define _DB1(x) x 00533 #else 00534 #define _DB1(x) 00535 #endif 00536 00537 /*! 00538 * Make space in a new string (e.g. to read in data from a file) 00539 */ 00540 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE)) 00541 AST_INLINE_API( 00542 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function), 00543 { 00544 struct ast_str *old_buf = *buf; 00545 00546 if (new_len <= (*buf)->__AST_STR_LEN) 00547 return 0; /* success */ 00548 if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC) 00549 return -1; /* cannot extend */ 00550 *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function); 00551 if (*buf == NULL) { 00552 *buf = old_buf; 00553 return -1; 00554 } 00555 if ((*buf)->__AST_STR_TS != DS_MALLOC) { 00556 pthread_setspecific((*buf)->__AST_STR_TS->key, *buf); 00557 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));) 00558 } 00559 00560 (*buf)->__AST_STR_LEN = new_len; 00561 return 0; 00562 } 00563 ) 00564 #define ast_str_make_space(a,b) _ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__) 00565 #else 00566 AST_INLINE_API( 00567 int ast_str_make_space(struct ast_str **buf, size_t new_len), 00568 { 00569 struct ast_str *old_buf = *buf; 00570 00571 if (new_len <= (*buf)->__AST_STR_LEN) 00572 return 0; /* success */ 00573 if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC) 00574 return -1; /* cannot extend */ 00575 *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str)); 00576 if (*buf == NULL) { 00577 *buf = old_buf; 00578 return -1; 00579 } 00580 if ((*buf)->__AST_STR_TS != DS_MALLOC) { 00581 pthread_setspecific((*buf)->__AST_STR_TS->key, *buf); 00582 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));) 00583 } 00584 00585 (*buf)->__AST_STR_LEN = new_len; 00586 return 0; 00587 } 00588 ) 00589 #endif 00590 00591 AST_INLINE_API( 00592 int ast_str_copy_string(struct ast_str **dst, struct ast_str *src), 00593 { 00594 00595 /* make sure our destination is large enough */ 00596 if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) { 00597 if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) { 00598 return -1; 00599 } 00600 } 00601 00602 memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1); 00603 (*dst)->__AST_STR_USED = src->__AST_STR_USED; 00604 return 0; 00605 } 00606 ) 00607 00608 #define ast_str_alloca(init_len) \ 00609 ({ \ 00610 struct ast_str *__ast_str_buf; \ 00611 __ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len); \ 00612 __ast_str_buf->__AST_STR_LEN = init_len; \ 00613 __ast_str_buf->__AST_STR_USED = 0; \ 00614 __ast_str_buf->__AST_STR_TS = DS_ALLOCA; \ 00615 __ast_str_buf->__AST_STR_STR[0] = '\0'; \ 00616 (__ast_str_buf); \ 00617 }) 00618 00619 /*! 00620 * \brief Retrieve a thread locally stored dynamic string 00621 * 00622 * \param ts This is a pointer to the thread storage structure declared by using 00623 * the AST_THREADSTORAGE macro. If declared with 00624 * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 00625 * (&my_buf). 00626 * \param init_len This is the initial length of the thread's dynamic string. The 00627 * current length may be bigger if previous operations in this thread have 00628 * caused it to increase. 00629 * 00630 * \return This function will return the thread locally stored dynamic string 00631 * associated with the thread storage management variable passed as the 00632 * first argument. 00633 * The result will be NULL in the case of a memory allocation error. 00634 * 00635 * Example usage: 00636 * \code 00637 * AST_THREADSTORAGE(my_str, my_str_init); 00638 * #define MY_STR_INIT_SIZE 128 00639 * ... 00640 * void my_func(const char *fmt, ...) 00641 * { 00642 * struct ast_str *buf; 00643 * 00644 * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE))) 00645 * return; 00646 * ... 00647 * } 00648 * \endcode 00649 */ 00650 #if !defined(DEBUG_THREADLOCALS) 00651 AST_INLINE_API( 00652 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts, 00653 size_t init_len), 00654 { 00655 struct ast_str *buf; 00656 00657 buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len); 00658 if (buf == NULL) 00659 return NULL; 00660 00661 if (!buf->__AST_STR_LEN) { 00662 buf->__AST_STR_LEN = init_len; 00663 buf->__AST_STR_USED = 0; 00664 buf->__AST_STR_TS = ts; 00665 } 00666 00667 return buf; 00668 } 00669 ) 00670 #else /* defined(DEBUG_THREADLOCALS) */ 00671 AST_INLINE_API( 00672 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts, 00673 size_t init_len, const char *file, const char *function, unsigned int line), 00674 { 00675 struct ast_str *buf; 00676 00677 buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line); 00678 if (buf == NULL) 00679 return NULL; 00680 00681 if (!buf->__AST_STR_LEN) { 00682 buf->__AST_STR_LEN = init_len; 00683 buf->__AST_STR_USED = 0; 00684 buf->__AST_STR_TS = ts; 00685 } 00686 00687 return buf; 00688 } 00689 ) 00690 00691 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__) 00692 #endif /* defined(DEBUG_THREADLOCALS) */ 00693 00694 /*! 00695 * \brief Error codes from __ast_str_helper() 00696 * The undelying processing to manipulate dynamic string is done 00697 * by __ast_str_helper(), which can return a success or a 00698 * permanent failure (e.g. no memory). 00699 */ 00700 enum { 00701 /*! An error has occurred and the contents of the dynamic string 00702 * are undefined */ 00703 AST_DYNSTR_BUILD_FAILED = -1, 00704 /*! The buffer size for the dynamic string had to be increased, and 00705 * __ast_str_helper() needs to be called again after 00706 * a va_end() and va_start(). This return value is legacy and will 00707 * no longer be used. 00708 */ 00709 AST_DYNSTR_BUILD_RETRY = -2 00710 }; 00711 00712 /*! 00713 * \brief Core functionality of ast_str_(set|append)_va 00714 * 00715 * The arguments to this function are the same as those described for 00716 * ast_str_set_va except for an addition argument, append. 00717 * If append is non-zero, this will append to the current string instead of 00718 * writing over it. 00719 * 00720 * AST_DYNSTR_BUILD_RETRY is a legacy define. It should probably never 00721 * again be used. 00722 * 00723 * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error. 00724 * 00725 * A return value greater than or equal to zero indicates the number of 00726 * characters that have been written, not including the terminating '\0'. 00727 * In the append case, this only includes the number of characters appended. 00728 * 00729 * \note This function should never need to be called directly. It should 00730 * through calling one of the other functions or macros defined in this 00731 * file. 00732 */ 00733 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE)) 00734 int __attribute__((format(printf, 4, 0))) __ast_debug_str_helper(struct ast_str **buf, ssize_t max_len, 00735 int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func); 00736 #define __ast_str_helper(a,b,c,d,e) __ast_debug_str_helper(a,b,c,d,e,__FILE__,__LINE__,__PRETTY_FUNCTION__) 00737 #else 00738 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, ssize_t max_len, 00739 int append, const char *fmt, va_list ap); 00740 #endif 00741 char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len, 00742 const char *src, size_t maxsrc, int append, int escapecommas); 00743 00744 /*! 00745 * \brief Set a dynamic string from a va_list 00746 * 00747 * \param buf This is the address of a pointer to a struct ast_str. 00748 * If it is retrieved using ast_str_thread_get, the 00749 struct ast_threadstorage pointer will need to 00750 * be updated in the case that the buffer has to be reallocated to 00751 * accommodate a longer string than what it currently has space for. 00752 * \param max_len This is the maximum length to allow the string buffer to grow 00753 * to. If this is set to 0, then there is no maximum length. 00754 * \param fmt This is the format string (printf style) 00755 * \param ap This is the va_list 00756 * 00757 * \return The return value of this function is the same as that of the printf 00758 * family of functions. 00759 * 00760 * Example usage (the first part is only for thread-local storage) 00761 * \code 00762 * AST_THREADSTORAGE(my_str, my_str_init); 00763 * #define MY_STR_INIT_SIZE 128 00764 * ... 00765 * void my_func(const char *fmt, ...) 00766 * { 00767 * struct ast_str *buf; 00768 * va_list ap; 00769 * 00770 * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE))) 00771 * return; 00772 * ... 00773 * va_start(fmt, ap); 00774 * ast_str_set_va(&buf, 0, fmt, ap); 00775 * va_end(ap); 00776 * 00777 * printf("This is the string we just built: %s\n", buf->str); 00778 * ... 00779 * } 00780 * \endcode 00781 * 00782 * \note Care should be taken when using this function. The function can 00783 * result in reallocating the ast_str. If a pointer to the ast_str is passed 00784 * by value to a function that calls ast_str_set_va(), then the original ast_str 00785 * pointer may be invalidated due to a reallocation. 00786 * 00787 */ 00788 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap), 00789 { 00790 return __ast_str_helper(buf, max_len, 0, fmt, ap); 00791 } 00792 ) 00793 00794 /*! 00795 * \brief Append to a dynamic string using a va_list 00796 * 00797 * Same as ast_str_set_va(), but append to the current content. 00798 * 00799 * \note Care should be taken when using this function. The function can 00800 * result in reallocating the ast_str. If a pointer to the ast_str is passed 00801 * by value to a function that calls ast_str_append_va(), then the original ast_str 00802 * pointer may be invalidated due to a reallocation. 00803 * 00804 */ 00805 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap), 00806 { 00807 return __ast_str_helper(buf, max_len, 1, fmt, ap); 00808 } 00809 ) 00810 00811 /*!\brief Set a dynamic string to a non-NULL terminated substring. */ 00812 AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc), 00813 { 00814 return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0); 00815 } 00816 ) 00817 00818 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */ 00819 AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc), 00820 { 00821 return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0); 00822 } 00823 ) 00824 00825 /*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */ 00826 AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc), 00827 { 00828 return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1); 00829 } 00830 ) 00831 00832 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */ 00833 AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc), 00834 { 00835 return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1); 00836 } 00837 ) 00838 00839 /*! 00840 * \brief Set a dynamic string using variable arguments 00841 * 00842 * \note Care should be taken when using this function. The function can 00843 * result in reallocating the ast_str. If a pointer to the ast_str is passed 00844 * by value to a function that calls ast_str_set(), then the original ast_str 00845 * pointer may be invalidated due to a reallocation. 00846 * 00847 * \param buf This is the address of a pointer to a struct ast_str which should 00848 * have been retrieved using ast_str_thread_get. It will need to 00849 * be updated in the case that the buffer has to be reallocated to 00850 * accomodate a longer string than what it currently has space for. 00851 * \param max_len This is the maximum length to allow the string buffer to grow 00852 * to. If this is set to 0, then there is no maximum length. 00853 * If set to -1, we are bound to the current maximum length. 00854 * \param fmt This is the format string (printf style) 00855 * 00856 * \return The return value of this function is the same as that of the printf 00857 * family of functions. 00858 * 00859 * All the rest is the same as ast_str_set_va() 00860 */ 00861 AST_INLINE_API( 00862 int __attribute__((format(printf, 3, 4))) ast_str_set( 00863 struct ast_str **buf, ssize_t max_len, const char *fmt, ...), 00864 { 00865 int res; 00866 va_list ap; 00867 00868 va_start(ap, fmt); 00869 res = ast_str_set_va(buf, max_len, fmt, ap); 00870 va_end(ap); 00871 00872 return res; 00873 } 00874 ) 00875 00876 /*! 00877 * \brief Append to a thread local dynamic string 00878 * 00879 * \note Care should be taken when using this function. The function can 00880 * result in reallocating the ast_str. If a pointer to the ast_str is passed 00881 * by value to a function that calls ast_str_append(), then the original ast_str 00882 * pointer may be invalidated due to a reallocation. 00883 * 00884 * The arguments, return values, and usage of this function are the same as 00885 * ast_str_set(), but the new data is appended to the current value. 00886 */ 00887 AST_INLINE_API( 00888 int __attribute__((format(printf, 3, 4))) ast_str_append( 00889 struct ast_str **buf, ssize_t max_len, const char *fmt, ...), 00890 { 00891 int res; 00892 va_list ap; 00893 00894 va_start(ap, fmt); 00895 res = ast_str_append_va(buf, max_len, fmt, ap); 00896 va_end(ap); 00897 00898 return res; 00899 } 00900 ) 00901 00902 /*! 00903 * \brief Check if a string is only digits 00904 * 00905 * \retval 1 The string contains only digits 00906 * \retval 0 The string contains non-digit characters 00907 */ 00908 AST_INLINE_API( 00909 int ast_check_digits(const char *arg), 00910 { 00911 while (*arg) { 00912 if (*arg < '0' || *arg > '9') { 00913 return 0; 00914 } 00915 arg++; 00916 } 00917 return 1; 00918 } 00919 ) 00920 00921 /*! 00922 * \brief Convert the tech portion of a device string to upper case 00923 * 00924 * \retval dev_str Returns the char* passed in for convenience 00925 */ 00926 AST_INLINE_API( 00927 char *ast_tech_to_upper(char *dev_str), 00928 { 00929 char *pos; 00930 if (!dev_str || !strchr(dev_str, '/')) { 00931 return dev_str; 00932 } 00933 00934 for (pos = dev_str; *pos && *pos != '/'; pos++) { 00935 *pos = toupper(*pos); 00936 } 00937 return dev_str; 00938 } 00939 ) 00940 00941 /*! 00942 * \brief Compute a hash value on a string 00943 * 00944 * This famous hash algorithm was written by Dan Bernstein and is 00945 * commonly used. 00946 * 00947 * http://www.cse.yorku.ca/~oz/hash.html 00948 */ 00949 static force_inline int attribute_pure ast_str_hash(const char *str) 00950 { 00951 int hash = 5381; 00952 00953 while (*str) 00954 hash = hash * 33 ^ *str++; 00955 00956 return abs(hash); 00957 } 00958 00959 /*! 00960 * \brief Compute a hash value on a string 00961 * 00962 * \param[in] str The string to add to the hash 00963 * \param[in] hash The hash value to add to 00964 * 00965 * \details 00966 * This version of the function is for when you need to compute a 00967 * string hash of more than one string. 00968 * 00969 * This famous hash algorithm was written by Dan Bernstein and is 00970 * commonly used. 00971 * 00972 * \sa http://www.cse.yorku.ca/~oz/hash.html 00973 */ 00974 static force_inline int ast_str_hash_add(const char *str, int hash) 00975 { 00976 while (*str) 00977 hash = hash * 33 ^ *str++; 00978 00979 return abs(hash); 00980 } 00981 00982 /*! 00983 * \brief Compute a hash value on a case-insensitive string 00984 * 00985 * Uses the same hash algorithm as ast_str_hash, but converts 00986 * all characters to lowercase prior to computing a hash. This 00987 * allows for easy case-insensitive lookups in a hash table. 00988 */ 00989 static force_inline int attribute_pure ast_str_case_hash(const char *str) 00990 { 00991 int hash = 5381; 00992 00993 while (*str) { 00994 hash = hash * 33 ^ tolower(*str++); 00995 } 00996 00997 return abs(hash); 00998 } 00999 01000 #endif /* _ASTERISK_STRINGS_H */