strings.c File Reference

String manipulation API. More...

#include "asterisk.h"
#include <regex.h>
#include "asterisk/strings.h"
#include "asterisk/pbx.h"
#include "asterisk/vector.h"

Include dependency graph for strings.c:

Go to the source code of this file.

Functions
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 *function)
	Core functionality of ast_str_(set|append)_va. More...
char *	__ast_str_helper2 (struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc, int append, int escapecommas)
char *	ast_generate_random_string (char *buf, size_t size)
	Create a pseudo-random string of a fixed length. More...
char *	ast_read_line_from_buffer (char **buffer)
	Read lines from a string buffer. More...
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. More...
struct ao2_container *	ast_str_container_alloc_options (enum ao2_alloc_opts opts, int buckets)
	Allocates a hash container for bare strings. More...
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. More...
int	ast_strings_equal (const char *str1, const char *str2)
	Compare strings for equality checking for NULL. More...
int	ast_strings_match (const char *left, const char *op, const char *right)
	Compares 2 strings using realtime-style operators. More...
int	ast_vector_string_split (struct ast_vector_string *dest, const char *input, const char *delim, int flags, int(*excludes_cmp)(const char *s1, const char *s2))
	Append a string vector by splitting a string. More...
static int	str_cmp (void *lhs, void *rhs, int flags)
static int	str_hash (const void *obj, const int flags)
static int	str_sort (const void *lhs, const void *rhs, int flags)

Detailed Description

String manipulation API.

Author

Tilghman Lesher tilgh.nosp@m.man@.nosp@m.digiu.nosp@m.m.co.nosp@m.m

Definition in file strings.c.

Function Documentation

__ast_str_helper()

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 *	function
	)

Core functionality of ast_str_(set|append)_va.

core handler for dynamic strings. This is not meant to be called directly, but rather through the various wrapper macros ast_str_set(...) ast_str_append(...) ast_str_set_va(...) ast_str_append_va(...)

Definition at line 55 of file strings.c.

References _ast_str_make_space(), AST_DYNSTR_BUILD_FAILED, ast_log_safe(), if(), and LOG_VERBOSE.

{
   int res;
   int added;
   int need;
   int offset = (append && (*buf)->__AST_STR_LEN) ? (*buf)->__AST_STR_USED : 0;
   va_list aq;

   if (max_len < 0) {
      max_len = (*buf)->__AST_STR_LEN; /* don't exceed the allocated space */
   }

   do {
      va_copy(aq, ap);
      res = vsnprintf((*buf)->__AST_STR_STR + offset, (*buf)->__AST_STR_LEN - offset, fmt, aq);
      va_end(aq);

      if (res < 0) {
         /*
          * vsnprintf write to string failed.
          * I don't think this is possible with a memory buffer.
          */
         res = AST_DYNSTR_BUILD_FAILED;
         added = 0;
         break;
      }

      /*
       * vsnprintf returns how much space we used or would need.
       * Remember that vsnprintf does not count the nil terminator
       * so we must add 1.
       */
      added = res;
      need = offset + added + 1;
      if (need <= (*buf)->__AST_STR_LEN
         || (max_len && max_len <= (*buf)->__AST_STR_LEN)) {
         /*
          * There was enough room for the string or we are not
          * allowed to try growing the string buffer.
          */
         break;
      }

      /* Reallocate the buffer and try again. */
      if (max_len == 0) {
         /* unbounded, give more room for next time */
         need += 16 + need / 4;
      } else if (max_len < need) {
         /* truncate as needed */
         need = max_len;
      }

      if (_ast_str_make_space(buf, need, file, lineno, function)) {
         ast_log_safe(LOG_VERBOSE, "failed to extend from %d to %d\n",
            (int) (*buf)->__AST_STR_LEN, need);

         res = AST_DYNSTR_BUILD_FAILED;
         break;
      }
   } while (1);

   /* Update space used, keep in mind truncation may be necessary. */
   (*buf)->__AST_STR_USED = ((*buf)->__AST_STR_LEN <= offset + added)
      ? (*buf)->__AST_STR_LEN - 1
      : offset + added;

   /* Ensure that the string is terminated. */
   (*buf)->__AST_STR_STR[(*buf)->__AST_STR_USED] = '\0';

   return res;
}

__ast_str_helper2()

char* __ast_str_helper2	(	struct ast_str **	buf,
		ssize_t	maxlen,
		const char *	src,
		size_t	maxsrc,
		int	append,
		int	escapecommas
	)

Definition at line 129 of file strings.c.

References ast_str::__AST_STR_LEN, ast_str_make_space, and if().

Referenced by ast_str_append_substr(), ast_str_append_va(), ast_str_set_escapecommas(), and ast_str_set_substr().

