Asterisk - The Open Source Telephony Project  18.5.0
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 <[email protected]>
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 #include <limits.h>
30 
31 #include "asterisk/utils.h"
32 #include "asterisk/threadstorage.h"
33 #include "asterisk/astobj2.h"
34 
35 #if defined(DEBUG_OPAQUE)
36 #define __AST_STR_USED used2
37 #define __AST_STR_LEN len2
38 #define __AST_STR_STR str2
39 #define __AST_STR_TS ts2
40 #else
41 #define __AST_STR_USED used
42 #define __AST_STR_LEN len
43 #define __AST_STR_STR str
44 #define __AST_STR_TS ts
45 #endif
46 
47 /* You may see casts in this header that may seem useless but they ensure this file is C++ clean */
48 
49 #define AS_OR(a,b) (a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)
50 
51 #ifdef AST_DEVMODE
52 #define ast_strlen_zero(foo) _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)
53 static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
54 {
55  if (!s || (*s == '\0')) {
56  return 1;
57  }
58  if (!strcmp(s, "(null)")) {
59  ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
60  }
61  return 0;
62 }
63 
64 #else
65 static force_inline int attribute_pure ast_strlen_zero(const char *s)
66 {
67  return (!s || (*s == '\0'));
68 }
69 #endif
70 
71 #ifdef SENSE_OF_HUMOR
72 #define ast_strlen_real(a) (a) ? strlen(a) : 0
73 #define ast_strlen_imaginary(a) ast_random()
74 #endif
75 
76 /*! \brief returns the equivalent of logic or for strings:
77  * first one if not empty, otherwise second one.
78  */
79 #define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
80 
81 /*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
82  * second one if not empty and first one is true, otherwise third one.
83  * example: S_COR(usewidget, widget, "<no widget>")
84  */
85 #define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
86 
87 /*
88  \brief Checks whether a string begins with another.
89  \since 12.0.0
90  \param str String to check.
91  \param prefix Prefix to look for.
92  \param 1 if \a str begins with \a prefix, 0 otherwise.
93  */
94 static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
95 {
96  ast_assert(str != NULL);
97  ast_assert(prefix != NULL);
98  while (*str == *prefix && *prefix != '\0') {
99  ++str;
100  ++prefix;
101  }
102  return *prefix == '\0';
103 }
104 
105 /*
106  \brief Checks whether a string ends with another.
107  \since 12.0.0
108  \param str String to check.
109  \param suffix Suffix to look for.
110  \param 1 if \a str ends with \a suffix, 0 otherwise.
111  */
112 static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
113 {
114  size_t str_len;
115  size_t suffix_len;
116 
117  ast_assert(str != NULL);
118  ast_assert(suffix != NULL);
119  str_len = strlen(str);
120  suffix_len = strlen(suffix);
121 
122  if (suffix_len > str_len) {
123  return 0;
124  }
125 
126  return strcmp(str + str_len - suffix_len, suffix) == 0;
127 }
128 
129 /*!
130  * \brief return Yes or No depending on the argument.
131  *
132  * Note that this macro is used my AMI, where a literal "Yes" and "No" are
133  * expected, and translations would cause problems.
134  *
135  * \param x Boolean value
136  * \return "Yes" if x is true (non-zero)
137  * \return "No" if x is false (zero)
138  */
139 #define AST_YESNO(x) ((x) ? "Yes" : "No")
140 
141 /*!
142  \brief Gets a pointer to the first non-whitespace character in a string.
143  \param str the input string
144  \return a pointer to the first non-whitespace character
145  */
147 char * attribute_pure ast_skip_blanks(const char *str),
148 {
149  if (str) {
150  while (*str && ((unsigned char) *str) < 33) {
151  str++;
152  }
153  }
154 
155  return (char *) str;
156 }
157 )
158 
159 /*!
160  \brief Trims trailing whitespace characters from a string.
161  \param str the input string
162  \return a pointer to the modified string
163  */
165 char *ast_trim_blanks(char *str),
166 {
167  char *work = str;
168 
169  if (work) {
170  work += strlen(work) - 1;
171  /* It's tempting to only want to erase after we exit this loop,
172  but since ast_trim_blanks *could* receive a constant string
173  (which we presumably wouldn't have to touch), we shouldn't
174  actually set anything unless we must, and it's easier just
175  to set each position to \0 than to keep track of a variable
176  for it */
177  while ((work >= str) && ((unsigned char) *work) < 33)
178  *(work--) = '\0';
179  }
180  return str;
181 }
182 )
183 
184 /*!
185  \brief Gets a pointer to first whitespace character in a string.
186  \param str the input string
187  \return a pointer to the first whitespace character
188  */
190 char * attribute_pure ast_skip_nonblanks(const char *str),
191 {
192  if (str) {
193  while (*str && ((unsigned char) *str) > 32) {
194  str++;
195  }
196  }
197 
198  return (char *) str;
199 }
200 )
201 
202 /*!
203  \brief Strip leading/trailing whitespace from a string.
204  \param s The string to be stripped (will be modified).
205  \return The stripped string.
206 
207  This functions strips all leading and trailing whitespace
208  characters from the input string, and returns a pointer to
209  the resulting string. The string is modified in place.
210 */
212 char *ast_strip(char *s),
213 {
214  if ((s = ast_skip_blanks(s))) {
215  ast_trim_blanks(s);
216  }
217  return s;
218 }
219 )
220 
221 /*!
222  \brief Strip leading/trailing whitespace and quotes from a string.
223  \param s The string to be stripped (will be modified).
224  \param beg_quotes The list of possible beginning quote characters.
225  \param end_quotes The list of matching ending quote characters.
226  \return The stripped string.
227 
228  This functions strips all leading and trailing whitespace
229  characters from the input string, and returns a pointer to
230  the resulting string. The string is modified in place.
231 
232  It can also remove beginning and ending quote (or quote-like)
233  characters, in matching pairs. If the first character of the
234  string matches any character in beg_quotes, and the last
235  character of the string is the matching character in
236  end_quotes, then they are removed from the string.
237 
238  Examples:
239  \code
240  ast_strip_quoted(buf, "\"", "\"");
241  ast_strip_quoted(buf, "'", "'");
242  ast_strip_quoted(buf, "[{(", "]})");
243  \endcode
244  */
245 char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
246 
247 /*!
248  \brief Flags for ast_strsep
249  */
251  AST_STRSEP_STRIP = 0x01, /*!< Trim, then strip quotes. You may want to trim again */
252  AST_STRSEP_TRIM = 0x02, /*!< Trim leading and trailing whitespace */
253  AST_STRSEP_UNESCAPE = 0x04, /*!< Unescape '\' */
254  AST_STRSEP_ALL = 0x07, /*!< Trim, strip, unescape */
255 };
256 
257 /*!
258  \brief Act like strsep but ignore separators inside quotes.
259  \param s Pointer to address of the string to be processed.
260  Will be modified and can't be constant.
261  \param sep A single character delimiter.
262  \param flags Controls post-processing of the result.
263  AST_STRSEP_TRIM trims all leading and trailing whitespace from the result.
264  AST_STRSEP_STRIP does a trim then strips the outermost quotes. You may want
265  to trim again after the strip. Just OR both the TRIM and STRIP flags.
266  AST_STRSEP_UNESCAPE unescapes '\' sequences.
267  AST_STRSEP_ALL does all of the above processing.
268  \return The next token or NULL if done or if there are more than 8 levels of
269  nested quotes.
270 
271  This function acts like strsep with three exceptions...
272  The separator is a single character instead of a string.
273  Separators inside quotes are treated literally instead of like separators.
274  You can elect to have leading and trailing whitespace and quotes
275  stripped from the result and have '\' sequences unescaped.
276 
277  Like strsep, ast_strsep maintains no internal state and you can call it
278  recursively using different separators on the same storage.
279 
280  Also like strsep, for consistent results, consecutive separators are not
281  collapsed so you may get an empty string as a valid result.
282 
283  Examples:
284  \code
285  char *mystr = ast_strdupa("abc=def,ghi='zzz=yyy,456',jkl");
286  char *token, *token2, *token3;
287 
288  while((token = ast_strsep(&mystr, ',', AST_SEP_STRIP))) {
289  // 1st token will be aaa=def
290  // 2nd token will be ghi='zzz=yyy,456'
291  while((token2 = ast_strsep(&token, '=', AST_SEP_STRIP))) {
292  // 1st token2 will be ghi
293  // 2nd token2 will be zzz=yyy,456
294  while((token3 = ast_strsep(&token2, ',', AST_SEP_STRIP))) {
295  // 1st token3 will be zzz=yyy
296  // 2nd token3 will be 456
297  // and so on
298  }
299  }
300  // 3rd token will be jkl
301  }
302 
303  \endcode
304  */
305 char *ast_strsep(char **s, const char sep, uint32_t flags);
306 
307 /*!
308  \brief Strip backslash for "escaped" semicolons,
309  the string to be stripped (will be modified).
310  \return The stripped string.
311  */
312 char *ast_unescape_semicolon(char *s);
313 
314 /*!
315  \brief Convert some C escape sequences \verbatim (\b\f\n\r\t) \endverbatim into the
316  equivalent characters. The string to be converted (will be modified).
317  \return The converted string.
318  */
319 char *ast_unescape_c(char *s);
320 
321 /*!
322  * \brief Escape the 'to_escape' characters in the given string.
323  *
324  * \note The given output buffer will contain a truncated escaped
325  * version of the source string if the given buffer is not large
326  * enough.
327  *
328  * \param dest the escaped string
329  * \param s the source string to escape
330  * \param size The size of the destination buffer
331  * \param to_escape an array of characters to escape
332  *
333  * \return Pointer to the destination.
334  */
335 char *ast_escape(char *dest, const char *s, size_t size, const char *to_escape);
336 
337 /*!
338  * \brief Escape standard 'C' sequences in the given string.
339  *
340  * \note The given output buffer will contain a truncated escaped
341  * version of the source string if the given buffer is not large
342  * enough.
343  *
344  * \param dest the escaped string
345  * \param s the source string to escape
346  * \param size The size of the destination buffer
347  *
348  * \return Pointer to the escaped string.
349  */
350 char *ast_escape_c(char *dest, const char *s, size_t size);
351 
352 /*!
353  * \brief Escape the 'to_escape' characters in the given string.
354  *
355  * \note Caller is responsible for freeing the returned string
356  *
357  * \param s the source string to escape
358  * \param to_escape an array of characters to escape
359  *
360  * \return Pointer to the escaped string or NULL.
361  */
362 char *ast_escape_alloc(const char *s, const char *to_escape);
363 
364 /*!
365  * \brief Escape standard 'C' sequences in the given string.
366  *
367  * \note Caller is responsible for freeing the returned string
368  *
369  * \param s the source string to escape
370  *
371  * \return Pointer to the escaped string or NULL.
372  */
373 char *ast_escape_c_alloc(const char *s);
374 
375 /*!
376  \brief Size-limited null-terminating string copy.
377  \param dst The destination buffer.
378  \param src The source string
379  \param size The size of the destination buffer
380  \return Nothing.
381 
382  This is similar to \a strncpy, with two important differences:
383  - the destination buffer will \b always be null-terminated
384  - the destination buffer is not filled with zeros past the copied string length
385  These differences make it slightly more efficient, and safer to use since it will
386  not leave the destination buffer unterminated. There is no need to pass an artificially
387  reduced buffer size to this function (unlike \a strncpy), and the buffer does not need
388  to be initialized to zeroes prior to calling this function.
389 */
391 void ast_copy_string(char *dst, const char *src, size_t size),
392 {
393  while (*src && size) {
394  *dst++ = *src++;
395  size--;
396  }
397  if (__builtin_expect(!size, 0))
398  dst--;
399  *dst = '\0';
400 }
401 )
402 
403 /*!
404  \brief Build a string in a buffer, designed to be called repeatedly
405 
406  \note This method is not recommended. New code should use ast_str_*() instead.
407 
408  This is a wrapper for snprintf, that properly handles the buffer pointer
409  and buffer space available.
410 
411  \param buffer current position in buffer to place string into (will be updated on return)
412  \param space remaining space in buffer (will be updated on return)
413  \param fmt printf-style format string
414  \retval 0 on success
415  \retval non-zero on failure.
416 */
417 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
418 
419 /*!
420  \brief Build a string in a buffer, designed to be called repeatedly
421 
422  This is a wrapper for snprintf, that properly handles the buffer pointer
423  and buffer space available.
424 
425  \return 0 on success, non-zero on failure.
426  \param buffer current position in buffer to place string into (will be updated on return)
427  \param space remaining space in buffer (will be updated on return)
428  \param fmt printf-style format string
429  \param ap varargs list of arguments for format
430 */
431 int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap) __attribute__((format(printf, 3, 0)));
432 
433 /*!
434  * \brief Make sure something is true.
435  * Determine if a string containing a boolean value is "true".
436  * This function checks to see whether a string passed to it is an indication of an "true" value.
437  * It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
438  *
439  * \retval 0 if val is a NULL pointer.
440  * \retval -1 if "true".
441  * \retval 0 otherwise.
442  */
443 int attribute_pure ast_true(const char *val);
444 
445 /*!
446  * \brief Make sure something is false.
447  * Determine if a string containing a boolean value is "false".
448  * This function checks to see whether a string passed to it is an indication of an "false" value.
449  * It checks to see if the string is "no", "false", "n", "f", "off" or "0".
450  *
451  * \retval 0 if val is a NULL pointer.
452  * \retval -1 if "true".
453  * \retval 0 otherwise.
454  */
455 int attribute_pure ast_false(const char *val);
456 
457 /*
458  * \brief Join an array of strings into a single string.
459  * \param s the resulting string buffer
460  * \param len the length of the result buffer, s
461  * \param w an array of strings to join.
462  * \param size the number of elements to join
463  * \param delim delimiter between elements
464  *
465  * This function will join all of the strings in the array 'w' into a single
466  * string. It will also place 'delim' in the result buffer in between each
467  * string from 'w'.
468  * \since 12
469 */
470 void ast_join_delim(char *s, size_t len, const char * const w[],
471  unsigned int size, char delim);
472 
473 /*
474  * \brief Join an array of strings into a single string.
475  * \param s the resulting string buffer
476  * \param len the length of the result buffer, s
477  * \param w an array of strings to join.
478  *
479  * This function will join all of the strings in the array 'w' into a single
480  * string. It will also place a space in the result buffer in between each
481  * string from 'w'.
482 */
483 #define ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')
484 
485 /*
486  * \brief Attempts to convert the given string to camel case using
487  * the specified delimiter.
488  *
489  * note - returned string needs to be freed
490  *
491  * \param s the string to convert
492  * \param delim delimiter to parse out
493  *
494  * \retval The string converted to "CamelCase"
495  * \since 12
496 */
497 char *ast_to_camel_case_delim(const char *s, const char *delim);
498 
499 /*
500  * \brief Attempts to convert the given string to camel case using
501  * an underscore as the specified delimiter.
502  *
503  * note - returned string needs to be freed
504  *
505  * \param s the string to convert
506  *
507  * \retval The string converted to "CamelCase"
508 */
509 #define ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")
510 
511 /*
512  \brief Parse a time (integer) string.
513  \param src String to parse
514  \param dst Destination
515  \param _default Value to use if the string does not contain a valid time
516  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
517  \retval 0 on success
518  \retval non-zero on failure.
519 */
520 int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
521 
522 /*
523  \brief Parse a time (float) string.
524  \param src String to parse
525  \param dst Destination
526  \param _default Value to use if the string does not contain a valid time
527  \param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
528  \return zero on success, non-zero on failure
529 */
530 int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
531 
532 /*!
533  * Support for dynamic strings.
534  *
535  * A dynamic string is just a C string prefixed by a few control fields
536  * that help setting/appending/extending it using a printf-like syntax.
537  *
538  * One should never declare a variable with this type, but only a pointer
539  * to it, e.g.
540  *
541  * struct ast_str *ds;
542  *
543  * The pointer can be initialized with the following:
544  *
545  * ds = ast_str_create(init_len);
546  * creates a malloc()'ed dynamic string;
547  *
548  * ds = ast_str_alloca(init_len);
549  * creates a string on the stack (not very dynamic!).
550  *
551  * ds = ast_str_thread_get(ts, init_len)
552  * creates a malloc()'ed dynamic string associated to
553  * the thread-local storage key ts
554  *
555  * Finally, the string can be manipulated with the following:
556  *
557  * ast_str_set(&buf, max_len, fmt, ...)
558  * ast_str_append(&buf, max_len, fmt, ...)
559  *
560  * and their varargs variant
561  *
562  * ast_str_set_va(&buf, max_len, ap)
563  * ast_str_append_va(&buf, max_len, ap)
564  *
565  * \param max_len The maximum allowed capacity of the ast_str. Note that
566  * if the value of max_len is less than the current capacity of the
567  * ast_str (as returned by ast_str_size), then the parameter is effectively
568  * ignored.
569  * 0 means unlimited, -1 means "at most the available space"
570  *
571  * \return All the functions return <0 in case of error, or the
572  * length of the string added to the buffer otherwise. Note that
573  * in most cases where an error is returned, characters ARE written
574  * to the ast_str.
575  */
576 
577 /*! \brief The descriptor of a dynamic string
578  * XXX storage will be optimized later if needed
579  * We use the ts field to indicate the type of storage.
580  * Three special constants indicate malloc, ast_alloca() or static
581  * variables, all other values indicate a
582  * struct ast_threadstorage pointer.
583  */
584 struct ast_str {
585  size_t __AST_STR_LEN; /*!< The current maximum length of the string */
586  size_t __AST_STR_USED; /*!< Amount of space used */
587  struct ast_threadstorage *__AST_STR_TS; /*!< What kind of storage is this ? */
588 #define DS_MALLOC ((struct ast_threadstorage *)1)
589 #define DS_ALLOCA ((struct ast_threadstorage *)2)
590 #define DS_STATIC ((struct ast_threadstorage *)3) /* not supported yet */
591  char __AST_STR_STR[0]; /*!< The string buffer */
592 };
593 
594 /*!
595  * \brief Given a string regex_string in the form of "/regex/", convert it into the form of "regex"
596  *
597  * This function will trim one leading / and one trailing / from a given input string
598  * ast_str regex_pattern must be preallocated before calling this function
599  *
600  * \return 0 on success, non-zero on failure.
601  * \return 1 if we only stripped a leading /
602  * \return 2 if we only stripped a trailing /
603  * \return 3 if we did not strip any / characters
604  * \param regex_string the string containing /regex/
605  * \param regex_pattern the destination ast_str which will contain "regex" after execution
606  */
607 int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern);
608 
609 /*!
610  * \brief Create a malloc'ed dynamic length string
611  *
612  * \param init_len This is the initial length of the string buffer
613  *
614  * \return This function returns a pointer to the dynamic string length. The
615  * result will be NULL in the case of a memory allocation error.
616  *
617  * \note The result of this function is dynamically allocated memory, and must
618  * be free()'d after it is no longer needed.
619  */
620 #define ast_str_create(init_len) \
621  _ast_str_create(init_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)
623 struct ast_str * attribute_malloc _ast_str_create(size_t init_len,
624  const char *file, int lineno, const char *func),
625 {
626  struct ast_str *buf;
627 
628  buf = (struct ast_str *)__ast_calloc(1, sizeof(*buf) + init_len, file, lineno, func);
629  if (buf == NULL)
630  return NULL;
631 
632  buf->__AST_STR_LEN = init_len;
633  buf->__AST_STR_USED = 0;
634  buf->__AST_STR_TS = DS_MALLOC;
635 
636  return buf;
637 }
638 )
639 
640 /*! \brief Reset the content of a dynamic string.
641  * Useful before a series of ast_str_append.
642  */
644 void ast_str_reset(struct ast_str *buf),
645 {
646  if (buf) {
647  buf->__AST_STR_USED = 0;
648  if (buf->__AST_STR_LEN) {
649  buf->__AST_STR_STR[0] = '\0';
650  }
651  }
652 }
653 )
654 
655 /*! \brief Update the length of the buffer, after using ast_str merely as a buffer.
656  * \param buf A pointer to the ast_str string.
657  */
659 void ast_str_update(struct ast_str *buf),
660 {
661  buf->__AST_STR_USED = strlen(buf->__AST_STR_STR);
662 }
663 )
664 
665 /*! \brief Trims trailing whitespace characters from an ast_str string.
666  * \param buf A pointer to the ast_str string.
667  */
669 void ast_str_trim_blanks(struct ast_str *buf),
670 {
671  if (!buf) {
672  return;
673  }
674  while (buf->__AST_STR_USED && ((unsigned char) buf->__AST_STR_STR[buf->__AST_STR_USED - 1]) < 33) {
675  buf->__AST_STR_STR[--(buf->__AST_STR_USED)] = '\0';
676  }
677 }
678 )
679 
680 /*!\brief Returns the current length of the string stored within buf.
681  * \param buf A pointer to the ast_str structure.
682  */
684 size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
685 {
686  return buf->__AST_STR_USED;
687 }
688 )
689 
690 /*!\brief Returns the current maximum length (without reallocation) of the current buffer.
691  * \param buf A pointer to the ast_str structure.
692  * \retval Current maximum length of the buffer.
693  */
695 size_t attribute_pure ast_str_size(const struct ast_str *buf),
696 {
697  return buf->__AST_STR_LEN;
698 }
699 )
700 
701 /*!\brief Returns the string buffer within the ast_str buf.
702  * \param buf A pointer to the ast_str structure.
703  * \retval A pointer to the enclosed string.
704  */
706 char * attribute_pure ast_str_buffer(const struct ast_str *buf),
707 {
708  /* for now, cast away the const qualifier on the pointer
709  * being returned; eventually, it should become truly const
710  * and only be modified via accessor functions
711  */
712  return (char *) buf->__AST_STR_STR;
713 }
714 )
715 
716 /*!\brief Truncates the enclosed string to the given length.
717  * \param buf A pointer to the ast_str structure.
718  * \param len Maximum length of the string. If len is larger than the
719  * current maximum length, things will explode. If it is negative
720  * at most -len characters will be trimmed off the end.
721  * \retval A pointer to the resulting string.
722  */
724 char *ast_str_truncate(struct ast_str *buf, ssize_t len),
725 {
726  if (len < 0) {
727  if ((typeof(buf->__AST_STR_USED)) -len >= buf->__AST_STR_USED) {
728  buf->__AST_STR_USED = 0;
729  } else {
730  buf->__AST_STR_USED += len;
731  }
732  } else {
733  buf->__AST_STR_USED = len;
734  }
735  buf->__AST_STR_STR[buf->__AST_STR_USED] = '\0';
736  return buf->__AST_STR_STR;
737 }
738 )
739 
740 /*
741  * AST_INLINE_API() is a macro that takes a block of code as an argument.
742  * Using preprocessor #directives in the argument is not supported by all
743  * compilers, and it is a bit of an obfuscation anyways, so avoid it.
744  * As a workaround, define a macro that produces either its argument
745  * or nothing, and use that instead of #ifdef/#endif within the
746  * argument to AST_INLINE_API().
747  */
748 #if defined(DEBUG_THREADLOCALS)
749 #define _DB1(x) x
750 #else
751 #define _DB1(x)
752 #endif
753 
754 /*!
755  * Make space in a new string (e.g. to read in data from a file)
756  */
758 int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function),
759 {
760  struct ast_str *old_buf = *buf;
761 
762  if (new_len <= (*buf)->__AST_STR_LEN)
763  return 0; /* success */
764  if ((*buf)->__AST_STR_TS == DS_ALLOCA || (*buf)->__AST_STR_TS == DS_STATIC)
765  return -1; /* cannot extend */
766  *buf = (struct ast_str *)__ast_realloc(*buf, new_len + sizeof(struct ast_str), file, lineno, function);
767  if (*buf == NULL) {
768  *buf = old_buf;
769  return -1;
770  }
771  if ((*buf)->__AST_STR_TS != DS_MALLOC) {
772  pthread_setspecific((*buf)->__AST_STR_TS->key, *buf);
773  _DB1(__ast_threadstorage_object_replace(old_buf, *buf, new_len + sizeof(struct ast_str));)
774  }
775 
776  (*buf)->__AST_STR_LEN = new_len;
777  return 0;
778 }
779 )
780 #define ast_str_make_space(buf, new_len) \
781  _ast_str_make_space(buf, new_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)
782 
784 int ast_str_copy_string(struct ast_str **dst, struct ast_str *src),
785 {
786 
787  /* make sure our destination is large enough */
788  if (src->__AST_STR_USED + 1 > (*dst)->__AST_STR_LEN) {
789  if (ast_str_make_space(dst, src->__AST_STR_USED + 1)) {
790  return -1;
791  }
792  }
793 
794  memcpy((*dst)->__AST_STR_STR, src->__AST_STR_STR, src->__AST_STR_USED + 1);
795  (*dst)->__AST_STR_USED = src->__AST_STR_USED;
796  return 0;
797 }
798 )
799 
800 #define ast_str_alloca(init_len) \
801  ({ \
802  struct ast_str *__ast_str_buf; \
803  __ast_str_buf = ast_alloca(sizeof(*__ast_str_buf) + init_len); \
804  __ast_str_buf->__AST_STR_LEN = init_len; \
805  __ast_str_buf->__AST_STR_USED = 0; \
806  __ast_str_buf->__AST_STR_TS = DS_ALLOCA; \
807  __ast_str_buf->__AST_STR_STR[0] = '\0'; \
808  (__ast_str_buf); \
809  })
810 
811 /*!
812  * \brief Retrieve a thread locally stored dynamic string
813  *
814  * \param ts This is a pointer to the thread storage structure declared by using
815  * the AST_THREADSTORAGE macro. If declared with
816  * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
817  * (&my_buf).
818  * \param init_len This is the initial length of the thread's dynamic string. The
819  * current length may be bigger if previous operations in this thread have
820  * caused it to increase.
821  *
822  * \return This function will return the thread locally stored dynamic string
823  * associated with the thread storage management variable passed as the
824  * first argument.
825  * The result will be NULL in the case of a memory allocation error.
826  *
827  * Example usage:
828  * \code
829  * AST_THREADSTORAGE(my_str, my_str_init);
830  * #define MY_STR_INIT_SIZE 128
831  * ...
832  * void my_func(const char *fmt, ...)
833  * {
834  * struct ast_str *buf;
835  *
836  * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
837  * return;
838  * ...
839  * }
840  * \endcode
841  */
842 #if !defined(DEBUG_THREADLOCALS)
844 struct ast_str *ast_str_thread_get(struct ast_threadstorage *ts,
845  size_t init_len),
846 {
847  struct ast_str *buf;
848 
849  buf = (struct ast_str *)ast_threadstorage_get(ts, sizeof(*buf) + init_len);
850  if (buf == NULL)
851  return NULL;
852 
853  if (!buf->__AST_STR_LEN) {
854  buf->__AST_STR_LEN = init_len;
855  buf->__AST_STR_USED = 0;
856  buf->__AST_STR_TS = ts;
857  }
858 
859  return buf;
860 }
861 )
862 #else /* defined(DEBUG_THREADLOCALS) */
864 struct ast_str *__ast_str_thread_get(struct ast_threadstorage *ts,
865  size_t init_len, const char *file, const char *function, unsigned int line),
866 {
867  struct ast_str *buf;
868 
869  buf = (struct ast_str *)__ast_threadstorage_get(ts, sizeof(*buf) + init_len, file, function, line);
870  if (buf == NULL)
871  return NULL;
872 
873  if (!buf->__AST_STR_LEN) {
874  buf->__AST_STR_LEN = init_len;
875  buf->__AST_STR_USED = 0;
876  buf->__AST_STR_TS = ts;
877  }
878 
879  return buf;
880 }
881 )
882 
883 #define ast_str_thread_get(ts, init_len) __ast_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
884 #endif /* defined(DEBUG_THREADLOCALS) */
885 
886 /*!
887  * \brief Error codes from __ast_str_helper()
888  * The undelying processing to manipulate dynamic string is done
889  * by __ast_str_helper(), which can return a success or a
890  * permanent failure (e.g. no memory).
891  */
892 enum {
893  /*! An error has occurred and the contents of the dynamic string
894  * are undefined */
896  /*! The buffer size for the dynamic string had to be increased, and
897  * __ast_str_helper() needs to be called again after
898  * a va_end() and va_start(). This return value is legacy and will
899  * no longer be used.
900  */
902 };
903 
904 /*!
905  * \brief Core functionality of ast_str_(set|append)_va
906  *
907  * The arguments to this function are the same as those described for
908  * ast_str_set_va except for an addition argument, append.
909  * If append is non-zero, this will append to the current string instead of
910  * writing over it.
911  *
912  * AST_DYNSTR_BUILD_RETRY is a legacy define. It should probably never
913  * again be used.
914  *
915  * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
916  *
917  * A return value greater than or equal to zero indicates the number of
918  * characters that have been written, not including the terminating '\0'.
919  * In the append case, this only includes the number of characters appended.
920  *
921  * \note This function should never need to be called directly. It should
922  * through calling one of the other functions or macros defined in this
923  * file.
924  */
925 int __attribute__((format(printf, 4, 0))) __ast_str_helper(struct ast_str **buf,
926  ssize_t max_len, int append, const char *fmt, va_list ap,
927  const char *file, int lineno, const char *func);
928 #define _ast_str_helper(buf, max_len, append, fmt, ap) \
929  __ast_str_helper(buf, max_len, append, fmt, ap, __FILE__, __LINE__, __PRETTY_FUNCTION__)
930 
931 char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
932  const char *src, size_t maxsrc, int append, int escapecommas);
933 
934 /*!
935  * \brief Set a dynamic string from a va_list
936  *
937  * \param buf This is the address of a pointer to a struct ast_str.
938  * If it is retrieved using ast_str_thread_get, the
939  struct ast_threadstorage pointer will need to
940  * be updated in the case that the buffer has to be reallocated to
941  * accommodate a longer string than what it currently has space for.
942  * \param max_len This is the maximum length to allow the string buffer to grow
943  * to. If this is set to 0, then there is no maximum length.
944  * \param fmt This is the format string (printf style)
945  * \param ap This is the va_list
946  *
947  * \return The return value of this function is the same as that of the printf
948  * family of functions.
949  *
950  * Example usage (the first part is only for thread-local storage)
951  * \code
952  * AST_THREADSTORAGE(my_str, my_str_init);
953  * #define MY_STR_INIT_SIZE 128
954  * ...
955  * void my_func(const char *fmt, ...)
956  * {
957  * struct ast_str *buf;
958  * va_list ap;
959  *
960  * if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
961  * return;
962  * ...
963  * va_start(fmt, ap);
964  * ast_str_set_va(&buf, 0, fmt, ap);
965  * va_end(ap);
966  *
967  * printf("This is the string we just built: %s\n", buf->str);
968  * ...
969  * }
970  * \endcode
971  *
972  * \note Care should be taken when using this function. The function can
973  * result in reallocating the ast_str. If a pointer to the ast_str is passed
974  * by value to a function that calls ast_str_set_va(), then the original ast_str
975  * pointer may be invalidated due to a reallocation.
976  *
977  */
978 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),
979 {
980  return _ast_str_helper(buf, max_len, 0, fmt, ap);
981 }
982 )
983 
984 /*!
985  * \brief Append to a dynamic string using a va_list
986  *
987  * Same as ast_str_set_va(), but append to the current content.
988  *
989  * \note Care should be taken when using this function. The function can
990  * result in reallocating the ast_str. If a pointer to the ast_str is passed
991  * by value to a function that calls ast_str_append_va(), then the original ast_str
992  * pointer may be invalidated due to a reallocation.
993  *
994  * \param buf, max_len, fmt, ap
995  */
996 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),
997 {
998  return _ast_str_helper(buf, max_len, 1, fmt, ap);
999 }
1001 
1002 /*!\brief Set a dynamic string to a non-NULL terminated substring. */
1003 AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1004 {
1005  return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
1006 }
1008 
1009 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
1010 AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1011 {
1012  return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
1013 }
1015 
1016 /*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
1017 AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1018 {
1019  return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
1020 }
1022 
1023 /*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
1024 AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
1025 {
1026  return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
1027 }
1029 
1030 /*!
1031  * \brief Set a dynamic string using variable arguments
1032  *
1033  * \note Care should be taken when using this function. The function can
1034  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1035  * by value to a function that calls ast_str_set(), then the original ast_str
1036  * pointer may be invalidated due to a reallocation.
1037  *
1038  * \param buf This is the address of a pointer to a struct ast_str which should
1039  * have been retrieved using ast_str_thread_get. It will need to
1040  * be updated in the case that the buffer has to be reallocated to
1041  * accomodate a longer string than what it currently has space for.
1042  * \param max_len This is the maximum length to allow the string buffer to grow
1043  * to. If this is set to 0, then there is no maximum length.
1044  * If set to -1, we are bound to the current maximum length.
1045  * \param fmt This is the format string (printf style)
1046  *
1047  * \return The return value of this function is the same as that of the printf
1048  * family of functions.
1049  *
1050  * All the rest is the same as ast_str_set_va()
1051  */
1053 int __attribute__((format(printf, 3, 4))) ast_str_set(
1054  struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1055 {
1056  int res;
1057  va_list ap;
1058 
1059  va_start(ap, fmt);
1060  res = ast_str_set_va(buf, max_len, fmt, ap);
1061  va_end(ap);
1062 
1063  return res;
1064 }
1066 
1067 /*!
1068  * \brief Append to a thread local dynamic string
1069  *
1070  * \note Care should be taken when using this function. The function can
1071  * result in reallocating the ast_str. If a pointer to the ast_str is passed
1072  * by value to a function that calls ast_str_append(), then the original ast_str
1073  * pointer may be invalidated due to a reallocation.
1074  *
1075  * The arguments, return values, and usage of this function are the same as
1076  * ast_str_set(), but the new data is appended to the current value.
1077  */
1079 int __attribute__((format(printf, 3, 4))) ast_str_append(
1080  struct ast_str **buf, ssize_t max_len, const char *fmt, ...),
1081 {
1082  int res;
1083  va_list ap;
1084 
1085  va_start(ap, fmt);
1086  res = ast_str_append_va(buf, max_len, fmt, ap);
1087  va_end(ap);
1088 
1089  return res;
1090 }
1092 
1093 /*!
1094  * \brief Provides a temporary ast_str and returns a copy of its buffer
1095  * \since 16.12
1096  * \since 17.6
1097  * \since 18.0
1098  *
1099  * \param init_len The initial length of the temporary ast_str needed.
1100  * \param __expr An expression that needs the temporary ast_str and returns a char *.
1101  *
1102  * \returns A copy of __expr's return buffer allocated on the stack.
1103  *
1104  * \details
1105  * There are a few query functions scattered around that need an ast_str in which
1106  * to assemble the results but it's not always convenient to create an ast_str
1107  * and ensure it's freed just to print a log message. For example...
1108  *
1109  * struct ast_str *temp = ast_str_create(128);
1110  * ast_log(LOG_INFO, "Format caps: %s\n", ast_format_cap_get_names(caps, &temp));
1111  * ast_free(temp);
1112  *
1113  * That's not bad if you only have to do it once but some of our code that deals
1114  * with streams and codecs is pretty complex and good instrumentation is essential.
1115  * The aim of this function is to make that easier.
1116  *
1117  * With this macro, the above code can be simplified as follows...
1118  * \example
1119  * ast_log(LOG_INFO, "Format caps: %s\n",
1120  * ast_str_tmp(128, ast_format_cap_get_names(caps, &STR_TMP));
1121  *
1122  * STR_TMP will always be a reference to the temporary ast_str created
1123  * by the macro. Its scope is limited by the macro so you can use it multiple
1124  * times without conflict.
1125  *
1126  * \example
1127  * ast_log(LOG_INFO, "Format caps in: %s Format caps out: %s\n",
1128  * ast_str_tmp(128, ast_format_cap_get_names(caps_in, &STR_TMP),
1129  * ast_str_tmp(128, ast_format_cap_get_names(caps_out, &STR_TMP)
1130  * );
1131  *
1132  * \warning
1133  * The returned string is stack allocated so don't go overboard.
1134  *
1135  */
1136 #define ast_str_tmp(init_len, __expr) \
1137 ({ \
1138  struct ast_str *STR_TMP = ast_str_create(init_len); \
1139  char *ret = ast_strdupa(__expr); \
1140  ast_free(STR_TMP); \
1141  ret; \
1142 })
1143 
1144 
1145 
1146 /*!
1147  * \brief Check if a string is only digits
1148  *
1149  * \retval 1 The string contains only digits
1150  * \retval 0 The string contains non-digit characters
1151  */
1153 int ast_check_digits(const char *arg),
1154 {
1155  while (*arg) {
1156  if (*arg < '0' || *arg > '9') {
1157  return 0;
1158  }
1159  arg++;
1160  }
1161  return 1;
1162 }
1164 
1165 /*!
1166  * \brief Convert the tech portion of a device string to upper case
1167  *
1168  * \retval dev_str Returns the char* passed in for convenience
1169  */
1171 char *ast_tech_to_upper(char *dev_str),
1172 {
1173  char *pos;
1174  if (!dev_str || !strchr(dev_str, '/')) {
1175  return dev_str;
1176  }
1177 
1178  for (pos = dev_str; *pos && *pos != '/'; pos++) {
1179  *pos = toupper(*pos);
1180  }
1181  return dev_str;
1182 }
1184 
1185 /*!
1186  * \brief Restrict hash value range
1187  *
1188  * \details
1189  * Hash values used all over asterisk are expected to be non-negative
1190  * (signed) int values. This function restricts an unsigned int hash
1191  * value to the positive half of the (signed) int values.
1192  */
1194 {
1195  return (int) (hash & (unsigned int) INT_MAX);
1196 }
1197 
1198 /*!
1199  * \brief Compute a hash value on a string
1200  *
1201  * This famous hash algorithm was written by Dan Bernstein and is
1202  * commonly used.
1203  *
1204  * http://www.cse.yorku.ca/~oz/hash.html
1205  */
1206 static force_inline int attribute_pure ast_str_hash(const char *str)
1207 {
1208  unsigned int hash = 5381;
1209 
1210  while (*str) {
1211  hash = hash * 33 ^ (unsigned char) *str++;
1212  }
1213 
1214  return ast_str_hash_restrict(hash);
1215 }
1216 
1217 /*!
1218  * \brief Compute a hash value on a string
1219  *
1220  * \param[in] str The string to add to the hash
1221  * \param[in] seed The hash value to start with
1222  *
1223  * \details
1224  * This version of the function is for when you need to compute a
1225  * string hash of more than one string.
1226  *
1227  * This famous hash algorithm was written by Dan Bernstein and is
1228  * commonly used.
1229  *
1230  * \sa http://www.cse.yorku.ca/~oz/hash.html
1231  */
1232 static force_inline int ast_str_hash_add(const char *str, int seed)
1233 {
1234  unsigned int hash = (unsigned int) seed;
1235 
1236  while (*str) {
1237  hash = hash * 33 ^ (unsigned char) *str++;
1238  }
1239 
1240  return ast_str_hash_restrict(hash);
1241 }
1242 
1243 /*!
1244  * \brief Compute a hash value on a case-insensitive string
1245  *
1246  * Uses the same hash algorithm as ast_str_hash, but converts
1247  * all characters to lowercase prior to computing a hash. This
1248  * allows for easy case-insensitive lookups in a hash table.
1249  */
1250 static force_inline int attribute_pure ast_str_case_hash(const char *str)
1251 {
1252  unsigned int hash = 5381;
1253 
1254  while (*str) {
1255  hash = hash * 33 ^ (unsigned char) tolower(*str++);
1256  }
1257 
1258  return ast_str_hash_restrict(hash);
1259 }
1260 
1261 /*!
1262  * \brief Convert a string to all lower-case
1263  *
1264  * \param str The string to be converted to lower case
1265  *
1266  * \retval str for convenience
1267  */
1268 static force_inline char *ast_str_to_lower(char *str)
1269 {
1270  char *str_orig = str;
1271  if (!str) {
1272  return str;
1273  }
1274 
1275  for (; *str; ++str) {
1276  *str = tolower(*str);
1277  }
1278 
1279  return str_orig;
1280 }
1281 
1282 /*!
1283  * \brief Convert a string to all upper-case
1284  *
1285  * \param str The string to be converted to upper case
1286  *
1287  * \retval str for convenience
1288  */
1289 static force_inline char *ast_str_to_upper(char *str)
1290 {
1291  char *str_orig = str;
1292  if (!str) {
1293  return str;
1294  }
1295 
1296  for (; *str; ++str) {
1297  *str = toupper(*str);
1298  }
1299 
1300  return str_orig;
1301 }
1302 
1303 /*!
1304  * \since 12
1305  * \brief Allocates a hash container for bare strings
1306  *
1307  * \param buckets The number of buckets to use for the hash container
1308  *
1309  * \retval AO2 container for strings
1310  * \retval NULL if allocation failed
1311  */
1312 #define ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
1313 
1314 /*!
1315  * \since 12
1316  * \brief Allocates a hash container for bare strings
1317  *
1318  * \param opts Options to be provided to the container
1319  * \param buckets The number of buckets to use for the hash container
1320  *
1321  * \retval AO2 container for strings
1322  * \retval NULL if allocation failed
1323  */
1324 //struct ao2_container *ast_str_container_alloc_options(enum ao2_container_opts opts, int buckets);
1325 struct ao2_container *ast_str_container_alloc_options(enum ao2_alloc_opts opts, int buckets);
1326 
1327 /*!
1328  * \since 12
1329  * \brief Adds a string to a string container allocated by ast_str_container_alloc
1330  *
1331  * \param str_container The container to which to add a string
1332  * \param add The string to add to the container
1333  *
1334  * \retval zero on success
1335  * \retval non-zero if the operation failed
1336  */
1337 int ast_str_container_add(struct ao2_container *str_container, const char *add);
1338 
1339 /*!
1340  * \since 12
1341  * \brief Removes a string from a string container allocated by ast_str_container_alloc
1342  *
1343  * \param str_container The container from which to remove a string
1344  * \param remove The string to remove from the container
1345  */
1346 void ast_str_container_remove(struct ao2_container *str_container, const char *remove);
1347 
1348 /*!
1349  * \brief Create a pseudo-random string of a fixed length.
1350  *
1351  * This function is useful for generating a string whose randomness
1352  * does not need to be across all time and space, does not need to
1353  * be cryptographically secure, and needs to fit in a limited space.
1354  *
1355  * This function will write a null byte at the final position
1356  * in the buffer (buf[size - 1]). So if you pass in a size of
1357  * 10, then this will generate a random 9-character string.
1358  *
1359  * \param buf Buffer to write random string into.
1360  * \param size The size of the buffer.
1361  * \return A pointer to buf
1362  */
1363 char *ast_generate_random_string(char *buf, size_t size);
1364 
1365 /*!
1366  * \brief Compare strings for equality checking for NULL.
1367  * \since 16.3.0
1368  *
1369  * This function considers NULL values as non-strings, thus a false condition.
1370  * This means that it will return false if one, or both of the given values are
1371  * NULL (i.e. two NULLs are not equal strings).
1372  *
1373  * \param str1 The string to compare to str2
1374  * \param str2 The string to compare to str1
1375  *
1376  * \return true if valid strings and equal, false otherwise.
1377  */
1378 int ast_strings_equal(const char *str1, const char *str2);
1379 
1380 /*!
1381  * \brief Compares 2 strings using realtime-style operators
1382  * \since 13.9.0
1383  *
1384  * \param left The left side of the equation
1385  * \param op The operator to apply
1386  * \param right The right side of the equation
1387  *
1388  * \retval 1 matches
1389  * \retval 0 doesn't match
1390  *
1391  * \details
1392  *
1393  * Operators:
1394  * "=", "!=", "<", "<=", ">", ">=":
1395  * If both left and right can be converted to float, then they will be
1396  * compared as such. Otherwise the result will be derived from strcmp(left, right).
1397  * "regex":
1398  * The right value will be compiled as a regular expression and matched against the left
1399  * value.
1400  * "like":
1401  * Any '%' character in the right value will be converted to '.*' and the resulting
1402  * string will be handled as a regex.
1403  * NULL , "":
1404  * If the right value starts and ends with a '/' then it will be processed as a regex.
1405  * Otherwise, same as "=".
1406  */
1407 int ast_strings_match(const char *left, const char *op, const char *right);
1408 
1409 /*!
1410  * \brief Read lines from a string buffer
1411  * \since 13.18.0
1412  *
1413  * \param buffer [IN/OUT] A pointer to a char * string with either Unix or Windows line endings
1414  *
1415  * \return The "next" line
1416  *
1417  * \warning The original string and *buffer will be modified.
1418  *
1419  * \details
1420  * Both '\n' and '\r\n' are treated as single delimiters but consecutive occurrances of
1421  * the delimiters are NOT considered to be a single delimiter. This preserves blank
1422  * lines in the input.
1423  *
1424  * MacOS line endings ('\r') are not supported at this time.
1425  *
1426  */
1427 char *ast_read_line_from_buffer(char **buffer);
1428 
1429 #endif /* _ASTERISK_STRINGS_H */
typedef typeof(dummy_tv_var_for_types.tv_sec) ast_time_t
#define attribute_pure
Definition: compiler.h:35
void * __ast_calloc(size_t nmemb, size_t size, const char *file, int lineno, const char *func) attribute_malloc
Definition: astmm.c:1635
static force_inline int _ast_strlen_zero(const char *s, const char *file, const char *function, int line)
Definition: strings.h:53
void ast_join_delim(char *s, size_t len, const char *const w[], unsigned int size, char delim)
Definition: main/utils.c:2130
void * ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size)
Retrieve thread storage.
#define DS_ALLOCA
Definition: strings.h:589
Definition: ast_expr2.c:325
size_t ast_str_size(const struct ast_str *buf)
Returns the current maximum length (without reallocation) of the current buffer.
Definition: strings.h:699
static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
Definition: strings.h:112
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
#define force_inline
Definition: compiler.h:29
#define ast_str_make_space(buf, new_len)
Definition: strings.h:780
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:714
char * ast_escape(char *dest, const char *s, size_t size, const char *to_escape)
Escape the &#39;to_escape&#39; characters in the given string.
Definition: main/utils.c:1786
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:982
if(!yyg->yy_init)
Definition: ast_expr2f.c:868
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:1028
void ast_str_container_remove(struct ao2_container *str_container, const char *remove)
Removes a string from a string container allocated by ast_str_container_alloc.
Definition: strings.c:222
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:1091
char * ast_escape_c(char *dest, const char *s, size_t size)
Escape standard &#39;C&#39; sequences in the given string.
Definition: main/utils.c:1829
#define __LOG_WARNING
Definition: logger.h:273
#define ast_assert(a)
Definition: utils.h:695
#define ast_str_alloca(init_len)
Definition: strings.h:800
const char * str
Definition: app_jack.c:147
#define NULL
Definition: resample.c:96
Definitions to aid in the use of thread local storage.
#define _ast_str_helper(buf, max_len, append, fmt, ap)
Definition: strings.h:928
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed)
get values from config variables.
Definition: main/utils.c:2171
#define DS_MALLOC
Definition: strings.h:588
char * ast_skip_nonblanks(const char *str)
Gets a pointer to first whitespace character in a string.
Definition: strings.h:200
Utility functions.
char * ast_str_truncate(struct ast_str *buf, ssize_t len)
Truncates the enclosed string to the given length.
Definition: strings.h:738
#define ast_strlen_zero(foo)
Definition: strings.h:52
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:1065
#define ast_str_tmp(init_len, __expr)
Definition: strings.h:1136
int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed)
get values from config variables.
Definition: main/utils.c:2198
char * ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes)
Strip leading/trailing whitespace and quotes from a string.
Definition: main/utils.c:1639
#define ast_log
Definition: astobj2.c:42
int ast_build_string(char **buffer, size_t *space, const char *fmt,...)
Build a string in a buffer, designed to be called repeatedly.
Definition: main/utils.c:1919
int ast_str_copy_string(struct ast_str **dst, struct ast_str *src)
Definition: strings.h:798
struct ao2_container * ast_str_container_alloc_options(enum ao2_alloc_opts opts, int buckets)
Allocates a hash container for bare strings.
Definition: strings.c:201
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:1014
char * ast_strip(char *s)
Strip leading/trailing whitespace from a string.
Definition: strings.h:219
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:300
char * ast_strsep(char **s, const char sep, uint32_t flags)
Act like strsep but ignore separators inside quotes.
Definition: main/utils.c:1656
#define DS_STATIC
Definition: strings.h:590
static force_inline char * ast_str_to_lower(char *str)
Convert a string to all lower-case.
Definition: strings.h:1268
char * ast_escape_alloc(const char *s, const char *to_escape)
Escape the &#39;to_escape&#39; characters in the given string.
Definition: main/utils.c:1884
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: astmm.h:290
static force_inline char * ast_str_to_upper(char *str)
Convert a string to all upper-case.
Definition: strings.h:1289
ao2_alloc_opts
Options available when allocating an ao2 object.
Definition: astobj2.h:363
char * ast_tech_to_upper(char *dev_str)
Convert the tech portion of a device string to upper case.
Definition: strings.h:1183
int attribute_pure ast_true(const char *val)
Make sure something is true. Determine if a string containing a boolean value is "true". This function checks to see whether a string passed to it is an indication of an "true" value. It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
Definition: main/utils.c:1951
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
char * ast_generate_random_string(char *buf, size_t size)
Create a pseudo-random string of a fixed length.
Definition: strings.c:227
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:586
char __AST_STR_STR[0]
Definition: strings.h:591
int ast_strings_equal(const char *str1, const char *str2)
Compare strings for equality checking for NULL.
Definition: strings.c:239
int _ast_str_make_space(struct ast_str **buf, size_t new_len, const char *file, int lineno, const char *function)
Definition: strings.h:779
char * ast_skip_blanks(const char *str)
Gets a pointer to the first non-whitespace character in a string.
Definition: strings.h:157
char * ast_trim_blanks(char *str)
Trims trailing whitespace characters from a string.
Definition: strings.h:182
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:129
int ast_regex_string_to_regex_pattern(const char *regex_string, struct ast_str **regex_pattern)
Given a string regex_string in the form of "/regex/", convert it into the form of "regex"...
Definition: main/utils.c:1931
static force_inline int ast_str_hash_add(const char *str, int seed)
Compute a hash value on a string.
Definition: strings.h:1232
void * __ast_realloc(void *ptr, size_t size, const char *file, int lineno, const char *func)
Definition: astmm.c:1672
ast_strsep_flags
Flags for ast_strsep.
Definition: strings.h:250
char * ast_escape_c_alloc(const char *s)
Escape standard &#39;C&#39; sequences in the given string.
Definition: main/utils.c:1892
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:1000
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: main/utils.c:1900
int ast_check_digits(const char *arg)
Check if a string is only digits.
Definition: strings.h:1163
char * ast_unescape_semicolon(char *s)
Strip backslash for "escaped" semicolons, the string to be stripped (will be modified).
Definition: main/utils.c:1716
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:1021
#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:653
struct ast_threadstorage * __AST_STR_TS
Definition: strings.h:587
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:688
static force_inline int attribute_pure ast_str_hash_restrict(unsigned int hash)
Restrict hash value range.
Definition: strings.h:1193
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:401
size_t __AST_STR_LEN
Definition: strings.h:585
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:663
int attribute_pure ast_false(const char *val)
Make sure something is false. Determine if a string containing a boolean value is "false"...
Definition: main/utils.c:1968
static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
Definition: strings.h:94
int __ast_str_helper(struct ast_str **buf, ssize_t max_len, int append, const char *fmt, va_list ap, const char *file, int lineno, const char *func)
Core functionality of ast_str_(set|append)_va.
Definition: strings.c:55
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:1007
Generic container type.
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:861
void ast_str_trim_blanks(struct ast_str *buf)
Trims trailing whitespace characters from an ast_str string.
Definition: strings.h:678
static snd_pcm_format_t format
Definition: chan_alsa.c:102
char * ast_to_camel_case_delim(const char *s, const char *delim)
Definition: main/utils.c:2149
struct ast_str * _ast_str_create(size_t init_len, const char *file, int lineno, const char *func)
Definition: strings.h:638
int ast_str_container_add(struct ao2_container *str_container, const char *add)
Adds a string to a string container allocated by ast_str_container_alloc.
Definition: strings.c:206
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:1250
int ast_strings_match(const char *left, const char *op, const char *right)
Compares 2 strings using realtime-style operators.
Definition: strings.c:248
#define ast_str_create(init_len)
Create a malloc&#39;ed dynamic length string.
Definition: strings.h:620
static char prefix[MAX_PREFIX]
Definition: http.c:141
static force_inline int attribute_pure ast_str_hash(const char *str)
Compute a hash value on a string.
Definition: strings.h:1206
char * ast_unescape_c(char *s)
Convert some C escape sequences.
Definition: main/utils.c:1735
char * ast_read_line_from_buffer(char **buffer)
Read lines from a string buffer.
Definition: strings.c:372
#define AST_INLINE_API(hdr, body)
Definition: inline_api.h:54