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