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