{
   int dynamic = 0;
   char *ptr = append ? &((*buf)->__AST_STR_STR[(*buf)->__AST_STR_USED]) : (*buf)->__AST_STR_STR;

   if (maxlen < 1) {
      if (maxlen == 0) {
         dynamic = 1;
      }
      maxlen = (*buf)->__AST_STR_LEN;
   }

   while (*src && maxsrc && maxlen && (!escapecommas || (maxlen - 1))) {
      if (escapecommas && (*src == '\\' || *src == ',')) {
         *ptr++ = '\\';
         maxlen--;
         (*buf)->__AST_STR_USED++;
      }
      *ptr++ = *src++;
      maxsrc--;
      maxlen--;
      (*buf)->__AST_STR_USED++;

      if ((ptr >= (*buf)->__AST_STR_STR + (*buf)->__AST_STR_LEN - 3) ||
         (dynamic && (!maxlen || (escapecommas && !(maxlen - 1))))) {
         char *oldbase = (*buf)->__AST_STR_STR;
         size_t old = (*buf)->__AST_STR_LEN;
         if (ast_str_make_space(buf, (*buf)->__AST_STR_LEN * 2)) {
            /* If the buffer can't be extended, end it. */
            break;
         }
         /* What we extended the buffer by */
         maxlen = old;

         ptr += (*buf)->__AST_STR_STR - oldbase;
      }
   }
   if (__builtin_expect(!maxlen, 0)) {
      ptr--;
   }
   *ptr = '\0';
   return (*buf)->__AST_STR_STR;
}

ast_generate_random_string()

char* ast_generate_random_string	(	char *	buf,
		size_t	size
	)

Create a pseudo-random string of a fixed length.

This function is useful for generating a string whose randomness does not need to be across all time and space, does not need to be cryptographically secure, and needs to fit in a limited space.

This function will write a null byte at the final position in the buffer (buf[size - 1]). So if you pass in a size of 10, then this will generate a random 9-character string.

Parameters

buf	Buffer to write random string into.
size	The size of the buffer.

Returns

A pointer to buf

Definition at line 227 of file strings.c.

References ast_random(), and buf.

Referenced by add_rlmi_resource(), create_multipart_body(), generate_content_id_hdr(), and sip_outbound_registration_regc_alloc().

{
   int i;

   for (i = 0; i < size - 1; ++i) {
      buf[i] = 'a' + (ast_random() % 26);
   }
   buf[i] = '\0';

   return buf;
}

ast_read_line_from_buffer()

char* ast_read_line_from_buffer

(

char **

buffer

)

Read lines from a string buffer.

Since

13.18.0

Parameters

buffer

[IN/OUT] A pointer to a char * string with either Unix or Windows line endings

Returns

The "next" line

Warning

The original string and *buffer will be modified.

Both '
' and '
' are treated as single delimiters but consecutive occurrances of the delimiters are NOT considered to be a single delimiter. This preserves blank lines in the input.

MacOS line endings ('') are not supported at this time.

Definition at line 372 of file strings.c.

References NULL.

Referenced by parse_simple_message_summary().

{
   char *start = *buffer;

   if (!buffer || !*buffer || *(*buffer) == '\0') {
      return NULL;
   }

   while (*(*buffer) && *(*buffer) != '\n' ) {
      (*buffer)++;
   }

   *(*buffer) = '\0';
   if (*(*buffer - 1) == '\r') {
      *(*buffer - 1) = '\0';
   }
   (*buffer)++;

   return start;
}

ast_str_container_add()

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.

Since

12

Parameters

str_container	The container to which to add a string
add	The string to add to the container

Return values

zero	on success
non-zero	if the operation failed

Definition at line 206 of file strings.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_link, ao2_ref, and NULL.

Referenced by add_media_cb(), add_variant_cb(), append_name(), apps_handler(), ast_bridge_snapshot_create(), ast_dns_get_nameservers(), ast_endpoint_add_channel(), AST_TEST_DEFINE(), complete_ari_app(), custom_nameserver_handler(), declined_handler(), event_session_alloc(), get_languages(), ip_identify_match_handler(), load_module(), test_cel_peer_strings_match(), and topic_add_subscription().

{
   char *ao2_add;

   /* The ao2_add object is immutable so it doesn't need a lock of its own. */
   ao2_add = ao2_alloc_options(strlen(add) + 1, NULL, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!ao2_add) {
      return -1;
   }
   strcpy(ao2_add, add);/* Safe */

   ao2_link(str_container, ao2_add);
   ao2_ref(ao2_add, -1);
   return 0;
}

ast_str_container_alloc_options()

struct ao2_container* ast_str_container_alloc_options	(	enum ao2_alloc_opts	opts,
		int	buckets
	)

