Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


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