Don't pass a negative to an unsigned type and expect things to work correctly.
[asterisk/asterisk.git] / include / asterisk / strings.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief String manipulation functions
21  */
22
23 #ifndef _ASTERISK_STRINGS_H
24 #define _ASTERISK_STRINGS_H
25
26 #define DEBUG_OPAQUE
27
28 #include <ctype.h>
29
30 #include "asterisk/utils.h"
31 #include "asterisk/threadstorage.h"
32
33 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
34
35 #define AS_OR(a,b)      ast_str_strlen(a) ? ast_str_buffer(a) : (b)
36
37 #ifdef AST_DEVMODE
38 #define ast_strlen_zero(foo)    _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
39 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
40 {
41         if (!s || (*s == '\0')) {
42                 return 1;
43         }
44         if (!strcmp(s, "(null)")) {
45                 ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
46         }
47         return 0;
48 }
49
50 #else
51 static force_inline int ast_strlen_zero(const char *s)
52 {
53         return (!s || (*s == '\0'));
54 }
55 #endif
56
57 /*! \brief returns the equivalent of logic or for strings:
58  * first one if not empty, otherwise second one.
59  */
60 #define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
61
62 /*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
63  * second one if not empty and first one is true, otherwise third one.
64  * example: S_COR(usewidget, widget, "<no widget>")
65  */
66 #define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
67
68 /*!
69   \brief Gets a pointer to the first non-whitespace character in a string.
70   \param str the input string
71   \return a pointer to the first non-whitespace character
72  */
73 AST_INLINE_API(
74 char *ast_skip_blanks(const char *str),
75 {
76         while (*str && ((unsigned char) *str) < 33)
77                 str++;
78         return (char *)str;
79 }
80 )
81
82 /*!
83   \brief Trims trailing whitespace characters from a string.
84   \param str the input string
85   \return a pointer to the modified string
86  */
87 AST_INLINE_API(
88 char *ast_trim_blanks(char *str),
89 {
90         char *work = str;
91
92         if (work) {
93                 work += strlen(work) - 1;
94                 /* It's tempting to only want to erase after we exit this loop, 
95                    but since ast_trim_blanks *could* receive a constant string
96                    (which we presumably wouldn't have to touch), we shouldn't
97                    actually set anything unless we must, and it's easier just
98                    to set each position to \0 than to keep track of a variable
99                    for it */
100                 while ((work >= str) && ((unsigned char) *work) < 33)
101                         *(work--) = '\0';
102         }
103         return str;
104 }
105 )
106
107 /*!
108   \brief Gets a pointer to first whitespace character in a string.
109   \param str the input string
110   \return a pointer to the first whitespace character
111  */
112 AST_INLINE_API(
113 char *ast_skip_nonblanks(char *str),
114 {
115         while (*str && ((unsigned char) *str) > 32)
116                 str++;
117         return str;
118 }
119 )
120   
121 /*!
122   \brief Strip leading/trailing whitespace from a string.
123   \param s The string to be stripped (will be modified).
124   \return The stripped string.
125
126   This functions strips all leading and trailing whitespace
127   characters from the input string, and returns a pointer to
128   the resulting string. The string is modified in place.
129 */
130 AST_INLINE_API(
131 char *ast_strip(char *s),
132 {
133         s = ast_skip_blanks(s);
134         if (s)
135                 ast_trim_blanks(s);
136         return s;
137
138 )
139
140 /*!
141   \brief Strip leading/trailing whitespace and quotes from a string.
142   \param s The string to be stripped (will be modified).
143   \param beg_quotes The list of possible beginning quote characters.
144   \param end_quotes The list of matching ending quote characters.
145   \return The stripped string.
146
147   This functions strips all leading and trailing whitespace
148   characters from the input string, and returns a pointer to
149   the resulting string. The string is modified in place.
150
151   It can also remove beginning and ending quote (or quote-like)
152   characters, in matching pairs. If the first character of the
153   string matches any character in beg_quotes, and the last
154   character of the string is the matching character in
155   end_quotes, then they are removed from the string.
156
157   Examples:
158   \code
159   ast_strip_quoted(buf, "\"", "\"");
160   ast_strip_quoted(buf, "'", "'");
161   ast_strip_quoted(buf, "[{(", "]})");
162   \endcode
163  */
164 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
165
166 /*!
167   \brief Strip backslash for "escaped" semicolons, 
168         the string to be stripped (will be modified).
169   \return The stripped string.
170  */
171 char *ast_unescape_semicolon(char *s);
172
173 /*!
174   \brief Convert some C escape sequences  \verbatim (\b\f\n\r\t) \endverbatim into the
175         equivalent characters. The string to be converted (will be modified).
176   \return The converted string.
177  */
178 char *ast_unescape_c(char *s);
179
180 /*!
181   \brief Size-limited null-terminating string copy.
182   \param dst The destination buffer.
183   \param src The source string
184   \param size The size of the destination buffer
185   \return Nothing.
186
187   This is similar to \a strncpy, with two important differences:
188     - the destination buffer will \b always be null-terminated
189     - the destination buffer is not filled with zeros past the copied string length
190   These differences make it slightly more efficient, and safer to use since it will
191   not leave the destination buffer unterminated. There is no need to pass an artificially
192   reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
193   to be initialized to zeroes prior to calling this function.
194 */
195 AST_INLINE_API(
196 void ast_copy_string(char *dst, const char *src, size_t size),
197 {
198         while (*src && size) {
199                 *dst++ = *src++;
200                 size--;
201         }
202         if (__builtin_expect(!size, 0))
203                 dst--;
204         *dst = '\0';
205 }
206 )
207
208 /*!
209   \brief Build a string in a buffer, designed to be called repeatedly
210   
211   \note This method is not recommended. New code should use ast_str_*() instead.
212
213   This is a wrapper for snprintf, that properly handles the buffer pointer
214   and buffer space available.
215
216   \param buffer current position in buffer to place string into (will be updated on return)
217   \param space remaining space in buffer (will be updated on return)
218   \param fmt printf-style format string
219   \retval 0 on success
220   \retval non-zero on failure.
221 */
222 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
223
224 /*!
225   \brief Build a string in a buffer, designed to be called repeatedly
226   
227   This is a wrapper for snprintf, that properly handles the buffer pointer
228   and buffer space available.
229
230   \return 0 on success, non-zero on failure.
231   \param buffer current position in buffer to place string into (will be updated on return)
232   \param space remaining space in buffer (will be updated on return)
233   \param fmt printf-style format string
234   \param ap varargs list of arguments for format
235 */
236 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
237
238 /*! 
239  * \brief Make sure something is true.
240  * Determine if a string containing a boolean value is "true".
241  * This function checks to see whether a string passed to it is an indication of an "true" value.  
242  * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".  
243  *
244  * \retval 0 if val is a NULL pointer.
245  * \retval -1 if "true".
246  * \retval 0 otherwise.
247  */
248 int ast_true(const char *val);
249
250 /*! 
251  * \brief Make sure something is false.
252  * Determine if a string containing a boolean value is "false".
253  * This function checks to see whether a string passed to it is an indication of an "false" value.  
254  * It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
255  *
256  * \retval 0 if val is a NULL pointer.
257  * \retval -1 if "true".
258  * \retval 0 otherwise.
259  */
260 int ast_false(const char *val);
261
262 /*
263  *  \brief Join an array of strings into a single string.
264  * \param s the resulting string buffer
265  * \param len the length of the result buffer, s
266  * \param w an array of strings to join.
267  *
268  * This function will join all of the strings in the array 'w' into a single
269  * string.  It will also place a space in the result buffer in between each
270  * string from 'w'.
271 */
272 void ast_join(char *s, size_t len, char * const w[]);
273
274 /*
275   \brief Parse a time (integer) string.
276   \param src String to parse
277   \param dst Destination
278   \param _default Value to use if the string does not contain a valid time
279   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
280   \retval 0 on success
281   \retval non-zero on failure.
282 */
283 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
284
285 /*
286   \brief Parse a time (float) string.
287   \param src String to parse
288   \param dst Destination
289   \param _default Value to use if the string does not contain a valid time
290   \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
291   \return zero on success, non-zero on failure
292 */
293 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
294
295 /*!
296  * Support for dynamic strings.
297  *
298  * A dynamic string is just a C string prefixed by a few control fields
299  * that help setting/appending/extending it using a printf-like syntax.
300  *
301  * One should never declare a variable with this type, but only a pointer
302  * to it, e.g.
303  *
304  *      struct ast_str *ds;
305  *
306  * The pointer can be initialized with the following:
307  *
308  *      ds = ast_str_create(init_len);
309  *              creates a malloc()'ed dynamic string;
310  *
311  *      ds = ast_str_alloca(init_len);
312  *              creates a string on the stack (not very dynamic!).
313  *
314  *      ds = ast_str_thread_get(ts, init_len)
315  *              creates a malloc()'ed dynamic string associated to
316  *              the thread-local storage key ts
317  *
318  * Finally, the string can be manipulated with the following:
319  *
320  *      ast_str_set(&buf, max_len, fmt, ...)
321  *      ast_str_append(&buf, max_len, fmt, ...)
322  *
323  * and their varargs variant
324  *
325  *      ast_str_set_va(&buf, max_len, ap)
326  *      ast_str_append_va(&buf, max_len, ap)
327  *
328  * \param max_len The maximum allowed length, reallocating if needed.
329  *      0 means unlimited, -1 means "at most the available space"
330  *
331  * \return All the functions return <0 in case of error, or the
332  *      length of the string added to the buffer otherwise.
333  */
334
335 /*! \brief The descriptor of a dynamic string
336  *  XXX storage will be optimized later if needed
337  * We use the ts field to indicate the type of storage.
338  * Three special constants indicate malloc, alloca() or static
339  * variables, all other values indicate a
340  * struct ast_threadstorage pointer.
341  */
342 struct ast_str {
343 #ifdef DEBUG_OPAQUE
344         size_t len2;
345         size_t used2;
346         struct ast_threadstorage *ts2;
347 #else
348         size_t len;     /*!< The current maximum length of the string */
349         size_t used;    /*!< Amount of space used */
350         struct ast_threadstorage *ts;   /*!< What kind of storage is this ? */
351 #endif
352 #define DS_MALLOC       ((struct ast_threadstorage *)1)
353 #define DS_ALLOCA       ((struct ast_threadstorage *)2)
354 #define DS_STATIC       ((struct ast_threadstorage *)3) /* not supported yet */
355 #ifdef DEBUG_OPAQUE
356         char str2[0];
357 #else
358         char str[0];    /*!< The string buffer */
359 #endif
360 };
361
362 /*!
363  * \brief Create a malloc'ed dynamic length string
364  *
365  * \param init_len This is the initial length of the string buffer
366  *
367  * \return This function returns a pointer to the dynamic string length.  The
368  *         result will be NULL in the case of a memory allocation error.
369  *
370  * \note The result of this function is dynamically allocated memory, and must
371  *       be free()'d after it is no longer needed.
372  */
373 AST_INLINE_API(
374 struct ast_str * attribute_malloc ast_str_create(size_t init_len),
375 {
376         struct ast_str *buf;
377
378         buf = (struct ast_str *)ast_calloc(1, sizeof(*buf) + init_len);
379         if (buf == NULL)
380                 return NULL;
381
382 #ifdef DEBUG_OPAQUE
383         buf->len2 = init_len;
384         buf->used2 = 0;
385         buf->ts2 = DS_MALLOC;
386 #else
387         buf->len = init_len;
388         buf->used = 0;
389         buf->ts = DS_MALLOC;
390 #endif
391
392         return buf;
393 }
394 )
395
396 /*! \brief Reset the content of a dynamic string.
397  * Useful before a series of ast_str_append.
398  */
399 AST_INLINE_API(
400 void ast_str_reset(struct ast_str *buf),
401 {
402         if (buf) {
403 #ifdef DEBUG_OPAQUE
404                 buf->used2 = 0;
405                 if (buf->len2)
406                         buf->str2[0] = '\0';
407 #else
408                 buf->used = 0;
409                 if (buf->len)
410                         buf->str[0] = '\0';
411 #endif
412         }
413 }
414 )
415
416 /*! \brief Trims trailing whitespace characters from an ast_str string.
417  *  \param buf A pointer to the ast_str string.
418  */
419 AST_INLINE_API(
420 void ast_str_trim_blanks(struct ast_str *buf),
421 {
422         if (!buf) {
423                 return;
424         }
425 #ifdef DEBUG_OPAQUE
426         while (buf->used2 && buf->str2[buf->used2 - 1] < 33) {
427                 buf->str2[--(buf->used2)] = '\0';
428         }
429 #else
430         while (buf->used && buf->str[buf->used - 1] < 33) {
431                 buf->str[--(buf->used)] = '\0';
432         }
433 #endif
434 }
435 )
436
437 /*!\brief Returns the current length of the string stored within buf.
438  * \param A pointer to the ast_str string.
439  */
440 AST_INLINE_API(
441 size_t ast_str_strlen(struct ast_str *buf),
442 {
443 #ifdef DEBUG_OPAQUE
444         return buf->used2;
445 #else
446         return buf->used;
447 #endif
448 }
449 )
450
451 /*!\brief Returns the current maximum length (without reallocation) of the current buffer.
452  * \param A pointer to the ast_str string.
453  */
454 AST_INLINE_API(
455 size_t ast_str_size(struct ast_str *buf),
456 {
457 #ifdef DEBUG_OPAQUE
458         return buf->len2;
459 #else
460         return buf->len;
461 #endif
462 }
463 )
464
465 /*!\brief Returns the string buffer within the ast_str buf.
466  * \param A pointer to the ast_str string.
467  */
468 AST_INLINE_API(
469 attribute_pure char *ast_str_buffer(struct ast_str *buf),
470 {
471 #ifdef DEBUG_OPAQUE
472         return buf->str2;
473 #else
474         return buf->str;
475 #endif
476 }
477 )
478
479 AST_INLINE_API(
480 char *ast_str_truncate(struct ast_str *buf, ssize_t len),
481 {
482 #ifdef DEBUG_OPAQUE
483         if (len < 0) {
484                 buf->used2 += (ssize_t) abs(len) > buf->used2 ? -buf->used2 : len;
485         } else {
486                 buf->used2 = len;
487         }
488         buf->str2[buf->used2] = '\0';
489         return buf->str2;
490 #else
491         if (len < 0) {
492                 buf->used += (ssize_t) abs(len) > buf->used ? -buf->used : len;
493         } else {
494                 buf->used = len;
495         }
496         buf->str[buf->used] = '\0';
497         return buf->str;
498 #endif
499 }
500 )
501         
502 /*
503  * AST_INLINE_API() is a macro that takes a block of code as an argument.
504  * Using preprocessor #directives in the argument is not supported by all
505  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
506  * As a workaround, define a macro that produces either its argument
507  * or nothing, and use that instead of #ifdef/#endif within the
508  * argument to AST_INLINE_API().
509  */
510 #if defined(DEBUG_THREADLOCALS)
511 #define _DB1(x) x
512 #else
513 #define _DB1(x)
514 #endif
515
516 /*!
517  * Make space in a new string (e.g. to read in data from a file)
518  */
519 #if (defined(MALLOC_DEBUG) && !defined(STANDALONE))
520 AST_INLINE_API(
521 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
522 {
523         struct ast_str *old_buf = *buf;
524
525 #ifdef DEBUG_OPAQUE
526         if (new_len <= (*buf)->len2) 
527                 return 0;       /* success */
528         if ((*buf)->ts2 == DS_ALLOCA || (*buf)->ts2 == DS_STATIC)
529                 return -1;      /* cannot extend */
530         *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
531         if (*buf == NULL) {
532                 *buf = old_buf;
533                 return -1;
534         }
535         if ((*buf)->ts2 != DS_MALLOC) {
536                 pthread_setspecific((*buf)->ts2->key, *buf);
537                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
538         }
539
540         (*buf)->len2 = new_len;
541 #else
542         if (new_len <= (*buf)->len) 
543                 return 0;       /* success */
544         if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
545                 return -1;      /* cannot extend */
546         *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
547         if (*buf == NULL) {
548                 *buf = old_buf;
549                 return -1;
550         }
551         if ((*buf)->ts != DS_MALLOC) {
552                 pthread_setspecific((*buf)->ts->key, *buf);
553                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
554         }
555
556         (*buf)->len = new_len;
557 #endif
558         return 0;
559 }
560 )
561 #define ast_str_make_space(a,b) _ast_str_make_space(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
562 #else
563 AST_INLINE_API(
564 int ast_str_make_space(struct ast_str **buf, size_t new_len),
565 {
566         struct ast_str *old_buf = *buf;
567
568 #ifdef DEBUG_OPAQUE
569         if (new_len <= (*buf)->len2) 
570                 return 0;       /* success */
571         if ((*buf)->ts2 == DS_ALLOCA || (*buf)->ts2 == DS_STATIC)
572                 return -1;      /* cannot extend */
573         *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
574         if (*buf == NULL) {
575                 *buf = old_buf;
576                 return -1;
577         }
578         if ((*buf)->ts2 != DS_MALLOC) {
579                 pthread_setspecific((*buf)->ts2->key, *buf);
580                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
581         }
582
583         (*buf)->len2 = new_len;
584 #else
585         if (new_len <= (*buf)->len) 
586                 return 0;       /* success */
587         if ((*buf)->ts == DS_ALLOCA || (*buf)->ts == DS_STATIC)
588                 return -1;      /* cannot extend */
589         *buf = (struct ast_str *)ast_realloc(*buf, new_len + sizeof(struct ast_str));
590         if (*buf == NULL) {
591                 *buf = old_buf;
592                 return -1;
593         }
594         if ((*buf)->ts != DS_MALLOC) {
595                 pthread_setspecific((*buf)->ts->key, *buf);
596                 _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
597         }
598
599         (*buf)->len = new_len;
600 #endif
601         return 0;
602 }
603 )
604 #endif
605
606 #ifdef DEBUG_OPAQUE
607 #define ast_str_alloca(init_len)                        \
608         ({                                              \
609                 struct ast_str *__ast_str_buf;                  \
610                 __ast_str_buf = alloca(sizeof(*__ast_str_buf) + init_len);      \
611                 __ast_str_buf->len2 = init_len;                 \
612                 __ast_str_buf->used2 = 0;                               \
613                 __ast_str_buf->ts2 = DS_ALLOCA;                 \
614                 __ast_str_buf->str2[0] = '\0';                  \
615                 (__ast_str_buf);                                        \
616         })
617 #else
618 #define ast_str_alloca(init_len)                        \
619         ({                                              \
620                 struct ast_str *__ast_str_buf;                  \
621                 __ast_str_buf = alloca(sizeof(*__ast_str_buf) + init_len);      \
622                 __ast_str_buf->len = init_len;                  \
623                 __ast_str_buf->used = 0;                                \
624                 __ast_str_buf->ts = DS_ALLOCA;                  \
625                 __ast_str_buf->str[0] = '\0';                   \
626                 (__ast_str_buf);                                        \
627         })
628 #endif
629
630 /*!
631  * \brief Retrieve a thread locally stored dynamic string
632  *
633  * \param ts This is a pointer to the thread storage structure declared by using
634  *      the AST_THREADSTORAGE macro.  If declared with 
635  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
636  *      (&my_buf).
637  * \param init_len This is the initial length of the thread's dynamic string. The
638  *      current length may be bigger if previous operations in this thread have
639  *      caused it to increase.
640  *
641  * \return This function will return the thread locally stored dynamic string
642  *         associated with the thread storage management variable passed as the
643  *         first argument.
644  *         The result will be NULL in the case of a memory allocation error.
645  *
646  * Example usage:
647  * \code
648  * AST_THREADSTORAGE(my_str, my_str_init);
649  * #define MY_STR_INIT_SIZE   128
650  * ...
651  * void my_func(const char *fmt, ...)
652  * {
653  *      struct ast_str *buf;
654  *
655  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
656  *           return;
657  *      ...
658  * }
659  * \endcode
660  */
661 #if !defined(DEBUG_THREADLOCALS)
662 AST_INLINE_API(
663 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
664         size_t init_len),
665 {
666         struct ast_str *buf;
667
668         buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
669         if (buf == NULL)
670                 return NULL;
671
672 #ifdef DEBUG_OPAQUE
673         if (!buf->len2) {
674                 buf->len2 = init_len;
675                 buf->used2 = 0;
676                 buf->ts2 = ts;
677         }
678 #else
679         if (!buf->len) {
680                 buf->len = init_len;
681                 buf->used = 0;
682                 buf->ts = ts;
683         }
684 #endif
685
686         return buf;
687 }
688 )
689 #else /* defined(DEBUG_THREADLOCALS) */
690 AST_INLINE_API(
691 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
692         size_t init_len, const char *file, const char *function, unsigned int line),
693 {
694         struct ast_str *buf;
695
696         buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
697         if (buf == NULL)
698                 return NULL;
699
700 #ifdef DEBUG_OPAQUE
701         if (!buf->len2) {
702                 buf->len2 = init_len;
703                 buf->used2 = 0;
704                 buf->ts2 = ts;
705         }
706 #else
707         if (!buf->len) {
708                 buf->len = init_len;
709                 buf->used = 0;
710                 buf->ts = ts;
711         }
712 #endif
713
714         return buf;
715 }
716 )
717
718 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
719 #endif /* defined(DEBUG_THREADLOCALS) */
720
721 /*!
722  * \brief Error codes from __ast_str_helper()
723  * The undelying processing to manipulate dynamic string is done
724  * by __ast_str_helper(), which can return a success or a
725  * permanent failure (e.g. no memory).
726  */
727 enum {
728         /*! An error has occurred and the contents of the dynamic string
729          *  are undefined */
730         AST_DYNSTR_BUILD_FAILED = -1,
731         /*! The buffer size for the dynamic string had to be increased, and
732          *  __ast_str_helper() needs to be called again after
733          *  a va_end() and va_start().  This return value is legacy and will
734          *  no longer be used.
735          */
736         AST_DYNSTR_BUILD_RETRY = -2
737 };
738
739 /*!
740  * \brief Core functionality of ast_str_(set|append)_va
741  *
742  * The arguments to this function are the same as those described for
743  * ast_str_set_va except for an addition argument, append.
744  * If append is non-zero, this will append to the current string instead of
745  * writing over it.
746  *
747  * AST_DYNSTR_BUILD_RETRY is a legacy define.  It should probably never
748  * again be used.
749  *
750  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
751  *
752  * A return value greater than or equal to zero indicates the number of
753  * characters that have been written, not including the terminating '\0'.
754  * In the append case, this only includes the number of characters appended.
755  *
756  * \note This function should never need to be called directly.  It should
757  *       through calling one of the other functions or macros defined in this
758  *       file.
759  */
760 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf, size_t max_len,
761                                                            int append, const char *fmt, va_list ap);
762 char *__ast_str_helper2(struct ast_str **buf, size_t max_len,
763         const char *src, size_t maxsrc, int append, int escapecommas);
764
765 /*!
766  * \brief Set a dynamic string from a va_list
767  *
768  * \param buf This is the address of a pointer to a struct ast_str.
769  *      If it is retrieved using ast_str_thread_get, the
770         struct ast_threadstorage pointer will need to
771  *      be updated in the case that the buffer has to be reallocated to
772  *      accommodate a longer string than what it currently has space for.
773  * \param max_len This is the maximum length to allow the string buffer to grow
774  *      to.  If this is set to 0, then there is no maximum length.
775  * \param fmt This is the format string (printf style)
776  * \param ap This is the va_list
777  *
778  * \return The return value of this function is the same as that of the printf
779  *         family of functions.
780  *
781  * Example usage (the first part is only for thread-local storage)
782  * \code
783  * AST_THREADSTORAGE(my_str, my_str_init);
784  * #define MY_STR_INIT_SIZE   128
785  * ...
786  * void my_func(const char *fmt, ...)
787  * {
788  *      struct ast_str *buf;
789  *      va_list ap;
790  *
791  *      if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
792  *           return;
793  *      ...
794  *      va_start(fmt, ap);
795  *      ast_str_set_va(&buf, 0, fmt, ap);
796  *      va_end(ap);
797  * 
798  *      printf("This is the string we just built: %s\n", buf->str);
799  *      ...
800  * }
801  * \endcode
802  */
803 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct ast_str **buf, size_t max_len, const char *fmt, va_list ap),
804 {
805         return __ast_str_helper(buf, max_len, 0, fmt, ap);
806 }
807 )
808
809 /*!
810  * \brief Append to a dynamic string using a va_list
811  *
812  * Same as ast_str_set_va(), but append to the current content.
813  */
814 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, size_t max_len, const char *fmt, va_list ap),
815 {
816         return __ast_str_helper(buf, max_len, 1, fmt, ap);
817 }
818 )
819
820 /*!\brief Set a dynamic string to a non-NULL terminated substring. */
821 AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, size_t maxlen, const char *src, size_t maxsrc),
822 {
823         return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
824 }
825 )
826
827 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
828 AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, size_t maxlen, const char *src, size_t maxsrc),
829 {
830         return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
831 }
832 )
833
834 /*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
835 AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, size_t maxlen, const char *src, size_t maxsrc),
836 {
837         return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
838 }
839 )
840
841 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
842 AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, size_t maxlen, const char *src, size_t maxsrc),
843 {
844         return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
845 }
846 )
847
848 /*!\brief Wrapper for SQLGetData to use with dynamic strings
849  * \param buf Address of the pointer to the ast_str structure.
850  * \param maxlen The maximum size of the resulting string, or 0 for no limit.
851  * \param StatementHandle The statement handle from which to retrieve data.
852  * \param ColumnNumber Column number (1-based offset) for which to retrieve data.
853  * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
854  * \param StrLen_or_Ind A pointer to a length indicator, specifying the total length of data.
855  */
856 #ifdef USE_ODBC
857 #include <sql.h>
858 #include <sqlext.h>
859 #include <sqltypes.h>
860
861 AST_INLINE_API(SQLRETURN ast_str_SQLGetData(struct ast_str **buf, size_t maxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind),
862 {
863         SQLRETURN res;
864         if (maxlen == 0) {
865 #ifdef DEBUG_OPAQUE
866                 if (SQLGetData(StatementHandle, ColumnNumber, TargetType, (*buf)->str2, 0, StrLen_or_Ind) == SQL_SUCCESS_WITH_INFO) {
867                         ast_str_make_space(buf, *StrLen_or_Ind + 1);
868                 }
869                 maxlen = (*buf)->len2;
870         } else if (maxlen > 0) {
871                 ast_str_make_space(buf, maxlen);
872         }
873         res = SQLGetData(StatementHandle, ColumnNumber, TargetType, (*buf)->str2, maxlen, StrLen_or_Ind);
874         (*buf)->used2 = *StrLen_or_Ind;
875 #else
876                 if (SQLGetData(StatementHandle, ColumnNumber, TargetType, (*buf)->str, 0, StrLen_or_Ind) == SQL_SUCCESS_WITH_INFO) {
877                         ast_str_make_space(buf, *StrLen_or_Ind + 1);
878                 }
879                 maxlen = (*buf)->len;
880         } else if (maxlen > 0) {
881                 ast_str_make_space(buf, maxlen);
882         }
883         res = SQLGetData(StatementHandle, ColumnNumber, TargetType, (*buf)->str, maxlen, StrLen_or_Ind);
884         (*buf)->used = *StrLen_or_Ind;
885 #endif
886         return res;
887 }
888 )
889 #endif /* defined(USE_ODBC) */
890
891
892 /*!
893  * \brief Set a dynamic string using variable arguments
894  *
895  * \param buf This is the address of a pointer to a struct ast_str which should
896  *      have been retrieved using ast_str_thread_get.  It will need to
897  *      be updated in the case that the buffer has to be reallocated to
898  *      accomodate a longer string than what it currently has space for.
899  * \param max_len This is the maximum length to allow the string buffer to grow
900  *      to.  If this is set to 0, then there is no maximum length.
901  *      If set to -1, we are bound to the current maximum length.
902  * \param fmt This is the format string (printf style)
903  *
904  * \return The return value of this function is the same as that of the printf
905  *         family of functions.
906  *
907  * All the rest is the same as ast_str_set_va()
908  */
909 AST_INLINE_API(
910 int __attribute__((format(printf, 3, 4))) ast_str_set(
911         struct ast_str **buf, size_t max_len, const char *fmt, ...),
912 {
913         int res;
914         va_list ap;
915
916         va_start(ap, fmt);
917         res = ast_str_set_va(buf, max_len, fmt, ap);
918         va_end(ap);
919
920         return res;
921 }
922 )
923
924 /*!
925  * \brief Append to a thread local dynamic string
926  *
927  * The arguments, return values, and usage of this function are the same as
928  * ast_str_set(), but the new data is appended to the current value.
929  */
930 AST_INLINE_API(
931 int __attribute__((format(printf, 3, 4))) ast_str_append(
932         struct ast_str **buf, size_t max_len, const char *fmt, ...),
933 {
934         int res;
935         va_list ap;
936
937         va_start(ap, fmt);
938         res = ast_str_append_va(buf, max_len, fmt, ap);
939         va_end(ap);
940
941         return res;
942 }
943 )
944
945 /*!
946  * \brief Compute a hash value on a string
947  *
948  * This famous hash algorithm was written by Dan Bernstein and is
949  * commonly used.
950  *
951  * http://www.cse.yorku.ca/~oz/hash.html
952  */
953 static force_inline int ast_str_hash(const char *str)
954 {
955         int hash = 5381;
956
957         while (*str)
958                 hash = hash * 33 ^ *str++;
959
960         return abs(hash);
961 }
962
963 /*!
964  * \brief Compute a hash value on a case-insensitive string
965  *
966  * Uses the same hash algorithm as ast_str_hash, but converts
967  * all characters to lowercase prior to computing a hash. This
968  * allows for easy case-insensitive lookups in a hash table.
969  */
970 static force_inline int ast_str_case_hash(const char *str)
971 {
972         int hash = 5381;
973
974         while (*str) {
975                 hash = hash * 33 ^ tolower(*str++);
976         }
977
978         return abs(hash);
979 }
980 #endif /* _ASTERISK_STRINGS_H */