Allocates a hash container for bare strings.

Since

12

Parameters

opts	Options to be provided to the container
buckets	The number of buckets to use for the hash container

Return values

AO2	container for strings
NULL	if allocation failed

Definition at line 201 of file strings.c.

References ao2_container_alloc_hash, str_cmp(), str_hash(), and str_sort().

Referenced by ast_dns_get_nameservers(), custom_nameserver_handler(), endpoint_internal_create(), and ip_identify_match_handler().

{
   return ao2_container_alloc_hash(opts, 0, buckets, str_hash, str_sort, str_cmp);
}

ast_str_container_remove()

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.

Since

12

Parameters

str_container	The container from which to remove a string
remove	The string to remove from the container

Definition at line 222 of file strings.c.

References ao2_find, OBJ_NODATA, OBJ_SEARCH_KEY, and OBJ_UNLINK.

Referenced by endpoint_cache_clear(), test_cel_peer_strings_match(), and topic_remove_subscription().

{
   ao2_find(str_container, remove, OBJ_SEARCH_KEY | OBJ_NODATA | OBJ_UNLINK);
}

ast_strings_equal()

int ast_strings_equal	(	const char *	str1,
		const char *	str2
	)

Compare strings for equality checking for NULL.

Since

16.3.0

This function considers NULL values as non-strings, thus a false condition. This means that it will return false if one, or both of the given values are NULL (i.e. two NULLs are not equal strings).

Parameters

str1	The string to compare to str2
str2	The string to compare to str1

Returns

true if valid strings and equal, false otherwise.

Definition at line 239 of file strings.c.

Referenced by app_event_filter_matched(), is_media_state_valid(), load_realtime_musiconhold(), resolve_refresh_media_states(), and set_outbound_authentication_credentials().

{
   if (!str1 || !str2) {
      return 0;
   }

   return str1 == str2 || !strcmp(str1, str2);
}

ast_strings_match()

int ast_strings_match	(	const char *	left,
		const char *	op,
		const char *	right
	)

Compares 2 strings using realtime-style operators.

Since

13.9.0

Parameters

left	The left side of the equation
op	The operator to apply
right	The right side of the equation

Return values

1	matches
0	doesn't match

Operators: "=", "!=", "<", "<=", ">", ">=": If both left and right can be converted to float, then they will be compared as such. Otherwise the result will be derived from strcmp(left, right). "regex": The right value will be compiled as a regular expression and matched against the left value. "like": Any '' character in the right value will be converted to '.*' and the resulting string will be handled as a regex. NULL , "": If the right value starts and ends with a '/' then it will be processed as a regex. Otherwise, same as "=".

Definition at line 248 of file strings.c.

References ast_str_alloca, ast_str_append(), ast_str_buffer(), ast_str_set(), ast_strdupa, ast_strlen_zero, NULL, regex(), and strsep().

Referenced by AST_TEST_DEFINE(), and ast_variables_match().

{
   char *internal_op = (char *)op;
   char *internal_right = (char *)right;
   double left_num;
   double right_num;
   int scan_numeric = 0;

   if (!(left && right)) {
      return 0;
   }

   if (ast_strlen_zero(op)) {
      if (ast_strlen_zero(left) && ast_strlen_zero(right)) {
         return 1;
      }

      if (strlen(right) >= 2 && right[0] == '/' && right[strlen(right) - 1] == '/') {
         internal_op = "regex";
         internal_right = ast_strdupa(right);
         /* strip the leading and trailing '/' */
         internal_right++;
         internal_right[strlen(internal_right) - 1] = '\0';
         goto regex;
      } else {
         internal_op = "=";
         goto equals;
      }
   }

   if (!strcasecmp(op, "like")) {
      char *tok;
      struct ast_str *buffer = ast_str_alloca(128);

      if (!strchr(right, '%')) {
         return !strcmp(left, right);
      } else {
         internal_op = "regex";
         internal_right = ast_strdupa(right);
         tok = strsep(&internal_right, "%");
         ast_str_set(&buffer, 0, "^%s", tok);

         while ((tok = strsep(&internal_right, "%"))) {
            ast_str_append(&buffer, 0, ".*%s", tok);
         }
         ast_str_append(&buffer, 0, "%s", "$");

         internal_right = ast_str_buffer(buffer);
         /* fall through to regex */
      }
   }

regex:
   if (!strcasecmp(internal_op, "regex")) {
      regex_t expression;
      int rc;

      if (regcomp(&expression, internal_right, REG_EXTENDED | REG_NOSUB)) {
         return 0;
      }

      rc = regexec(&expression, left, 0, NULL, 0);
      regfree(&expression);
      return !rc;
   }

equals:
   scan_numeric = (sscanf(left, "%lf", &left_num) > 0 && sscanf(internal_right, "%lf", &right_num) > 0);

   if (internal_op[0] == '=') {
      if (ast_strlen_zero(left) && ast_strlen_zero(internal_right)) {
         return 1;
      }

      if (scan_numeric) {
         return (left_num == right_num);
      } else {
         return (!strcmp(left, internal_right));
      }
   }

   if (internal_op[0] == '!' && internal_op[1] == '=') {
      if (scan_numeric) {
         return (left_num != right_num);
      } else {
         return !!strcmp(left, internal_right);
      }
   }

   if (internal_op[0] == '<') {
      if (scan_numeric) {
         if (internal_op[1] == '=') {
            return (left_num <= right_num);
         } else {
            return (left_num < right_num);
         }
      } else {
         if (internal_op[1] == '=') {
            return strcmp(left, internal_right) <= 0;
         } else {
            return strcmp(left, internal_right) < 0;
         }
      }
   }

   if (internal_op[0] == '>') {
      if (scan_numeric) {
         if (internal_op[1] == '=') {
            return (left_num >= right_num);
         } else {
            return (left_num > right_num);
         }
      } else {
         if (internal_op[1] == '=') {
            return strcmp(left, internal_right) >= 0;
         } else {
            return strcmp(left, internal_right) > 0;
         }
      }
   }

   return 0;
}

ast_vector_string_split()

int ast_vector_string_split	(	struct ast_vector_string *	dest,
		const char *	input,
		const char *	delim,
		int	flags,
		int(*)(const char *s1, const char *s2)	excludes_cmp
	)

Append a string vector by splitting a string.

Parameters

dest	Pointer to an initialized vector.
input	String buffer to split.
delim	String delimeter passed to strsep.
flags	Processing options defined by enum ast_vector_string_split_flags.
excludes_cmp	NULL or a function like strcmp to exclude duplicate strings.

Return values

0	Success
-1	Failure

Note

All elements added to the vector are allocated. The caller is always responsible for calling ast_free on each element in the vector even after failure. It's possible for this function to successfully add some elements before failing.

Definition at line 393 of file strings.c.

References ast_assert, ast_free, ast_strdup, ast_strdupa, ast_strip(), ast_strlen_zero, AST_VECTOR_APPEND, AST_VECTOR_GET_CMP, AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY, AST_VECTOR_STRING_SPLIT_NO_TRIM, buf, NULL, and strsep().

Referenced by module_post_register().

{
   char *buf;
   char *cur;
   int no_trim = flags & AST_VECTOR_STRING_SPLIT_NO_TRIM;
   int allow_empty = flags & AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY;

   ast_assert(dest != NULL);
   ast_assert(!ast_strlen_zero(delim));

   if (ast_strlen_zero(input)) {
      return 0;
   }

   buf = ast_strdupa(input);
   while ((cur = strsep(&buf, delim))) {
      if (!no_trim) {
         cur = ast_strip(cur);
      }

      if (!allow_empty && ast_strlen_zero(cur)) {
         continue;
      }

      if (excludes_cmp && AST_VECTOR_GET_CMP(dest, cur, !excludes_cmp)) {
         continue;
      }

      cur = ast_strdup(cur);
      if (!cur || AST_VECTOR_APPEND(dest, cur)) {
         ast_free(cur);

         return -1;
      }
   }

   return 0;
}

str_cmp()

static int str_cmp ( void *  lhs, void *  rhs, int  flags  )

static

Definition at line 187 of file strings.c.

References CMP_MATCH, OBJ_SEARCH_MASK, and OBJ_SEARCH_PARTIAL_KEY.

Referenced by ast_str_container_alloc_options().

{
   int cmp = 0;

   if ((flags & OBJ_SEARCH_MASK) == OBJ_SEARCH_PARTIAL_KEY) {
      cmp = strncmp(lhs, rhs, strlen(rhs));
   } else {
      cmp = strcmp(lhs, rhs);
   }

   return cmp ? 0 : CMP_MATCH;
}

str_hash()

static int str_hash ( const void *  obj, const int  flags  )

static

Definition at line 173 of file strings.c.

References ast_str_hash().

Referenced by ast_str_container_alloc_options().

{
   return ast_str_hash(obj);
}

str_sort()

static int str_sort ( const void *  lhs, const void *  rhs, int  flags  )

static

Definition at line 178 of file strings.c.

References OBJ_SEARCH_MASK, and OBJ_SEARCH_PARTIAL_KEY.

Referenced by ast_str_container_alloc_options().

{
   if ((flags & OBJ_SEARCH_MASK) == OBJ_SEARCH_PARTIAL_KEY) {
      return strncmp(lhs, rhs, strlen(rhs));
   } else {
      return strcmp(lhs, rhs);
   }
}