String manipulation functions. More...

#include <ctype.h>
#include <limits.h>
#include "asterisk/utils.h"
#include "asterisk/threadstorage.h"
#include "asterisk/astobj2.h"

Include dependency graph for strings.h:

Go to the source code of this file.

Data Structures
struct	ast_str
	The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field to indicate the type of storage. Three special constants indicate malloc, ast_alloca() or static variables, all other values indicate a struct ast_threadstorage pointer. More...

Macros
#define	__AST_STR_LEN len

#define	__AST_STR_STR str

#define	__AST_STR_TS ts

#define	__AST_STR_USED used

#define	_ast_str_helper(buf, max_len, append, fmt, ap) __ast_str_helper(buf, max_len, append, fmt, ap, __FILE__, __LINE__, __PRETTY_FUNCTION__)

#define	_DB1(x)

#define	AS_OR(a, b) (a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)

#define	ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')

#define	ast_str_alloca(init_len)

#define	ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
	Allocates a hash container for bare strings. More...

#define	ast_str_create(init_len) _ast_str_create(init_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Create a malloc'ed dynamic length string. More...

#define	ast_str_make_space(buf, new_len) _ast_str_make_space(buf, new_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)

#define	ast_str_tmp(init_len, __expr)

#define	ast_strlen_zero(foo) _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)

#define	ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")

#define	AST_YESNO(x) ((x) ? "Yes" : "No")
	return Yes or No depending on the argument. More...

#define	DS_ALLOCA ((struct ast_threadstorage *)2)

#define	DS_MALLOC ((struct ast_threadstorage *)1)

#define	DS_STATIC ((struct ast_threadstorage )3) / not supported yet */

#define	S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
	returns the equivalent of logic or for strings, with an additional boolean check: second one if not empty and first one is true, otherwise third one. example: S_COR(usewidget, widget, "<no widget>") More...

#define	S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
	returns the equivalent of logic or for strings: first one if not empty, otherwise second one. More...

Enumerations
enum	{ AST_DYNSTR_BUILD_FAILED = -1, AST_DYNSTR_BUILD_RETRY = -2 }
	Error codes from __ast_str_helper() The undelying processing to manipulate dynamic string is done by __ast_str_helper(), which can return a success or a permanent failure (e.g. no memory). More...

enum	ast_strsep_flags { AST_STRSEP_STRIP = 0x01, AST_STRSEP_TRIM = 0x02, AST_STRSEP_UNESCAPE = 0x04, AST_STRSEP_ALL = 0x07 }
	Flags for ast_strsep. More...

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 func)
	Core functionality of ast_str_(set\|append)_va. More...

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

struct ast_str *	_ast_str_create (size_t init_len, const char file, int lineno, const char func)

int	_ast_str_make_space (struct ast_str *buf, size_t new_len, const char file, int lineno, const char *function)

static force_inline int	_ast_strlen_zero (const char s, const char file, const char *function, int line)

static int force_inline attribute_pure	ast_begins_with (const char str, const char prefix)

int	ast_build_string (char *buffer, size_t space, const char *fmt,...)
	Build a string in a buffer, designed to be called repeatedly. More...

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. More...

int	ast_check_digits (const char *arg)
	Check if a string is only digits. More...

void	ast_copy_string (char dst, const char src, size_t size)
	Size-limited null-terminating string copy. More...

static int force_inline attribute_pure	ast_ends_with (const char str, const char suffix)

char *	ast_escape (char dest, const char s, size_t size, const char *to_escape)
	Escape the 'to_escape' characters in the given string. More...

char *	ast_escape_alloc (const char s, const char to_escape)
	Escape the 'to_escape' characters in the given string. More...

char *	ast_escape_c (char dest, const char s, size_t size)
	Escape standard 'C' sequences in the given string. More...

char *	ast_escape_c_alloc (const char *s)
	Escape standard 'C' sequences in the given string. More...

int attribute_pure	ast_false (const char *val)
	Make sure something is false. Determine if a string containing a boolean value is "false". This function checks to see whether a string passed to it is an indication of an "false" value. It checks to see if the string is "no", "false", "n", "f", "off" or "0". More...

char *	ast_generate_random_string (char *buf, size_t size)
	Create a pseudo-random string of a fixed length. More...

int	ast_get_time_t (const char src, time_t dst, time_t _default, int *consumed)
	get values from config variables. More...

int	ast_get_timeval (const char src, struct timeval tv, struct timeval _default, int *consumed)
	get values from config variables. More...

void	ast_join_delim (char s, size_t len, const char const w[], unsigned int size, char delim)

char *	ast_read_line_from_buffer (char **buffer)
	Read lines from a string buffer. More...

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". More...

char *	ast_skip_blanks (const char *str)
	Gets a pointer to the first non-whitespace character in a string. More...

char *	ast_skip_nonblanks (const char *str)
	Gets a pointer to first whitespace character in a string. More...

int	ast_str_append (struct ast_str *buf, ssize_t max_len, const char fmt,...)
	Append to a thread local dynamic string. More...

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. More...

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. More...

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. More...

char *	ast_str_buffer (const struct ast_str *buf)
	Returns the string buffer within the ast_str buf. More...

static force_inline int attribute_pure	ast_str_case_hash (const char *str)
	Compute a hash value on a case-insensitive string. 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_str_copy_string (struct ast_str *dst, struct ast_str src)

static force_inline int attribute_pure	ast_str_hash (const char *str)
	Compute a hash value on a string. More...

static force_inline int	ast_str_hash_add (const char *str, int seed)
	Compute a hash value on a string. More...

static force_inline int attribute_pure	ast_str_hash_restrict (unsigned int hash)
	Restrict hash value range. More...

void	ast_str_reset (struct ast_str *buf)
	Reset the content of a dynamic string. Useful before a series of ast_str_append. More...

int	ast_str_set (struct ast_str *buf, ssize_t max_len, const char fmt,...)
	Set a dynamic string using variable arguments. More...

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. More...

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. More...

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. More...

size_t	ast_str_size (const struct ast_str *buf)
	Returns the current maximum length (without reallocation) of the current buffer. More...

size_t	ast_str_strlen (const struct ast_str *buf)
	Returns the current length of the string stored within buf. More...

struct ast_str *	ast_str_thread_get (struct ast_threadstorage *ts, size_t init_len)
	Retrieve a thread locally stored dynamic string. More...

static force_inline char *	ast_str_to_lower (char *str)
	Convert a string to all lower-case. More...

static force_inline char *	ast_str_to_upper (char *str)
	Convert a string to all upper-case. More...

void	ast_str_trim_blanks (struct ast_str *buf)
	Trims trailing whitespace characters from an ast_str string. More...

char *	ast_str_truncate (struct ast_str *buf, ssize_t len)
	Truncates the enclosed string to the given length. More...

void	ast_str_update (struct ast_str *buf)
	Update the length of the buffer, after using ast_str merely as a buffer. 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...

char *	ast_strip (char *s)
	Strip leading/trailing whitespace from a string. More...

char *	ast_strip_quoted (char s, const char beg_quotes, const char *end_quotes)
	Strip leading/trailing whitespace and quotes from a string. More...

char *	ast_strsep (char **s, const char sep, uint32_t flags)
	Act like strsep but ignore separators inside quotes. More...

char *	ast_tech_to_upper (char *dev_str)
	Convert the tech portion of a device string to upper case. More...

char *	ast_to_camel_case_delim (const char s, const char delim)

char *	ast_trim_blanks (char *str)
	Trims trailing whitespace characters from a string. More...

int attribute_pure	ast_true (const char *val)
	Make sure something is true. Determine if a string containing a boolean value is "true". This function checks to see whether a string passed to it is an indication of an "true" value. It checks to see if the string is "yes", "true", "y", "t", "on" or "1". More...

char *	ast_unescape_c (char *s)
	Convert some C escape sequences. More...

char *	ast_unescape_semicolon (char *s)
	Strip backslash for "escaped" semicolons, the string to be stripped (will be modified). More...

Detailed Description

String manipulation functions.

Definition in file strings.h.

Macro Definition Documentation

◆ __AST_STR_LEN

#define __AST_STR_LEN len

Definition at line 42 of file strings.h.

◆ __AST_STR_STR

#define __AST_STR_STR str

Definition at line 43 of file strings.h.

◆ __AST_STR_TS

#define __AST_STR_TS ts

Definition at line 44 of file strings.h.

◆ __AST_STR_USED

#define __AST_STR_USED used

Definition at line 41 of file strings.h.

◆ _ast_str_helper

#define _ast_str_helper	(	buf,
		max_len,
		append,
		fmt,
		ap
	)	__ast_str_helper(buf, max_len, append, fmt, ap, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 928 of file strings.h.

Referenced by ast_str_set_va().

◆ _DB1

#define _DB1 ( x )

Definition at line 751 of file strings.h.

◆ AS_OR

#define AS_OR	(	a,
		b
	)	(a && ast_str_strlen(a)) ? ast_str_buffer(a) : (b)

Definition at line 49 of file strings.h.

Referenced by aoc_to_ami(), cli_show_module_options(), mwi_update_cb(), mysql_log(), and rtcp_report_to_ami().

◆ ast_join

#define ast_join	(	s,
		len,
		w
	)	ast_join_delim(s, len, w, -1, ' ')

Definition at line 483 of file strings.h.

Referenced by __ast_cli_generator(), ast_agi_register(), ast_agi_unregister(), ast_cli_command_full(), cli_console_sendtext(), console_sendtext(), find_best(), handle_cli_agi_show(), handle_cli_check_permissions(), handle_help(), help1(), help_workhorse(), set_full_cmd(), and write_htmldump().

◆ ast_str_alloca

#define ast_str_alloca ( init_len )

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 800 of file strings.h.

Referenced by __manager_event_sessions_va(), __queues_show(), _iax2_show_peers_one(), _sip_show_peer(), _skinny_show_device(), _skinny_show_line(), action_agents(), action_createconfig(), action_listcommands(), action_login(), add_cc_call_info_to_response(), add_rpid(), add_sdp(), agent_handle_show_specific(), agent_show_requested(), alsa_request(), aocmessage_get_unit_entry(), app_exec(), ast_eivr_getvariable(), ast_json_ipaddr(), ast_sip_append_body(), ast_str_encode_mime(), ast_streamfile(), ast_strings_match(), AST_TEST_DEFINE(), ast_var_channels_table(), ast_write_stream(), build_nonce(), build_peer(), cc_extension_monitor_init(), cc_generic_agent_start_monitoring(), challenge(), chan_pjsip_write_stream(), chanavail_exec(), check_nonce(), cli_alias_passthrough(), cli_match_char_tree(), codec_handler_fn(), console_request(), construct_pidf_body(), do_magic_pickup(), extract_transferrer_headers(), func_channel_read(), func_headers_read2(), function_iaxpeer(), function_realtime_read(), function_realtime_readdestroy(), function_sippeer(), generate_fmtp_attr(), generate_status(), generate_uri(), handle_call_token(), handle_capabilities_res_message(), handle_cli_core_show_channeltype(), handle_cli_iax2_show_peer(), handle_cli_indication_show(), handle_cli_ooh323_show_config(), handle_cli_ooh323_show_peers(), handle_cli_ooh323_show_users(), handle_show_translation_path(), handle_showchan(), handle_showmanager(), handle_showmancmd(), hashkeys_read(), hashkeys_read2(), iax2_key_rotate(), iax2_request(), jingle_write(), local_request_with_stream_topology(), log_caps(), log_jack_status(), manager_json_array_with_key(), manager_json_obj_with_key(), mbl_request(), mgcp_request(), mgcp_write(), native_rtp_bridge_compatible_check(), nbs_request(), onNewCallCreated(), ooh323_request(), ooh323_set_write_format(), ooh323_write(), oss_request(), phone_request(), print_queue(), print_uptimestr(), process_sdp(), request_channel(), sendtext_exec(), serialize_showchan(), set_caps(), set_format(), show_channels_cb(), sip_new(), sip_request_call(), sip_send_mwi_to_peer(), sip_show_channel(), sip_show_sched(), sip_show_settings(), sip_write(), skinny_new(), skinny_request(), skinny_write(), socket_process_helper(), start_rtp(), test_2way_function(), test_create_joint(), transmit_info_with_aoc(), transmit_notify_with_mwi(), transmit_state_notify(), unistim_new(), unistim_request(), unistim_rtp_read(), unistim_show_info(), unistim_write(), update_scoreboard(), and wait_for_answer().

◆ ast_str_container_alloc

#define ast_str_container_alloc ( buckets ) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)

Allocates a hash container for bare strings.

Since: 12

Parameters

buckets The number of buckets to use for the hash container

Return values

AO2	container for strings
NULL	if allocation failed

Definition at line 1312 of file strings.h.

Referenced by ast_bridge_snapshot_create(), ast_cel_general_config_alloc(), ast_media_get_media(), ast_media_get_variants(), event_session_alloc(), get_languages(), stasis_app_get_all(), stasis_config_alloc(), stasis_subscription_statistics_create(), stasis_topic_statistics_create(), and test_cel_peer_strings_match().

◆ ast_str_create

#define ast_str_create ( init_len ) _ast_str_create(init_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Create a malloc'ed dynamic length string.

Parameters

init_len This is the initial length of the string buffer

Returns: This function returns a pointer to the dynamic string length. The result will be NULL in the case of a memory allocation error.

Note: The result of this function is dynamically allocated memory, and must be free()'d after it is no longer needed.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 620 of file strings.h.

Referenced by __ast_http_post_load(), __ast_test_status_update(), __ast_test_suite_event_notify(), __ast_trace(), __sip_reliable_xmit(), __test_cel_generate_peer_str(), _ast_xmldoc_build_arguments(), _ast_xmldoc_build_seealso(), _macro_exec(), _sip_tcp_helper_thread(), acf_curl_exec(), acf_curl_helper(), acf_cut_exec(), action_hangup(), add_bundle_groups(), add_crypto_to_stream(), add_ice_to_stream(), add_required_respheader(), add_sdp(), allocate_subscription(), analog_publish_dnd_state(), aoc_display_decoded_debug(), ari_channels_handle_originate_with_id(), ast_ari_asterisk_get_global_var(), ast_ari_callback(), ast_ari_channels_create(), ast_ari_channels_get_channel_var(), ast_ari_get_docs(), ast_category_get_templates(), ast_cc_agent_set_interfaces_chanvar(), ast_channel_dialed_causes_channels(), ast_dump_locks(), ast_func_read(), ast_get_character_str(), ast_get_digit_str(), ast_get_money_en_dollars_str(), ast_get_phonetic_str(), ast_http_auth(), ast_http_create_response(), ast_http_error(), ast_http_send(), ast_log_backtrace(), ast_log_show_lock(), ast_logger_get_channels(), ast_manager_build_bridge_state_string_prefix(), ast_manager_build_channel_state_string_prefix(), ast_manager_str_from_json_object(), ast_monitor_stop(), ast_parse_digest(), ast_set_cc_interfaces_chanvar(), ast_sip_cli_traverse_objects(), ast_sip_create_ami_event(), ast_sounds_get_index_for_file(), ast_statsd_log_string(), ast_str_append_event_header(), ast_str_substitute_variables_full(), ast_stream_create_resolved(), ast_tcptls_client_create(), ast_tcptls_server_root(), ast_test_debug(), AST_TEST_DEFINE(), ast_xml_doc_item_alloc(), ast_xmldoc_printable(), ast_xmldoc_query(), attended_transfer_to_ami(), auth_http_callback(), build_notify(), build_path_data(), build_user_routes(), caldav_get_events_between(), caldav_request(), caldav_write_event(), calendar_join_attendees(), cdr_handler(), cel_generate_peer_str(), channel_fax_cb(), channel_get_external_vars(), channel_hangup_request_cb(), channel_hold_cb(), channel_mixmonitor_mute_cb(), cli_list_subscriptions_inout(), cli_print_body(), cli_prompt(), cli_show_settings(), cli_show_subscription_common(), cli_show_subscriptions_inout(), codec_prefs_handler(), codec_prefs_to_str(), config_text_file_load(), contacts_to_str(), contactstatus_to_ami(), copy_request(), create_channel_name(), create_lookup_filter(), cut_internal(), device_state_cb(), digest_create_request_with_auth(), do_notify(), dump_queue_members(), ewscal_write_event(), exchangecal_get_events_between(), exchangecal_request(), exchangecal_write_event(), exec_exec(), exten_state_publisher_cb(), fetch_icalendar(), find_aor(), find_realtime(), function_sippeer(), generate_status(), generic_http_callback(), get_ewscal_ids_for(), get_languages(), get_number_str_en(), handle_aor(), handle_dbget(), handle_getvariablefull(), handle_hint_change_message_type(), handle_manager_show_events(), handle_missing_table(), handle_options(), handle_registrations(), handle_request_refer(), handle_show_translation_table(), handle_showchan(), handle_updates(), handle_uri(), http_callback(), httpstatus_callback(), iax_parse_ies(), init_appendbuf(), init_queue(), init_req(), init_resp(), initreqprep(), is_new_rec_file(), jack_str(), join_conference_bridge(), leave_voicemail(), list_item_to_str(), load_column_config(), load_config(), load_dlopen(), load_modules(), load_values_config(), local_message_to_ami(), localnet_to_str(), log_action(), log_attended_transfer(), make_email_file(), manager_bridge_info(), manager_bridge_tech_list(), manager_bridges_list(), manager_build_parked_call_string(), manager_json_to_ast_str(), match_to_str(), meetme_cmd_helper(), meetme_show_cmd(), meetme_stasis_cb(), misdn_cfg_get_config_string(), mock_tcp_loop(), multi_object_blob_to_ami(), mwi_allocate_body(), mwi_mailbox_delete(), mwi_mailbox_get(), my_load_config_string(), named_callgroups_to_str(), named_pickupgroups_to_str(), odbc_log(), parking_lot_cfg_create_extensions(), parse_ewscal_id(), pbx_retrieve_variable(), peerstatus_to_ami(), pgsql_log(), pgsql_reconnect(), pjsip_acf_dial_contacts_read(), pp_each_extension_helper(), presence_state_cb(), print_named_groups(), process_description_file(), prometheus_scrape_to_string(), publish_channel_alarm(), publish_channel_alarm_clear(), publish_dnd_state(), queue_set_param(), read_config(), read_raw_content_length(), realtime_ldap_status(), realtime_sqlite3_destroy(), realtime_sqlite3_helper(), realtime_sqlite3_store(), realtime_sqlite3_update(), realtime_sqlite3_update2(), replace(), require_pgsql(), resource_list_recursive_decline(), response_alloc(), rtcp_report_to_ami(), run_app_helper(), run_station(), security_event_to_ami_blob(), send_eivr_event(), send_unsolicited_mwi_notify_to_contact(), sendmail(), sendpage(), set_var_to_str(), sip_notify_alloc(), sip_route_list(), sip_rtp_read(), sip_tcptls_write(), sip_websocket_callback(), sipsock_read(), spandsp_manager_fax_session(), start_resource_list(), startelm(), stasis_app_control_snoop(), static_callback(), statsmaker(), store_odbc(), system_registry_to_ami(), test_2way_function(), test_alloc(), test_chan_function(), test_chan_integer(), test_chan_integer_accessor(), test_chan_string(), test_chan_variable(), test_cli_generate_results(), test_expected_result(), test_files_create(), test_suite_event_to_ami(), test_xml_entry(), threadpool_alloc(), tls_method_to_str(), transmit_info_dtmf(), try_calling(), tryexec_exec(), update_caldav(), varset_to_ami(), vm_allocate_dh(), websocket_bad_request(), websocket_client_parse_uri(), write_cel(), xmldoc_get_formatted(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_config_object(), xmldoc_get_syntax_config_option(), xmldoc_get_syntax_manager(), xmldoc_parse_cmd_enumlist(), xmldoc_string_cleanup(), and xmldoc_string_wrap().

◆ ast_str_make_space

#define ast_str_make_space	(	buf,
		new_len
	)	_ast_str_make_space(buf, new_len, __FILE__, __LINE__, __PRETTY_FUNCTION__)

◆ ast_str_tmp

#define ast_str_tmp	(	init_len,
		__expr
	)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1136 of file strings.h.

Referenced by add_sdp_streams(), apply_negotiated_sdp_stream(), ast_channel_nativeformats_set(), ast_channel_request_stream_topology_change(), ast_channel_set_stream_topology(), ast_sip_session_create_outgoing(), ast_stream_create_resolved(), AST_TEST_DEFINE(), call(), chan_pjsip_call(), chan_pjsip_get_codec(), chan_pjsip_indicate(), chan_pjsip_request_with_stream_topology(), chan_pjsip_set_rtp_peer(), compatible_formats_exist(), create_local_sdp(), create_outgoing_sdp_stream(), dial_exec_full(), handle_incoming_sdp(), is_media_state_valid(), on_topology_change_response(), resolve_refresh_media_states(), send_topology_change_refresh(), session_on_tsx_state(), sip_session_refresh(), softmix_bridge_stream_sources_update(), test_scope_enter_function(), and wait_for_answer().

◆ ast_strlen_zero

#define ast_strlen_zero ( foo ) _ast_strlen_zero(foo, __FILE__, __PRETTY_FUNCTION__, __LINE__)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 52 of file strings.h.

◆ ast_to_camel_case

#define ast_to_camel_case ( s ) ast_to_camel_case_delim(s, "_")

Definition at line 509 of file strings.h.

Referenced by ast_sip_sorcery_object_to_ami(), and sip_aor_to_ami().

◆ AST_YESNO

#define AST_YESNO ( x ) ((x) ? "Yes" : "No")

return Yes or No depending on the argument.

Note that this macro is used my AMI, where a literal "Yes" and "No" are expected, and translations would cause problems.

Parameters

x	Boolean value

Returns: "Yes" if x is true (non-zero); "No" if x is false (zero)

Definition at line 139 of file strings.h.

Referenced by action_confbridgelist_item(), action_confbridgelistrooms(), dtlsautogeneratecert_to_str(), dtlsverify_to_str(), get_bool_header(), manager_bridge_tech_list(), pjsip_acf_moh_passthrough_read(), require_client_cert_to_str(), statsd_init(), verify_client_to_str(), and verify_server_to_str().

◆ DS_ALLOCA

#define DS_ALLOCA ((struct ast_threadstorage *)2)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 589 of file strings.h.

◆ DS_MALLOC

#define DS_MALLOC ((struct ast_threadstorage *)1)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 588 of file strings.h.

◆ DS_STATIC

#define DS_STATIC ((struct ast_threadstorage *)3) /* not supported yet */

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 590 of file strings.h.

◆ S_COR

#define S_COR	(	a,
		b,
		c
	)	({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})

returns the equivalent of logic or for strings, with an additional boolean check: second one if not empty and first one is true, otherwise third one. example: S_COR(usewidget, widget, "<no widget>")

Examples:: /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 85 of file strings.h.

Referenced by __analog_handle_event(), __ast_goto_if_exists(), __ast_pbx_run(), _macro_exec(), _skinny_show_line(), acf_isexten_exec(), action_meetmelist(), add_rpid(), analog_call(), analog_ss_thread(), ast_app_dtget(), ast_bridge_setup_after_goto(), ast_channel_nativeformats_set(), ast_pbx_h_exten_run(), ast_stream_topology_to_str(), background_detect_exec(), caller_id_to_str(), chan_pjsip_cng_tone_detected(), chan_pjsip_new(), channel_snapshot_caller_create(), channel_snapshot_connected_create(), cli_endpoint_print_body(), cli_list_subscriptions_detail(), cli_show_subscriptions_detail(), collect_digits(), console_call(), copy_message(), create_local_sdp(), dahdi_handle_dtmf(), dahdi_handle_event(), dial_exec_full(), dialog_info_generate_body_content(), disa_exec(), do_forward(), eval_exten_read(), fax_detect_framehook(), find_matching_endif(), find_matching_endwhile(), findmeexec(), forward_message(), generate_status(), gosub_exec(), gosub_run(), handle_cli_confbridge_list_item(), handle_cli_misdn_show_channels(), handle_gosub(), handle_setpriority(), handle_showchan(), indicate_connected_line(), isAnsweringMachine(), isexten_function_read(), launch_monitor_thread(), leave_voicemail(), local_call(), manager_queues_status(), meetme_show_cmd(), mgcp_call(), mgcp_hangup(), mgcp_ss(), minivm_greet_exec(), minivm_notify_exec(), misdn_copy_redirecting_from_ast(), misdn_get_connected_line(), misdn_write(), my_handle_dtmf(), my_on_hook(), onModeChanged(), ooh323_rtp_read(), ospauth_exec(), osplookup_exec(), oss_call(), party_id_read(), pbx_builtin_background(), pbx_builtin_waitexten(), pbx_outgoing_attempt(), pbx_parseable_goto(), process_ast_dsp(), process_sdp(), push_callinfo(), queue_exec(), readexten_exec(), release_chan(), run_externnotify(), send_callinfo(), serialize_showchan(), set_from_header(), setsubstate(), setup_env(), sip_read(), sip_subscription_to_ami(), sms_exec(), socket_process_helper(), start_automixmonitor(), start_automonitor(), state_notify_build_xml(), try_calling(), unicast_rtp_request(), unistim_indicate(), update_connectedline(), valid_exit(), vm_allocate_dh(), vm_authenticate(), waitstream_core(), and write_metadata().

◆ S_OR

#define S_OR	(	a,
		b
	)	({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})

returns the equivalent of logic or for strings: first one if not empty, otherwise second one.

Examples:: /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 79 of file strings.h.

Referenced by __ast_channel_alloc_ap(), __ast_cli_register(), __ast_codec_register_with_format(), __ast_sorcery_object_type_insert_wizard(), __ast_sorcery_object_type_remove_wizard(), __ast_trace(), __ssl_setup(), _sip_show_peer(), _skinny_show_device(), _skinny_show_line(), acf_curl_helper(), acf_if(), acf_transaction_write(), acf_vm_info(), action_getvar(), action_messagesend(), action_reload(), action_setvar(), action_status(), actual_load_config(), add_transferer_role(), alloc_security_event_json_object(), analog_ss_thread(), append_event_str_single(), append_row_to_cfg(), ari_bridges_play_helper(), ari_channels_handle_originate_with_id(), ari_channels_handle_play(), array(), ast_ari_asterisk_get_global_var(), ast_ari_callback(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_get_channel_var(), ast_bridge_channel_run_app(), ast_bridge_timelimit(), ast_call_forward(), ast_cc_call_init(), ast_cdr_serialize_variables(), ast_cel_create_event_with_time(), ast_cel_fill_record(), ast_cel_get_type_name(), ast_channel_connected_line_macro(), ast_channel_connected_line_sub(), ast_channel_nativeformats_set(), ast_channel_publish_dial_internal(), ast_channel_redirecting_macro(), ast_channel_redirecting_sub(), ast_cli_command_full(), ast_format_create_named(), ast_get_chan_applicationmap(), ast_manager_build_channel_state_string_prefix(), ast_media_index_update_for_file(), ast_msg_data_alloc2(), ast_msg_send(), ast_multicast_rtp_create_options(), ast_play_and_record_full(), ast_queue_log(), ast_sendtext_data(), ast_sip_format_contact_ami(), ast_sip_publish_client_get_from_uri(), ast_sip_publish_client_get_to_uri(), ast_sip_session_create_outgoing(), ast_sockaddr_parse(), ast_sockaddr_resolve(), ast_stream_alloc(), ast_stream_clone(), ast_stream_to_str(), ast_system_publish_registry(), authenticate(), beanstalk_put(), bridge_create_common(), bridge_parking_push(), build_callid_pvt(), build_callid_registry(), build_peer(), build_profile(), build_route(), calltoken_required(), cc_generic_agent_init(), cc_interfaces_datastore_init(), cdr_handler(), cel_bs_put(), celgenuserevent_exec(), chan_pjsip_cng_tone_detected(), channel_dial_cb(), channel_do_masquerade(), channel_enter_cb(), channel_read_rtcp(), channel_read_rtp(), channel_snapshot_caller_create(), channel_snapshot_hangup_create(), channel_snapshot_peer_create(), check_auth(), cli_fax_show_sessions(), cli_odbc_write(), common_exec(), conf_get_sound(), config_curl(), config_handler(), config_parse_variables(), create_dynamic_lot_full(), create_local_sdp(), create_queue_member(), dahdi_handle_dtmf(), dahdi_show_channel(), dial_exec_full(), dialog_info_generate_body_content(), dialplan_has_destination_cb(), do_forward(), dundi_exec(), enable_jack_hook(), endpoint_internal_create(), execif_exec(), exten_state_publisher_state_cb(), extension_length_comparator(), extensionstate_update(), fast_originate(), fax_detect_framehook(), feature_automixmonitor(), feature_automonitor(), feature_blind_transfer(), file_write(), find_conf(), find_user(), format_log_json(), forward_message(), generate_status(), generic_recall(), get_also_info(), get_cid_name(), get_defaults(), get_destination(), get_outbound_endpoint(), get_rdnis(), get_refer_info(), get_single_field_as_var_list(), getsubbyname(), gosub_run(), goto_exten(), handle_bridge_show_all(), handle_bridge_show_specific(), handle_call_forward(), handle_call_token(), handle_chanlist(), handle_cli_agi_show(), handle_cli_cdr_mysql_status(), handle_cli_check_permissions(), handle_cli_config_list(), handle_cli_iax2_show_channels(), handle_cli_moh_show_classes(), handle_debug(), handle_debug_category(), handle_gosub(), handle_manager_show_settings(), handle_minivm_list_templates(), handle_minivm_show_users(), handle_request_invite(), handle_request_refer(), handle_request_subscribe(), handle_response_register(), handle_show_function(), handle_show_functions(), handle_show_settings(), handle_showchan(), handle_showmanager(), handle_showmancmd(), handle_skinny_show_settings(), handle_streamfile(), handle_trace(), handle_verbose(), hashtab_compare_exten_labels(), hashtab_hash_labels(), help1(), help_workhorse(), hold_to_json(), hook_on(), iftime(), init_logger_chain(), init_pvt(), jingle_new(), leave_voicemail(), load_dlopen(), load_module(), local_alloc(), local_read(), logged_dlclose(), make_email_file(), manager_dbput(), manager_fax_sessions_entry(), manager_mixmonitor(), manager_park(), manager_queue_log_custom(), manager_queue_reload(), manager_set_defaults(), manager_show_registry(), mbl_devicestate(), misdn_cfg_get(), misdn_copy_redirecting_from_ast(), misdn_get_connected_line(), mixmonitor_exec(), msg_create_from_file(), msg_q_cb(), msg_route(), msg_send_exec(), msg_to_endpoint(), mstime(), my_distinctive_ring(), my_handle_dtmf(), my_load_module(), new_subscribe(), npval(), on_dns_update_registry(), onModeChanged(), ooh323_rtp_read(), originate_exec(), oss_call(), pbx_builtin_execiftime(), pbx_builtin_waitdigit(), pbx_builtin_waitexten(), pbx_exec(), pbx_extension_helper(), pbx_load_config(), pbx_outgoing_exec(), pgsql_reconnect(), phase_e_handler(), pjsip_acf_dial_contacts_read(), play_mailbox_owner(), play_moh_exec(), prep_email_sub_vars(), presence_state_alloc(), print_app_docs(), print_featuregroup(), process_ast_dsp(), process_config(), process_sdp(), process_sdp_o(), process_text_line(), publish_hangup_handler_message(), publish_reload_message(), publish_request_initial(), queue_exec(), realtime_common(), realtime_curl(), realtime_destroy_handler(), realtime_directory(), realtime_exec(), realtime_handler(), realtime_multi_curl(), realtime_multi_handler(), realtime_multi_odbc(), realtime_odbc(), realtime_store_handler(), realtime_update2_handler(), realtime_update_handler(), refer_blind_callback(), register_exten(), register_peer_exten(), reload_config(), report_receive_fax_status(), report_send_fax_status(), return_exec(), ring_entry(), row_to_varlist(), rt_handle_member_record(), run_externnotify(), rx_data_to_ast_msg(), select_entry(), send_msg(), send_provisional_keepalive_full(), sendpage(), sendtext_exec(), serialize_showchan(), set_channel_variables(), set_member_paused(), set_queue_member_pause(), set_transfer_variables_all(), setup_env(), setup_filestack(), shared_write(), show_channels_cb(), show_codec(), show_codecs(), sip_aor_to_ami(), sip_dialog_create_contact(), sip_msg_send(), sip_outbound_registration_regc_alloc(), sip_parse_register_line(), sip_read(), sip_show_domains(), sip_show_settings(), sip_uri_cmp(), sla_show_stations(), sla_show_trunks(), sms_exec(), sms_log(), socket_process_helper(), start_automixmonitor(), start_automonitor(), start_moh_exec(), start_monitor_exec(), stasis_app_control_continue(), stasis_app_message_handler(), state_notify_build_xml(), static_callback(), statistics_show_subscription(), stop_mixmonitor_full(), subscription_established(), test_cli_generate_results(), test_txt_entry(), test_xml_entry(), testtime_write(), tls_method_to_str(), transmit_notify_with_mwi(), transmit_register(), unbound_resolver_callback(), unicast_rtp_request(), unregister_exten(), users_apply_handler(), verify_mock_cdr_record(), vm_allocate_dh(), wait_for_answer(), xmldoc_get_syntax_config_object(), xmpp_client_reconnect(), xmpp_client_set_group_presence(), xmpp_pak_message(), and xmpp_pak_presence().

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Error codes from __ast_str_helper() The undelying processing to manipulate dynamic string is done by __ast_str_helper(), which can return a success or a permanent failure (e.g. no memory).

Enumerator
AST_DYNSTR_BUILD_FAILED	An error has occurred and the contents of the dynamic string are undefined
AST_DYNSTR_BUILD_RETRY	The buffer size for the dynamic string had to be increased, and __ast_str_helper() needs to be called again after a va_end() and va_start(). This return value is legacy and will no longer be used.

Definition at line 892 of file strings.h.

      {
    /*! An error has occurred and the contents of the dynamic string
     *  are undefined */
    AST_DYNSTR_BUILD_FAILED = -1,
    /*! The buffer size for the dynamic string had to be increased, and
     *  __ast_str_helper() needs to be called again after
     *  a va_end() and va_start().  This return value is legacy and will
     *  no longer be used.
     */
    AST_DYNSTR_BUILD_RETRY = -2
 };

◆ ast_strsep_flags

enum ast_strsep_flags

Flags for ast_strsep.

Enumerator
AST_STRSEP_STRIP	Trim, then strip quotes. You may want to trim again
AST_STRSEP_TRIM	Trim leading and trailing whitespace
AST_STRSEP_UNESCAPE	Unescape '\'
AST_STRSEP_ALL	Trim, strip, unescape

Definition at line 250 of file strings.h.

                       {
    AST_STRSEP_STRIP =    0x01, /*!< Trim, then strip quotes.  You may want to trim again */
    AST_STRSEP_TRIM =     0x02, /*!< Trim leading and trailing whitespace */
    AST_STRSEP_UNESCAPE = 0x04, /*!< Unescape '\' */
    AST_STRSEP_ALL =      0x07, /*!< Trim, strip, unescape */
 };

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.

The arguments to this function are the same as those described for ast_str_set_va except for an addition argument, append. If append is non-zero, this will append to the current string instead of writing over it.

AST_DYNSTR_BUILD_RETRY is a legacy define. It should probably never again be used.

A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.

A return value greater than or equal to zero indicates the number of characters that have been written, not including the terminating '\0'. In the append case, this only includes the number of characters appended.

Note: This function should never need to be called directly. It should through calling one of the other functions or macros defined in this file.

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(...)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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	max_len,
		const char *	src,
		size_t	maxsrc,
		int	append,
		int	escapecommas
	)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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_str_create()

struct ast_str * _ast_str_create	(	size_t	init_len,
		const char *	file,
		int	lineno,
		const char *	func
	)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 638 of file strings.h.

References buf.

645 {

◆ _ast_str_make_space()

int _ast_str_make_space	(	struct ast_str **	buf,
		size_t	new_len,
		const char *	file,
		int	lineno,
		const char *	function
	)

inline

Make space in a new string (e.g. to read in data from a file)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 779 of file strings.h.

Referenced by __ast_str_helper().

785 {

◆ _ast_strlen_zero()

static force_inline int _ast_strlen_zero	(	const char *	s,
		const char *	file,
		const char *	function,
		int	line
	)

static

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 53 of file strings.h.

References __LOG_WARNING, ast_log, ast_strlen_zero, attribute_pure, and force_inline.

 {
    if (!s || (*s == '\0')) {
       return 1;
    }
    if (!strcmp(s, "(null)")) {
       ast_log(__LOG_WARNING, file, line, function, "Possible programming error: \"(null)\" is not NULL!\n");
    }
    return 0;
 }

◆ ast_begins_with()

static int force_inline attribute_pure ast_begins_with	(	const char *	str,
		const char *	prefix
	)

static

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 94 of file strings.h.

References ast_assert, NULL, prefix, and str.

Referenced by app_event_source_find(), assign_uuid(), ast_ari_callback(), ast_ari_get_docs(), ast_crypt(), ast_crypt_validate(), ast_http_get_auth(), ast_sendtext_data(), AST_TEST_DEFINE(), cache_simple(), explicit_publish_cb(), extract_transferrer_headers(), func_headers_read2(), get_object_variables(), handle_slash(), handle_updates(), handle_validate(), implicit_publish_cb(), moh_parse_options(), msg_send(), on_load_public_cert_url(), on_rx_process_symmetric_transport(), play_on_channel(), safe_mkdir(), sendtext_exec(), stasis_app_stored_recording_find_by_name(), stasis_app_user_event(), state_id_by_topic(), and stir_shaken_incoming_request().

 {
    ast_assert(str != NULL);
    ast_assert(prefix != NULL);
    while (*str == *prefix && *prefix != '\0') {
       ++str;
       ++prefix;
    }
    return *prefix == '\0';
 }

◆ ast_build_string()

int ast_build_string	(	char **	buffer,
		size_t *	space,
		const char *	fmt,
			...
	)

Build a string in a buffer, designed to be called repeatedly.

Note: This method is not recommended. New code should use ast_str_*() instead.

This is a wrapper for snprintf, that properly handles the buffer pointer and buffer space available.

Parameters

buffer	current position in buffer to place string into (will be updated on return)
space	remaining space in buffer (will be updated on return)
fmt	printf-style format string

Return values

0	on success
non-zero	on failure.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1919 of file main/utils.c.

References ast_build_string_va(), and result.

Referenced by ast_fax_caps_to_str(), generate_filenames_string(), handle_speechrecognize(), pp_each_extension_helper(), and vm_allocate_dh().

 {
    va_list ap;
    int result;
 
    va_start(ap, fmt);
    result = ast_build_string_va(buffer, space, fmt, ap);
    va_end(ap);
 
    return result;
 }

◆ ast_build_string_va()

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.

This is a wrapper for snprintf, that properly handles the buffer pointer and buffer space available.

Returns: 0 on success, non-zero on failure.

Parameters

buffer	current position in buffer to place string into (will be updated on return)
space	remaining space in buffer (will be updated on return)
fmt	printf-style format string
ap	varargs list of arguments for format

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1900 of file main/utils.c.

References result.

Referenced by ast_build_string().

 {
    int result;
 
    if (!buffer || !*buffer || !space || !*space)
       return -1;
 
    result = vsnprintf(*buffer, *space, fmt, ap);
 
    if (result < 0)
       return -1;
    else if (result > *space)
       result = *space;
 
    *buffer += result;
    *space -= result;
    return 0;
 }

◆ ast_check_digits()

int ast_check_digits ( const char * arg )

inline

Check if a string is only digits.

Return values

1	The string contains only digits
0	The string contains non-digit characters

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1163 of file strings.h.

Referenced by create_addr().

1172 {

◆ ast_copy_string()

void ast_copy_string	(	char *	dst,
		const char *	src,
		size_t	size
	)

inline

Size-limited null-terminating string copy.

Parameters

dst	The destination buffer.
src	The source string
size	The size of the destination buffer

Returns: Nothing.

This is similar to strncpy, with two important differences:

the destination buffer will always be null-terminated
the destination buffer is not filled with zeros past the copied string length These differences make it slightly more efficient, and safer to use since it will not leave the destination buffer unterminated. There is no need to pass an artificially reduced buffer size to this function (unlike strncpy), and the buffer does not need to be initialized to zeroes prior to calling this function.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 401 of file strings.h.

584 {

◆ ast_ends_with()

static int force_inline attribute_pure ast_ends_with	(	const char *	str,
		const char *	suffix
	)

static

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 112 of file strings.h.

References ast_assert, and NULL.

Referenced by ast_ari_callback(), ast_sip_cli_traverse_objects(), AST_TEST_DEFINE(), and format_log_message_ap().

 {
    size_t str_len;
    size_t suffix_len;
 
    ast_assert(str != NULL);
    ast_assert(suffix != NULL);
    str_len = strlen(str);
    suffix_len = strlen(suffix);
 
    if (suffix_len > str_len) {
       return 0;
    }
 
    return strcmp(str + str_len - suffix_len, suffix) == 0;
 }

◆ ast_escape()

char* ast_escape	(	char *	dest,
		const char *	s,
		size_t	size,
		const char *	to_escape
	)

Escape the 'to_escape' characters in the given string.

Note: The given output buffer will contain a truncated escaped version of the source string if the given buffer is not large enough.

Parameters

dest	the escaped string
s	the source string to escape
size	The size of the destination buffer
to_escape	an array of characters to escape

Returns: Pointer to the destination.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1786 of file main/utils.c.

References ast_copy_string(), ast_strlen_zero, c, and escape_sequences.

Referenced by ast_escape_alloc().

 {
    char *p;
    char *c;
 
    if (!dest || !size) {
       return dest;
    }
    if (ast_strlen_zero(s)) {
       *dest = '\0';
       return dest;
    }
 
    if (ast_strlen_zero(to_escape)) {
       ast_copy_string(dest, s, size);
       return dest;
    }
 
    for (p = dest; *s && --size; ++s, ++p) {
       /* If in the list of characters to escape then escape it */
       if (strchr(to_escape, *s)) {
          if (!--size) {
             /* Not enough room left for the escape sequence. */
             break;
          }
 
          /*
           * See if the character to escape is part of the standard escape
           * sequences. If so we'll have to use its mapped counterpart
           * otherwise just use the current character.
           */
          c = strchr(escape_sequences, *s);
          *p++ = '\\';
          *p = c ? escape_sequences_map[c - escape_sequences] : *s;
       } else {
          *p = *s;
       }
    }
    *p = '\0';
 
    return dest;
 }

◆ ast_escape_alloc()

char* ast_escape_alloc	(	const char *	s,
		const char *	to_escape
	)

Escape the 'to_escape' characters in the given string.

Note: Caller is responsible for freeing the returned string

Parameters

s	the source string to escape
to_escape	an array of characters to escape

Returns: Pointer to the escaped string or NULL.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1884 of file main/utils.c.

References ast_escape(), and escape_alloc().

 {
    size_t size = 0;
    char *dest = escape_alloc(s, &size);
 
    return ast_escape(dest, s, size, to_escape);
 }

◆ ast_escape_c()

char* ast_escape_c	(	char *	dest,
		const char *	s,
		size_t	size
	)

Escape standard 'C' sequences in the given string.

Note: The given output buffer will contain a truncated escaped version of the source string if the given buffer is not large enough.

Parameters

dest	the escaped string
s	the source string to escape
size	The size of the destination buffer

Returns: Pointer to the escaped string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1829 of file main/utils.c.

References ast_strlen_zero, c, and escape_sequences.

Referenced by ast_escape_c_alloc().

 {
    /*
     * Note - This is an optimized version of ast_escape. When looking only
     * for escape_sequences a couple of checks used in the generic case can
     * be left out thus making it slightly more efficient.
     */
    char *p;
    char *c;
 
    if (!dest || !size) {
       return dest;
    }
    if (ast_strlen_zero(s)) {
       *dest = '\0';
       return dest;
    }
 
    for (p = dest; *s && --size; ++s, ++p) {
       /*
        * See if the character to escape is part of the standard escape
        * sequences. If so use its mapped counterpart.
        */
       c = strchr(escape_sequences, *s);
       if (c) {
          if (!--size) {
             /* Not enough room left for the escape sequence. */
             break;
          }
 
          *p++ = '\\';
          *p = escape_sequences_map[c - escape_sequences];
       } else {
          *p = *s;
       }
    }
    *p = '\0';
 
    return dest;
 }

◆ ast_escape_c_alloc()

char* ast_escape_c_alloc ( const char * s )

Escape standard 'C' sequences in the given string.

Note: Caller is responsible for freeing the returned string

Parameters

s	the source string to escape

Returns: Pointer to the escaped string or NULL.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1892 of file main/utils.c.

References ast_escape_c(), and escape_alloc().

Referenced by ast_manager_build_channel_state_string_prefix(), channel_new_callerid(), presence_state_to_ami(), and varset_to_ami().

 {
    size_t size = 0;
    char *dest = escape_alloc(s, &size);
 
    return ast_escape_c(dest, s, size);
 }

◆ ast_false()

int attribute_pure ast_false ( const char * val )

Make sure something is false. Determine if a string containing a boolean value is "false". This function checks to see whether a string passed to it is an indication of an "false" value. It checks to see if the string is "no", "false", "n", "f", "off" or "0".

Return values

0	if val is a NULL pointer.
-1	if "true".
0	otherwise.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1968 of file main/utils.c.

References ast_strlen_zero.

Referenced by acf_faxopt_write(), acf_transaction_write(), actual_load_config(), announce_user_count_all_handler(), aoc_cli_debug_enable(), bool_handler_fn(), boolflag_handler_fn(), build_peer(), build_user(), check_debug(), dahdi_set_dnd(), find_realtime(), function_ooh323_write(), handle_common_options(), handle_queue_set_member_ringinuse(), hook_write(), init_acf_query(), load_config(), manager_mute_mixmonitor(), manager_queue_member_ringinuse(), parking_feature_flag_cfg(), parse_empty_options(), parse_playtone(), prack_handler(), process_config(), process_dahdi(), process_echocancel(), read_pjproject_startup_options(), reload(), reload_config(), reload_single_member(), rt_handle_member_record(), rtp_reload(), run_agi(), set_config(), set_insecure_flags(), sip_parse_nat_option(), sla_build_trunk(), strings_to_mask(), and timers_handler().

 {
    if (ast_strlen_zero(s))
       return 0;
 
    /* Determine if this is a false value */
    if (!strcasecmp(s, "no") ||
        !strcasecmp(s, "false") ||
        !strcasecmp(s, "n") ||
        !strcasecmp(s, "f") ||
        !strcasecmp(s, "0") ||
        !strcasecmp(s, "off"))
       return -1;
 
    return 0;
 }

◆ 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

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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_get_time_t()

int ast_get_time_t	(	const char *	src,
		time_t *	dst,
		time_t	_default,
		int *	consumed
	)

get values from config variables.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 2198 of file main/utils.c.

References ast_strlen_zero, and NULL.

Referenced by build_peer(), cache_lookup_internal(), dundi_show_cache(), dundi_show_hints(), handle_saydatetime(), load_password(), play_message_datetime(), process_clearcache(), realtime_peer(), and sayunixtime_exec().

 {
    long t;
    int scanned;
 
    if (dst == NULL)
       return -1;
 
    *dst = _default;
 
    if (ast_strlen_zero(src))
       return -1;
 
    /* only integer at the moment, but one day we could accept more formats */
    if (sscanf(src, "%30ld%n", &t, &scanned) == 1) {
       *dst = t;
       if (consumed)
          *consumed = scanned;
       return 0;
    } else
       return -1;
 }

◆ ast_get_timeval()

int ast_get_timeval	(	const char *	src,
		struct timeval *	tv,
		struct timeval	_default,
		int *	consumed
	)

get values from config variables.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 2171 of file main/utils.c.

References ast_strlen_zero, and NULL.

Referenced by acf_strftime(), expiration_str2struct(), persistence_expires_str2struct(), and timeval_str2struct().

 {
    long double dtv = 0.0;
    int scanned;
 
    if (dst == NULL)
       return -1;
 
    *dst = _default;
 
    if (ast_strlen_zero(src))
       return -1;
 
    /* only integer at the moment, but one day we could accept more formats */
    if (sscanf(src, "%30Lf%n", &dtv, &scanned) > 0) {
       dst->tv_sec = dtv;
       dst->tv_usec = (dtv - dst->tv_sec) * 1000000.0;
       if (consumed)
          *consumed = scanned;
       return 0;
    } else
       return -1;
 }

◆ ast_join_delim()

void ast_join_delim	(	char *	s,
		size_t	len,
		const char *const	w[],
		unsigned int	size,
		char	delim
	)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 2130 of file main/utils.c.

References len().

Referenced by ast_sip_auths_to_str().

 {
    int x, ofs = 0;
    const char *src;
 
    /* Join words into a string */
    if (!s)
       return;
    for (x = 0; ofs < len && x < size && w[x] ; x++) {
       if (x > 0)
          s[ofs++] = delim;
       for (src = w[x]; *src && ofs < len; src++)
          s[ofs++] = *src;
    }
    if (ofs == len)
       ofs--;
    s[ofs] = '\0';
 }

◆ 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.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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_regex_string_to_regex_pattern()

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".

This function will trim one leading / and one trailing / from a given input string ast_str regex_pattern must be preallocated before calling this function

Returns: 0 on success, non-zero on failure.; 1 if we only stripped a leading /; 2 if we only stripped a trailing /; 3 if we did not strip any / characters

Parameters

regex_string	the string containing /regex/
regex_pattern	the destination ast_str which will contain "regex" after execution

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1931 of file main/utils.c.

References ast_str_set(), and ast_str_truncate().

Referenced by action_hangup(), mwi_mailbox_delete(), and mwi_mailbox_get().

 {
    int regex_len = strlen(regex_string);
    int ret = 3;
 
    /* Chop off the leading / if there is one */
    if ((regex_len >= 1) && (regex_string[0] == '/')) {
       ast_str_set(regex_pattern, 0, "%s", regex_string + 1);
       ret -= 2;
    }
 
    /* Chop off the ending / if there is one */
    if ((regex_len > 1) && (regex_string[regex_len - 1] == '/')) {
       ast_str_truncate(*regex_pattern, -1);
       ret -= 1;
    }
 
    return ret;
 }

◆ ast_skip_blanks()

char * ast_skip_blanks ( const char * str )

inline

Gets a pointer to the first non-whitespace character in a string.

Parameters

str	the input string

Returns: a pointer to the first non-whitespace character

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 157 of file strings.h.

References str.

Referenced by __ast_cli_register(), __ast_trace(), __astman_get_header(), __find_call(), __get_header(), acf_faxopt_write(), add_redirect(), ast_append_acl(), ast_get_namedgroups(), ast_http_header_parse(), ast_parse_arg(), ast_parse_digest(), ast_skip_nonblanks(), build_peer(), callerid_write(), capture_buildopts_cb(), connectedline_write(), curl_header_callback(), determine_firstline_parts(), do_say(), dtmf_info_incoming_request(), extract_transferrer_headers(), find_table_cb(), func_headers_read2(), get_calleridname(), get_content_line(), get_rpid(), get_sdp_iterate(), get_sdp_line(), handle_incoming(), handle_request_invite(), handle_request_notify(), handle_response(), headers_to_vars(), http_request_headers_get(), httpd_process_request(), keypad_cfg_read(), man_do_variable_value(), mark_parsed_methods(), next_item(), parse_cdata(), parse_line(), parse_minse(), parse_session_expires(), parse_via(), pbx_load_config(), process_description_file(), process_sdp(), process_text_line(), proxy_from_config(), redirecting_write(), reload_config(), remove_excess_lws(), reply_digest(), rfc3326_use_reason_header(), rtp_reload(), sdp_fmtp_get(), set_message_vars_from_req(), sip_digest_parser(), stackpeek_read(), transmit_fake_auth_response(), transmit_invite(), use_reason_header(), user_event_hook_cb(), xml_translate(), and xmldoc_get_formatted().

166 {

◆ ast_skip_nonblanks()

char * ast_skip_nonblanks ( const char * str )

inline

Gets a pointer to first whitespace character in a string.

Parameters

str	the input string

Returns: a pointer to the first whitespace character

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 200 of file strings.h.

References ast_skip_blanks(), and ast_trim_blanks().

Referenced by __ast_cli_register(), determine_firstline_parts(), handle_response(), httpd_process_request(), and remove_excess_lws().

213 {

◆ ast_str_append()

int ast_str_append	(	struct ast_str **	buf,
		ssize_t	max_len,
		const char *	fmt,
			...
	)

inline

Append to a thread local dynamic string.

Note: Care should be taken when using this function. The function can result in reallocating the ast_str. If a pointer to the ast_str is passed by value to a function that calls ast_str_append(), then the original ast_str pointer may be invalidated due to a reallocation.

The arguments, return values, and usage of this function are the same as ast_str_set(), but the new data is appended to the current value.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1091 of file strings.h.

1137 { \

◆ ast_str_append_escapecommas()

char * ast_str_append_escapecommas	(	struct ast_str **	buf,
		ssize_t	maxlen,
		const char *	src,
		size_t	maxsrc
	)

inline

Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1028 of file strings.h.

References ast_str_set_va().

Referenced by acf_odbc_read(), and function_db_keys().

1055 {

◆ ast_str_append_substr()

char * ast_str_append_substr	(	struct ast_str **	buf,
		ssize_t	maxlen,
		const char *	src,
		size_t	maxsrc
	)

inline

Append a non-NULL terminated substring to the end of a dynamic string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1014 of file strings.h.

References __ast_str_helper2().

Referenced by ast_str_substitute_variables_full(), file_read(), listfilter(), logger_add_verbose_magic(), write_to_ast_str(), and WriteMemoryCallback().

1018 {

◆ ast_str_append_va()

int ast_str_append_va	(	struct ast_str **	buf,
		ssize_t	max_len,
		const char *	fmt,
		va_list	ap
	)

inline

Append to a dynamic string using a va_list.

Same as ast_str_set_va(), but append to the current content.

Note: Care should be taken when using this function. The function can result in reallocating the ast_str. If a pointer to the ast_str is passed by value to a function that calls ast_str_append_va(), then the original ast_str pointer may be invalidated due to a reallocation.

Parameters

buf,max_len,fmt,ap

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1000 of file strings.h.

References __ast_str_helper2().

Referenced by __manager_event_sessions_va(), and ast_str_set().

1004 {

◆ ast_str_buffer()

char * ast_str_buffer ( const struct ast_str * buf )

inline

Returns the string buffer within the ast_str buf.

Parameters

buf	A pointer to the ast_str structure.

Return values

A	pointer to the enclosed string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 714 of file strings.h.

References buf, len(), and typeof().

Referenced by __ast_format_cap_get_names(), __ast_test_status_update(), __ast_test_suite_event_notify(), __ast_trace(), __manager_event_sessions_va(), __queues_show(), __sip_pretend_ack(), __sip_reliable_xmit(), __sip_semi_ack(), __sip_xmit(), _ast_xmldoc_build_arguments(), _ast_xmldoc_build_seealso(), _iax2_show_peers_one(), _macro_exec(), _sip_show_peer(), _sip_tcp_helper_thread(), _xmldoc_build_field(), acf_curl_exec(), acf_curl_helper(), acf_cut_exec(), acf_odbc_read(), acf_odbc_write(), action_agents(), action_confbridgelist_item(), action_coreshowchannels(), action_createconfig(), action_getconfig(), action_getconfigjson(), action_hangup(), action_userevent(), add_bundle_groups(), add_cc_call_info_to_response(), add_crypto_to_stream(), add_hintdevice(), add_ice_to_stream(), add_required_respheader(), add_route(), add_rpid(), add_sdp(), agent_handle_show_specific(), agent_login_to_ami(), agent_logoff_to_ami(), agent_show_requested(), agi_channel_to_ami(), ALLOC_COMMENT(), ami_outbound_registration_task(), ami_registrations_aor(), ami_subscription_detail(), analog_publish_dnd_state(), ao2_container_unregister(), aoc_display_decoded_debug(), aoc_to_ami(), aocmessage_get_unit_entry(), ari_channel_thread(), ari_channels_handle_originate_with_id(), ast_agi_send(), ast_ari_callback(), ast_ari_channels_get_channel_var(), ast_ari_get_docs(), ast_cc_agent_set_interfaces_chanvar(), ast_eivr_getvariable(), ast_func_read(), ast_func_read2(), ast_get_money_en_dollars_str(), ast_http_create_response(), ast_http_send(), ast_json_ipaddr(), ast_json_load_str(), ast_log_backtrace(), ast_log_show_lock(), ast_logger_get_channels(), ast_monitor_stop(), ast_odbc_ast_str_SQLGetData(), ast_parse_digest(), ast_print_namedgroups(), ast_realtime_encode_chunk(), ast_rtp_lookup_mime_multiple2(), ast_say_number_full_en(), ast_set_cc_interfaces_chanvar(), ast_sip_append_body(), ast_sip_format_contact_ami(), ast_sockaddr_stringify_fmt(), ast_sounds_get_index_for_file(), ast_statsd_log_full_va(), ast_statsd_log_string(), ast_statsd_log_string_va(), ast_str_encode_mime(), ast_str_get_encoded_str(), ast_str_quote(), ast_str_retrieve_variable(), ast_str_substitute_variables_full(), ast_str_substring(), ast_stream_codec_prefs_to_str(), ast_stream_create_resolved(), ast_stream_to_str(), ast_stream_topology_to_str(), ast_strings_match(), ast_test_debug(), AST_TEST_DEFINE(), ast_translate_path_to_str(), ast_var_channels_table(), AST_VECTOR(), ast_xmldoc_printable(), ast_xmldoc_query(), astman_append(), astman_flush(), astman_send_error_va(), attended_transfer_to_ami(), authority_to_str(), base64_helper(), blacklist_read2(), blind_transfer_to_ami(), bridge_merge_cb(), bridge_snapshot_update(), build_nonce(), build_notify_body(), build_peer(), build_user_routes(), caldav_request(), calendar_join_attendees(), call_pickup_to_ami(), cc_extension_monitor_init(), cc_unique_append(), cdata(), cdr_handler(), cel_bridge_enter_cb(), cel_bridge_leave_cb(), challenge(), chanavail_exec(), change_hold_state(), channel_chanspy_start_cb(), channel_chanspy_stop_cb(), channel_dial_cb(), channel_dtmf_begin_cb(), channel_dtmf_end_cb(), channel_enter_cb(), channel_fax_cb(), channel_flash_cb(), channel_get_external_vars(), channel_hangup_handler_cb(), channel_hangup_request_cb(), channel_hold_cb(), channel_leave_cb(), channel_mixmonitor_mute_cb(), channel_moh_start_cb(), channel_snapshot_update(), channel_unhold_cb(), check_auth(), check_message_integrity(), check_nonce(), cli_alias_passthrough(), cli_list_subscriptions_detail(), cli_match_char_tree(), cli_odbc_read(), cli_odbc_write(), cli_prompt(), cli_show_module_options(), cli_show_module_type(), cli_show_module_types(), cli_show_settings(), cli_show_subscription_common(), cli_show_subscriptions_detail(), codec_prefs_handler(), commit_exec(), conf_start_record(), confbridge_publish_manager_event(), config_curl(), config_mysql(), config_odbc(), config_pgsql(), config_text_file_load(), configure_connection_charset(), construct_pidf_body(), contacts_to_str(), contactstatus_to_ami(), create_channel_name(), custom_log(), cut_internal(), dahdi_cc_callback(), dahdi_new(), dahdichannel_to_ami(), dbl_list_expect_forward(), dbl_list_expect_reverse(), destroy_curl(), destroy_mysql(), destroy_odbc(), destroy_pgsql(), detect_disconnect(), determine_firstline_parts(), dialog_info_to_string(), digest_create_request_with_auth(), do_magic_pickup(), do_notify(), dump_queue_members(), dump_str_and_free(), dumpchan_exec(), eivr_comm(), endelm(), exchangecal_get_events_between(), exchangecal_request(), exchangecal_write_event(), exec_exec(), exten_state_publisher_cb(), extract_transferrer_headers(), fetch_icalendar(), file2display(), finalize_content(), find_aor(), find_realtime(), find_table(), format_ami_aor_handler(), format_ami_aorlist_handler(), format_ami_auth_handler(), format_ami_authlist_handler(), format_ami_contactlist_handler(), format_ami_endpoint(), format_ami_endpoint_transport(), format_ami_endpoints(), format_ami_resource_lists(), format_log_message_ap(), func_headers_read2(), function_fieldnum_helper(), function_fieldqty_helper(), function_iaxpeer(), function_realtime_read(), function_realtime_readdestroy(), function_sippeer(), generate_fmtp_attr(), generate_notify_body(), generate_status(), generate_uri(), get_content(), get_key(), get_languages(), get_number_str_en(), handle_aor(), handle_call_token(), handle_cli_cdr_mysql_status(), handle_cli_iax2_show_peer(), handle_cli_indication_show(), handle_dbget(), handle_end_element(), handle_getvariablefull(), handle_manager_show_events(), handle_missing_table(), handle_options(), handle_registrations(), handle_request_do(), handle_request_refer(), handle_show_locks(), handle_show_translation_path(), handle_show_translation_table(), handle_showchan(), hangupcause_keys_read(), hashkeys_read2(), http_callback(), http_post_callback(), iax2_getformatname_multiple(), iax_parse_ies(), initreqprep(), is_new_rec_file(), is_valid_uuid(), jack_str(), leave_voicemail(), list_expect(), list_item_to_str(), listfilter(), load_column_config(), load_dlopen(), load_modules(), load_values_config(), local_message_to_ami(), localnet_to_str(), log_action(), log_attended_transfer(), log_jack_status(), logger_add_verbose_magic(), lws2sws(), make_email_file(), manager_bridge_info(), manager_bridge_tech_list(), manager_build_parked_call_string(), manager_generic_msg_cb(), manager_json_array_with_key(), manager_json_obj_with_key(), manager_log(), manager_parking_status_all_lots(), manager_parking_status_single_lot(), match_to_str(), meetme_cmd_helper(), meetme_show_cmd(), meetme_stasis_cb(), mock_tcp_loop(), module_load_error(), multi_object_blob_to_ami(), multi_user_event_to_ami(), mwi_app_event_cb(), mwi_mailbox_delete(), mwi_mailbox_get(), mwi_to_string(), my_connect_db(), my_load_module(), mysql_log(), named_callgroups_to_str(), named_pickupgroups_to_str(), odbc_log(), parked_call_message_response(), parking_lot_cfg_create_extensions(), parse_hint_device(), parse_hint_presence(), parse_register_contact(), parse_request(), pbx_find_extension(), pbx_retrieve_variable(), peerstatus_to_ami(), pgsql_log(), pgsql_reconnect(), pidf_to_string(), pjsip_acf_dial_contacts_read(), pp_each_extension_helper(), print_event_instance(), print_queue(), print_uptimestr(), process_description_file(), process_text_line(), prometheus_show_metrics(), publish_basic_channel_event(), publish_channel_alarm(), publish_channel_alarm_clear(), publish_dnd_state(), queue_channel_to_ami(), queue_member_to_ami(), queue_multi_channel_to_ami(), read_raw_content_length(), realtime_curl(), realtime_directory(), realtime_ldap_base_ap(), realtime_ldap_status(), realtime_multi_curl(), realtime_multi_mysql(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_mysql(), realtime_odbc(), realtime_pgsql(), realtime_sqlite3_destroy(), realtime_sqlite3_helper(), realtime_sqlite3_store(), realtime_sqlite3_update(), realtime_sqlite3_update2(), realtime_update2_handler(), realtimefield_read(), register_aor_core(), replace(), require_curl(), require_pgsql(), resource_list_recursive_decline(), retrans_pkt(), rm_file(), rollback_exec(), rtcp_report_to_ami(), run_app_helper(), run_station(), say_character_str_full(), say_digit_str_full(), say_money_str_full(), say_periodic_announcement(), say_phonetic_str_full(), sayfile_exec(), search_directory_sub(), security_event_stasis_cb(), security_event_to_ami_blob(), send_bridge_info_item_cb(), send_bridge_list_item_cb(), send_eivr_event(), send_ews_request_and_parse(), send_identify_ami_event(), send_request(), send_response(), send_unsolicited_mwi_notify_to_contact(), sendmail(), sendpage(), sendtext_exec(), session_timeout_to_ami(), set2(), set_format(), shift_pop(), show_channels_cb(), sip_hangup(), sip_report_security_event(), sip_rtp_read(), sip_send_mwi_to_peer(), sip_show_channel(), sip_show_sched(), sip_tcptls_read(), snoop_stasis_thread(), spandsp_manager_fax_session(), sqlite3_escape_column_op(), sqlite3_escape_string_helper(), start_resource_list(), startelm(), statsmaker(), store_curl(), store_mysql(), store_odbc(), store_pgsql(), str_appender(), string_tolower2(), string_toupper2(), strreplace(), substitute_escapes(), syslog_log(), system_exec_helper(), system_registry_to_ami(), talking_start_to_ami(), talking_stop_to_ami(), test_2way_function(), test_chan_function(), test_chan_integer(), test_chan_integer_accessor(), test_chan_string(), test_chan_variable(), test_cli_generate_results(), test_expected_result(), test_files_create(), test_files_get_one(), test_suite_event_to_ami(), test_txt_entry(), test_xml_entry(), threadpool_alloc(), tls_method_to_str(), transmit_fake_auth_response(), transmit_info_dtmf(), transmit_info_with_aoc(), transmit_invite(), transmit_notify_with_mwi(), transmit_state_notify(), try_calling(), tryexec_exec(), unshift_push(), update2_curl(), update2_ldap(), update2_mysql(), update2_odbc(), update2_pgsql(), update2_prepare(), update_caldav(), update_curl(), update_ewscal(), update_exchangecal(), update_mysql(), update_odbc(), update_peer(), update_pgsql(), update_scoreboard(), user_authority_to_str(), varset_to_ami(), vm_allocate_dh(), websocket_client_handshake(), write_cel(), xmldoc_get_formatted(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_config_object(), xmldoc_get_syntax_config_option(), xmldoc_get_syntax_manager(), xmldoc_parse_cmd_enumlist(), xmldoc_parse_example(), xmldoc_parse_para(), xmldoc_parse_variable(), xmldoc_string_wrap(), and xpidf_to_string().

725 {

◆ ast_str_case_hash()

static force_inline int attribute_pure ast_str_case_hash ( const char * str )

static

Compute a hash value on a case-insensitive string.

Uses the same hash algorithm as ast_str_hash, but converts all characters to lowercase prior to computing a hash. This allows for easy case-insensitive lookups in a hash table.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1250 of file strings.h.

References ast_str_hash_restrict().

Referenced by ast_channel_hash_cb(), ast_tone_zone_hash(), ast_xml_doc_item_hash(), autohint_hash_cb(), bridge_hash_cb(), cache_hash(), calendar_hash_fn(), cdr_all_hash_fn(), cdr_master_hash_fn(), channel_role_hash_cb(), channel_snapshot_hash_cb(), channel_snapshot_uniqueid_hash_cb(), conference_bridge_hash_cb(), config_opt_hash(), dialog_hash_cb(), featuregroup_hash(), format_hash_cb(), hint_hash(), hintdevice_hash_cb(), media_info_hash(), media_variant_hash(), menu_hash_cb(), moh_class_hash(), notify_option_hash(), peer_hash_cb(), pending_members_hash(), protocol_hash_fn(), pvt_hash_cb(), queue_hash_cb(), skel_level_hash(), subscription_statistics_hash(), topic_pool_entry_hash(), topic_statistics_hash(), tps_hash_cb(), and user_hash_cb().

 {
    unsigned int hash = 5381;
 
    while (*str) {
       hash = hash * 33 ^ (unsigned char) tolower(*str++);
    }
 
    return ast_str_hash_restrict(hash);
 }

◆ 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

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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_str_copy_string()

int ast_str_copy_string	(	struct ast_str **	dst,
		struct ast_str *	src
	)

inline

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 798 of file strings.h.

Referenced by copy_request().

801 { \

◆ ast_str_hash()

static force_inline int attribute_pure ast_str_hash ( const char * str )

static

Compute a hash value on a string.

This famous hash algorithm was written by Dan Bernstein and is commonly used.

http://www.cse.yorku.ca/~oz/hash.html

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1206 of file strings.h.

References ast_str_hash_restrict().

Referenced by alias_hash_cb(), app_hash(), ast_event_append_ie_str(), ast_get_namedgroups(), ast_sorcery_object_id_hash(), bridges_channel_hash_fn(), bridges_hash(), channel_hash(), control_hash(), datastore_hash(), db_hash_fn(), device_state_subscriptions_hash(), dsn_hash(), entry_hash_fn(), esc_hash_fn(), event_hash_fn(), event_session_hash(), exten_state_publisher_hash(), formatter_hash(), group_hash_fn(), hook_hash(), internal_state_hash(), jingle_add_ice_udp_candidates_to_transport(), jingle_endpoint_hash(), jingle_session_hash(), lang_hash_fn(), message_subscription_hash_cb(), monitored_transport_hash_fn(), mwi_sub_hash(), outbound_publish_state_hash(), parking_lot_cfg_hash_fn(), peer_hash_cb(), persistent_endpoint_hash(), playback_hash(), pvt_cause_hash_fn(), recording_hash(), registration_state_hash(), registry_hash_cb(), sdp_handler_list_hash(), sorcery_memory_cache_hash(), sorcery_memory_cached_object_hash(), sorcery_memory_hash(), stasis_sub_hash(), str_hash(), str_hash_fn(), suspects_hash(), test_vm_api_create_mock_snapshot(), transport_state_hash(), uid_hold_hash_fn(), user_hash_cb(), variable_count_hash_fn(), wait_bridge_hash_fn(), and xmpp_buddy_hash().

 {
    unsigned int hash = 5381;
 
    while (*str) {
       hash = hash * 33 ^ (unsigned char) *str++;
    }
 
    return ast_str_hash_restrict(hash);
 }

◆ ast_str_hash_add()

static force_inline int ast_str_hash_add	(	const char *	str,
		int	seed
	)

static

Compute a hash value on a string.

Parameters

[in]	str	The string to add to the hash
[in]	seed	The hash value to start with

This version of the function is for when you need to compute a string hash of more than one string.

This famous hash algorithm was written by Dan Bernstein and is commonly used.

See also: http://www.cse.yorku.ca/~oz/hash.html

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1232 of file strings.h.

References ast_str_hash_restrict().

 {
    unsigned int hash = (unsigned int) seed;
 
    while (*str) {
       hash = hash * 33 ^ (unsigned char) *str++;
    }
 
    return ast_str_hash_restrict(hash);
 }

◆ ast_str_hash_restrict()

static force_inline int attribute_pure ast_str_hash_restrict ( unsigned int hash )

static

Restrict hash value range.

Hash values used all over asterisk are expected to be non-negative (signed) int values. This function restricts an unsigned int hash value to the positive half of the (signed) int values.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1193 of file strings.h.

Referenced by ast_sip_get_distributor_serializer(), ast_str_case_hash(), ast_str_hash(), ast_str_hash_add(), and dialog_associations_hash().

 {
    return (int) (hash & (unsigned int) INT_MAX);
 }

◆ ast_str_reset()

void ast_str_reset ( struct ast_str * buf )

inline

Reset the content of a dynamic string. Useful before a series of ast_str_append.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 653 of file strings.h.

References buf.

Referenced by _sip_show_peer(), _sip_tcp_helper_thread(), _skinny_show_line(), acf_odbc_read(), action_userevent(), app_exec(), ast_cdr_serialize_variables(), ast_func_read2(), ast_get_character_str(), ast_get_digit_str(), ast_get_money_en_dollars_str(), ast_get_phonetic_str(), ast_logger_get_channels(), ast_odbc_print_errors(), ast_realtime_encode_chunk(), ast_str_encode_mime(), ast_str_substitute_variables_full(), ast_str_substring(), AST_TEST_DEFINE(), ast_translate_path_to_str(), authority_to_str(), build_peer(), CB_RESET(), cli_prompt(), config_text_file_load(), dbl_list_expect_forward(), dbl_list_expect_reverse(), detect_disconnect(), endelm(), file2display(), file_read(), function_db_keys(), get_content(), get_languages(), get_number_str_en(), handle_registrations(), handle_request_do(), handle_show_translation_path(), handle_start_element(), list_expect(), listfilter(), load_modules(), logger_add_verbose_magic(), mock_tcp_loop(), pbx_builtin_serialize_variables(), process_description_file(), read_config(), realtime_multi_odbc(), realtime_odbc(), realtimefield_read(), resource_list_recursive_decline(), set_rec_filename(), sip_tcptls_read(), sqlite3_escape_column_op(), sqlite3_escape_string_helper(), start_resource_list(), startelm(), strreplace(), substitute_escapes(), test_execute(), and user_authority_to_str().

660 {

◆ ast_str_set()

int ast_str_set	(	struct ast_str **	buf,
		ssize_t	max_len,
		const char *	fmt,
			...
	)

inline

Set a dynamic string using variable arguments.

Note: Care should be taken when using this function. The function can result in reallocating the ast_str. If a pointer to the ast_str is passed by value to a function that calls ast_str_set(), then the original ast_str pointer may be invalidated due to a reallocation.

Parameters

buf	This is the address of a pointer to a struct ast_str which should have been retrieved using ast_str_thread_get. It will need to be updated in the case that the buffer has to be reallocated to accomodate a longer string than what it currently has space for.
max_len	This is the maximum length to allow the string buffer to grow to. If this is set to 0, then there is no maximum length. If set to -1, we are bound to the current maximum length.
fmt	This is the format string (printf style)

Returns: The return value of this function is the same as that of the printf family of functions.

All the rest is the same as ast_str_set_va()

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 1065 of file strings.h.

References ast_str_append_va().

Referenced by __ast_format_cap_get_names(), __ast_http_post_load(), __ast_trace(), __manager_event_sessions_va(), __queues_show(), __sip_reliable_xmit(), acf_curl_exec(), acf_curl_helper(), acf_curlopt_helper(), action_agents(), action_createconfig(), add_bundle_groups(), add_cc_call_info_to_response(), add_crypto_to_stream(), add_hintdevice(), add_ice_to_stream(), add_rpid(), agent_handle_show_specific(), agent_show_requested(), analog_publish_dnd_state(), aocmessage_get_unit_entry(), ari_channels_handle_originate_with_id(), ast_ari_callback(), ast_extension_state2(), ast_http_auth(), ast_http_create_response(), ast_http_error(), ast_http_send(), ast_json_ipaddr(), ast_manager_build_bridge_state_string_prefix(), ast_manager_build_channel_state_string_prefix(), ast_monitor_stop(), ast_parse_digest(), ast_realtime_encode_chunk(), ast_regex_string_to_regex_pattern(), ast_sched_report(), ast_sip_append_body(), ast_sip_create_ami_event(), ast_sockaddr_stringify_fmt(), ast_sounds_get_index_for_file(), ast_str_encode_mime(), ast_str_expr(), ast_str_get_encoded_str(), ast_str_get_hint(), ast_str_quote(), ast_str_retrieve_variable(), ast_stream_create_resolved(), ast_strings_match(), AST_TEST_DEFINE(), ast_xmldoc_regenerate_doc_item(), astman_send_list_complete_start_common(), astman_send_response_full(), bs_to_exchange_bs(), build_notify(), build_path_data(), build_peer(), caldav_write_event(), cc_extension_monitor_init(), cc_generic_agent_start_monitoring(), cdata(), cdr_handler(), channel_hold_cb(), check_auth(), cli_list_subscriptions_detail(), cli_match_char_tree(), cli_odbc_read(), cli_prompt(), cli_show_subscriptions_detail(), config_curl(), config_mysql(), config_odbc(), config_pgsql(), create_channel_name(), destroy_curl(), destroy_mysql(), destroy_odbc(), destroy_pgsql(), device_state_notify_callbacks(), do_magic_pickup(), do_notify(), encmethods_to_str(), ewscal_write_event(), exchangecal_write_event(), extension_presence_state_helper(), extract_transferrer_headers(), file_count_line(), file_format(), find_aor(), find_realtime(), find_table(), func_headers_read2(), function_fieldnum_helper(), function_fieldqty_helper(), generate_exchange_uuid(), generate_uri(), get_ewscal_ids_for(), get_languages(), handle_call_token(), handle_cli_indication_show(), handle_manager_show_events(), handle_missing_table(), handle_show_translation_path(), handle_show_translation_table(), handle_uri(), hashkeys_read(), hashkeys_read2(), iax_parse_ies(), init_queue(), init_req(), init_resp(), initreqprep(), is_new_rec_file(), leave_voicemail(), listfilter(), log_attended_transfer(), log_jack_status(), make_email_file(), manager_bridge_info(), manager_bridge_tech_list(), manager_bridges_list(), manager_build_parked_call_string(), manager_json_array_with_key(), manager_json_obj_with_key(), meetme_cmd_helper(), meetme_show_cmd(), meetme_stasis_cb(), mwi_to_string(), my_load_config_string(), my_load_module(), mysql_log(), odbc_log(), parking_lot_cfg_create_extensions(), parse_ewscal_id(), parse_hint_device(), parse_hint_presence(), passthru(), pgsql_log(), pgsql_reconnect(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), presence_state_notify_callbacks(), print_queue(), process_description_file(), process_text_line(), publish_channel_alarm(), publish_channel_alarm_clear(), publish_dnd_state(), queue_set_param(), read_raw_content_length(), realtime_curl(), realtime_directory(), realtime_multi_curl(), realtime_multi_mysql(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_mysql(), realtime_odbc(), realtime_pgsql(), realtime_sqlite3_destroy(), realtime_sqlite3_helper(), realtime_sqlite3_store(), realtime_sqlite3_update(), realtime_sqlite3_update2(), realtime_update2_handler(), replace(), require_curl(), require_pgsql(), run_station(), search_directory_sub(), security_event_stasis_cb(), sendmail(), sendpage(), set_rec_filename(), shift_pop(), sip_report_security_event(), sip_tcptls_write(), sip_websocket_callback(), sipsock_read(), sorcery_function_read(), stackpeek_read(), startelm(), stasis_app_control_snoop(), static_callback(), statsmaker(), store_curl(), store_mysql(), store_odbc(), store_pgsql(), system_registry_to_ami(), test_2way_function(), test_chan_variable(), test_cli_generate_results(), test_files_create(), threadpool_alloc(), transmit_fake_auth_response(), transmit_info_dtmf(), try_calling(), unshift_push(), update2_curl(), update2_mysql(), update2_pgsql(), update2_prepare(), update_curl(), update_mysql(), update_odbc(), update_pgsql(), update_scoreboard(), varset_to_ami(), websocket_bad_request(), websocket_client_parse_uri(), xmldoc_build_documentation_item(), xmldoc_get_syntax_config_object(), and xmldoc_get_syntax_config_option().

1081 {

◆ ast_str_set_escapecommas()

char * ast_str_set_escapecommas	(	struct ast_str **	buf,
		ssize_t	maxlen,
		const char *	src,
		size_t	maxsrc
	)

inline

Set a dynamic string to a non-NULL terminated substring, with escaping of commas.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1021 of file strings.h.

References __ast_str_helper2().

Referenced by acf_curl_helper(), and realtimefield_read().

1025 {

◆ ast_str_set_substr()

char * ast_str_set_substr	(	struct ast_str **	buf,
		ssize_t	maxlen,
		const char *	src,
		size_t	maxsrc
	)

inline

Set a dynamic string to a non-NULL terminated substring.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1007 of file strings.h.

References __ast_str_helper2().

Referenced by ast_str_substitute_variables_full(), and set_rec_filename().

1011 {

◆ ast_str_set_va()

int ast_str_set_va	(	struct ast_str **	buf,
		ssize_t	max_len,
		const char *	fmt,
		va_list	ap
	)

inline

Set a dynamic string from a va_list.

Parameters

buf	This is the address of a pointer to a struct ast_str. If it is retrieved using ast_str_thread_get, the struct ast_threadstorage pointer will need to be updated in the case that the buffer has to be reallocated to accommodate a longer string than what it currently has space for.
max_len	This is the maximum length to allow the string buffer to grow to. If this is set to 0, then there is no maximum length.
fmt	This is the format string (printf style)
ap	This is the va_list

Returns: The return value of this function is the same as that of the printf family of functions.

Example usage (the first part is only for thread-local storage)

AST_THREADSTORAGE(my_str, my_str_init);
#define MY_STR_INIT_SIZE   128
...
void my_func(const char *fmt, ...)
{
     struct ast_str *buf;
     va_list ap;
     if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
          return;
     ...
     va_start(fmt, ap);
     ast_str_set_va(&buf, 0, fmt, ap);
     va_end(ap);
     printf("This is the string we just built: %s\n", buf->str);
     ...
}

Note: Care should be taken when using this function. The function can result in reallocating the ast_str. If a pointer to the ast_str is passed by value to a function that calls ast_str_set_va(), then the original ast_str pointer may be invalidated due to a reallocation.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 982 of file strings.h.

References _ast_str_helper.

Referenced by __ast_test_status_update(), __ast_test_suite_event_notify(), ao2_container_unregister(), ast_agi_send(), ast_statsd_log_full_va(), ast_statsd_log_string_va(), ast_str_append_escapecommas(), ast_test_debug(), AST_VECTOR(), ast_xmldoc_query(), astman_append(), astman_send_error_va(), format_log_message_ap(), and module_load_error().

997 {

◆ ast_str_size()

size_t ast_str_size ( const struct ast_str * buf )

inline

Returns the current maximum length (without reallocation) of the current buffer.

Parameters

buf	A pointer to the ast_str structure.

Return values

Current maximum length of the buffer.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 699 of file strings.h.

References buf.

Referenced by ari_channels_handle_originate_with_id(), ast_func_read(), ast_func_read2(), ast_odbc_ast_str_SQLGetData(), ast_str_get_encoded_str(), AST_TEST_DEFINE(), base64_helper(), blacklist_read2(), dialog_info_to_string(), handle_dbget(), load_config(), pbx_find_extension(), pidf_to_string(), realtime_multi_odbc(), realtime_odbc(), set2(), sqlite3_escape_column_op(), sqlite3_escape_string_helper(), string_tolower2(), string_toupper2(), write_to_ast_str(), and xpidf_to_string().

707 {

◆ ast_str_strlen()

size_t ast_str_strlen ( const struct ast_str * buf )

inline

Returns the current length of the string stored within buf.

Parameters

buf	A pointer to the ast_str structure.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 688 of file strings.h.

References buf.

Referenced by __sip_reliable_xmit(), __sip_xmit(), _ast_xmldoc_build_arguments(), _sip_tcp_helper_thread(), _xmldoc_build_field(), acf_curl_helper(), acf_odbc_read(), action_getconfig(), action_getconfigjson(), add_header(), add_required_respheader(), add_route(), ALLOC_COMMENT(), ast_agi_send(), ast_http_send(), ast_odbc_print_errors(), ast_statsd_log_string(), ast_str_encode_mime(), ast_str_expr(), ast_str_substitute_variables_full(), ast_str_substring(), AST_TEST_DEFINE(), ast_var_channels_table(), AST_VECTOR(), authority_to_str(), base64_helper(), blacklist_read2(), build_cc_interfaces_chanvar(), build_notify(), build_peer(), caldav_get_events_between(), caldav_request(), cc_extension_monitor_init(), cdata(), chanavail_exec(), check_message_integrity(), cli_show_module_options(), cli_show_module_type(), cli_show_module_types(), collect_names_cb(), config_mysql(), config_text_file_load(), configure_connection_charset(), copy_request(), cut_internal(), destroy_mysql(), detect_disconnect(), dump_queue_members(), encmethods_to_str(), endelm(), exchangecal_request(), fetch_icalendar(), finalize_content(), find_table(), function_fieldnum_helper(), function_fieldqty_helper(), generate_fmtp_attr(), get_key(), handle_cli_cdr_mysql_status(), handle_dbget(), handle_end_element(), handle_request_cancel(), handle_request_do(), handle_showchan(), hangupcause_keys_read(), hashkeys_read2(), http_callback(), initreqprep(), listfilter(), load_column_config(), load_config(), load_dlopen(), load_modules(), load_values_config(), lws2sws(), manager_log(), manager_sipnotify(), mock_tcp_loop(), my_connect_db(), my_load_module(), mysql_log(), odbc_log(), opus_generate_sdp_fmtp(), parse_request(), pgsql_log(), pgsql_reconnect(), pjsip_acf_dial_contacts_read(), print_uptimestr(), realtime_multi_mysql(), realtime_multi_odbc(), realtime_mysql(), realtime_odbc(), replace(), say_periodic_announcement(), send_ews_request_and_parse(), set_outbound_authentication_credentials(), set_rec_filename(), shift_pop(), sip_cli_notify(), sip_hangup(), sip_send_mwi_to_peer(), sip_tcptls_read(), store_mysql(), system_exec_helper(), test_create_joint(), transmit_invite(), unshift_push(), update2_mysql(), update_caldav(), update_exchangecal(), update_mysql(), user_authority_to_str(), write_cel(), write_to_ast_str(), xmldoc_get_formatted(), and xmldoc_parse_variable().

696 {

◆ ast_str_thread_get()

struct ast_str * ast_str_thread_get	(	struct ast_threadstorage *	ts,
		size_t	init_len
	)

Retrieve a thread locally stored dynamic string.

Parameters

ts	This is a pointer to the thread storage structure declared by using the AST_THREADSTORAGE macro. If declared with AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be (&my_buf).
init_len	This is the initial length of the thread's dynamic string. The current length may be bigger if previous operations in this thread have caused it to increase.

Returns: This function will return the thread locally stored dynamic string associated with the thread storage management variable passed as the first argument. The result will be NULL in the case of a memory allocation error.

Example usage:

AST_THREADSTORAGE(my_str, my_str_init);
#define MY_STR_INIT_SIZE   128
...
void my_func(const char *fmt, ...)
{
     struct ast_str *buf;
     if (!(buf = ast_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
          return;
     ...
}

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 861 of file strings.h.

References ast_str::__AST_STR_LEN, ast_str::__AST_STR_TS, ast_str::__AST_STR_USED, buf, make_ari_stubs::file, and NULL.

Referenced by __manager_event_sessions_va(), acf_curl_helper(), acf_odbc_read(), acf_odbc_write(), action_userevent(), add_hintdevice(), ao2_container_unregister(), ast_agi_send(), ast_extension_state2(), ast_odbc_print_errors(), ast_sockaddr_stringify_fmt(), ast_statsd_log_full_va(), ast_statsd_log_string_va(), AST_VECTOR(), astman_append(), astman_send_error_va(), astman_send_list_complete_start_common(), astman_send_response_full(), check_auth(), cli_odbc_read(), cli_odbc_write(), config_curl(), config_mysql(), config_odbc(), config_pgsql(), custom_log(), destroy_curl(), destroy_mysql(), destroy_odbc(), destroy_pgsql(), dumpchan_exec(), extension_presence_state_helper(), find_table(), format_log_message_ap(), function_fieldnum_helper(), function_fieldqty_helper(), get_content(), handle_showchan(), listfilter(), logger_add_verbose_magic(), mysql_log(), pbx_find_extension(), realtime_curl(), realtime_directory(), realtime_multi_curl(), realtime_multi_mysql(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_mysql(), realtime_odbc(), realtime_pgsql(), realtime_update2_handler(), realtimefield_read(), require_curl(), search_directory_sub(), security_event_stasis_cb(), shift_pop(), sip_report_security_event(), sqlite3_escape_column_op(), sqlite3_escape_string_helper(), store_curl(), store_mysql(), store_odbc(), store_pgsql(), strreplace(), substitute_escapes(), syslog_log(), system_exec_helper(), transmit_fake_auth_response(), unshift_push(), update2_curl(), update2_mysql(), update2_odbc(), update2_pgsql(), update2_prepare(), update_curl(), update_mysql(), update_odbc(), and update_pgsql().

866 {

◆ ast_str_to_lower()

static force_inline char* ast_str_to_lower ( char * str )

static

Convert a string to all lower-case.

Parameters

str	The string to be converted to lower case

Return values

str	for convenience

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1268 of file strings.h.

References str.

Referenced by apps_handler(), ast_ari_endpoints_send_message_to_endpoint(), ast_uuid_to_str(), build_contact(), cel_track_app(), curl_header_callback(), get_user_agent(), and parse_simple_message_summary().

 {
    char *str_orig = str;
    if (!str) {
       return str;
    }
 
    for (; *str; ++str) {
       *str = tolower(*str);
    }
 
    return str_orig;
 }

◆ ast_str_to_upper()

static force_inline char* ast_str_to_upper ( char * str )

static

Convert a string to all upper-case.

Parameters

str	The string to be converted to upper case

Return values

str	for convenience

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1289 of file strings.h.

References str.

Referenced by ast_rtp_engine_load_format().

 {
    char *str_orig = str;
    if (!str) {
       return str;
    }
 
    for (; *str; ++str) {
       *str = toupper(*str);
    }
 
    return str_orig;
 }

◆ ast_str_trim_blanks()

void ast_str_trim_blanks ( struct ast_str * buf )

inline

Trims trailing whitespace characters from an ast_str string.

Parameters

buf	A pointer to the ast_str string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 678 of file strings.h.

References buf.

Referenced by acf_curl_helper(), process_text_line(), and xmldoc_string_cleanup().

685 {

◆ ast_str_truncate()

char * ast_str_truncate	(	struct ast_str *	buf,
		ssize_t	len
	)

inline

Truncates the enclosed string to the given length.

Parameters

buf	A pointer to the ast_str structure.
len	Maximum length of the string. If len is larger than the current maximum length, things will explode. If it is negative at most -len characters will be trimmed off the end.

Return values

A	pointer to the resulting string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 738 of file strings.h.

Referenced by __test_cel_generate_peer_str(), _ast_xmldoc_build_arguments(), active_channels_to_str(), ast_regex_string_to_regex_pattern(), ast_str_substring(), build_cc_interfaces_chanvar(), cel_generate_peer_str(), check_message_integrity(), contacts_to_str(), func_headers_read2(), hashkeys_read2(), jack_str(), list_item_to_str(), opus_generate_sdp_fmtp(), pjsip_acf_dial_contacts_read(), send_eivr_event(), set_outbound_authentication_credentials(), set_var_to_str(), sorcery_function_read(), test_create_joint(), xmldoc_get_formatted(), and xmldoc_string_wrap().

759 {

◆ ast_str_update()

void ast_str_update ( struct ast_str * buf )

inline

Update the length of the buffer, after using ast_str merely as a buffer.

Parameters

buf	A pointer to the ast_str string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 663 of file strings.h.

References buf.

Referenced by ast_odbc_ast_str_SQLGetData(), ast_str_get_encoded_str(), ast_str_substring(), base64_helper(), blacklist_read2(), cli_show_subscription_common(), dialog_info_to_string(), handle_dbget(), lws2sws(), pidf_to_string(), realtime_multi_odbc(), realtime_odbc(), sqlite3_escape_column_op(), sqlite3_escape_string_helper(), string_tolower2(), string_toupper2(), and xpidf_to_string().

670 {

◆ 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.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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 "=".

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

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_strip()

char * ast_strip ( char * s )

inline

Strip leading/trailing whitespace from a string.

Parameters

s	The string to be stripped (will be modified).

Returns: The stripped string.

This functions strips all leading and trailing whitespace characters from the input string, and returns a pointer to the resulting string. The string is modified in place.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 219 of file strings.h.

Referenced by acf_if(), add_menu_entry(), add_peer_mailboxes(), ami_sip_qualify(), apps_handler(), aqm_exec(), ari_channels_handle_originate_with_id(), ast_ari_channels_create(), ast_callerid_parse(), ast_el_add_history(), ast_format_cap_update_by_allow_disallow(), ast_get_namedgroups(), ast_playtones_start(), ast_sip_auth_vector_init(), ast_sip_for_each_aor(), ast_sip_location_retrieve_contact_and_aor_from_list_filtered(), ast_strip_quoted(), ast_strsep(), ast_vector_string_split(), ast_websocket_uri_cb(), bridge_create_common(), build_calendar(), build_profile(), chanavail_exec(), check_blacklist(), check_via(), cli_qualify(), cli_reload_qualify_endpoint(), cli_show_qualify_endpoint(), config_parse_variables(), config_text_file_load(), create_unsolicited_mwi_subscriptions(), dial_exec_full(), eivr_comm(), events_handler(), find_aor(), find_aor_for_resource(), find_aor_name(), function_amiclient(), global_loaded(), h263_parse_sdp_fmtp(), h264_parse_sdp_fmtp(), header_identify_match_check(), ident_handler(), ip_identify_apply(), ip_identify_match_handler(), list_item_handler(), load_column_config(), load_config(), make_components(), mwi_on_aor(), mwi_validate_for_aor(), my_connect_db(), notify_endpoint(), page_exec(), parse_cookies(), parse_sip_options(), pbx_builtin_background(), pbx_load_config(), permanent_uri_handler(), pjsip_acf_dial_contacts_read(), process_echocancel(), process_text_line(), read_header(), realtime_multi_mysql(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_odbc(), realtime_pgsql(), reload_config(), reload_single_member(), send_unsolicited_mwi_notify(), set(), sip_options_synchronize_endpoint(), stir_shaken_read(), store_tone_zone_ring_cadence(), tls_method_to_str(), try_suggested_sip_codec(), and userevent_exec().

250 {

◆ ast_strip_quoted()

char* ast_strip_quoted	(	char *	s,
		const char *	beg_quotes,
		const char *	end_quotes
	)

Strip leading/trailing whitespace and quotes from a string.

Parameters

s	The string to be stripped (will be modified).
beg_quotes	The list of possible beginning quote characters.
end_quotes	The list of matching ending quote characters.

Returns: The stripped string.

This functions strips all leading and trailing whitespace characters from the input string, and returns a pointer to the resulting string. The string is modified in place.

It can also remove beginning and ending quote (or quote-like) characters, in matching pairs. If the first character of the string matches any character in beg_quotes, and the last character of the string is the matching character in end_quotes, then they are removed from the string.

Examples:

ast_strip_quoted(buf, "\"", "\"");
ast_strip_quoted(buf, "'", "'");
ast_strip_quoted(buf, "[{(", "]})");

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1639 of file main/utils.c.

References ast_strip().

Referenced by applicationmap_handler(), ast_callerid_parse(), ast_sip_validate_uri_length(), ast_strsep(), dialog_info_generate_body_content(), get_rdnis(), hfp_parse_clip(), iftime(), load_values_config(), parse_allowed_methods(), parse_cookies(), parse_dial_string(), pidf_allocate_body(), set_redirecting_reason(), sip_parse_register_line(), and xpidf_allocate_body().

 {
    char *e;
    char *q;
 
    s = ast_strip(s);
    if ((q = strchr(beg_quotes, *s)) && *q != '\0') {
       e = s + strlen(s) - 1;
       if (*e == *(end_quotes + (q - beg_quotes))) {
          s++;
          *e = '\0';
       }
    }
 
    return s;
 }

◆ ast_strsep()

char* ast_strsep	(	char **	s,
		const char	sep,
		uint32_t	flags
	)

Act like strsep but ignore separators inside quotes.

Parameters

s	Pointer to address of the string to be processed. Will be modified and can't be constant.
sep	A single character delimiter.
flags	Controls post-processing of the result. AST_STRSEP_TRIM trims all leading and trailing whitespace from the result. AST_STRSEP_STRIP does a trim then strips the outermost quotes. You may want to trim again after the strip. Just OR both the TRIM and STRIP flags. AST_STRSEP_UNESCAPE unescapes '\' sequences. AST_STRSEP_ALL does all of the above processing.

Returns: The next token or NULL if done or if there are more than 8 levels of nested quotes.

This function acts like strsep with three exceptions... The separator is a single character instead of a string. Separators inside quotes are treated literally instead of like separators. You can elect to have leading and trailing whitespace and quotes stripped from the result and have '\' sequences unescaped.

Like strsep, ast_strsep maintains no internal state and you can call it recursively using different separators on the same storage.

Also like strsep, for consistent results, consecutive separators are not collapsed so you may get an empty string as a valid result.

Examples:

char *mystr = ast_strdupa("abc=def,ghi='zzz=yyy,456',jkl");
char *token, *token2, *token3;
while((token = ast_strsep(&mystr, ',', AST_SEP_STRIP))) {
  // 1st token will be aaa=def
  // 2nd token will be ghi='zzz=yyy,456'
  while((token2 = ast_strsep(&token, '=', AST_SEP_STRIP))) {
     // 1st token2 will be ghi
     // 2nd token2 will be zzz=yyy,456
     while((token3 = ast_strsep(&token2, ',', AST_SEP_STRIP))) {
        // 1st token3 will be zzz=yyy
        // 2nd token3 will be 456
        // and so on
     }
  }
  // 3rd token will be jkl
}

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1656 of file main/utils.c.

References ast_strip(), ast_strip_quoted(), ast_strlen_zero, AST_STRSEP_STRIP, AST_STRSEP_TRIM, AST_STRSEP_UNESCAPE, ast_unescape_quoted(), and NULL.

Referenced by AST_TEST_DEFINE(), does_category_match(), handle_updates(), originate_exec(), test_xml_entry(), and wizard_apply_handler().

 {
    char *st = *iss;
    char *is;
    int inquote = 0;
    int found = 0;
    char stack[8];
 
    if (ast_strlen_zero(st)) {
       return NULL;
    }
 
    memset(stack, 0, sizeof(stack));
 
    for(is = st; *is; is++) {
       if (*is == '\\') {
          if (*++is != '\0') {
             is++;
          } else {
             break;
          }
       }
 
       if (*is == '\'' || *is == '"') {
          if (*is == stack[inquote]) {
             stack[inquote--] = '\0';
          } else {
             if (++inquote >= sizeof(stack)) {
                return NULL;
             }
             stack[inquote] = *is;
          }
       }
 
       if (*is == sep && !inquote) {
          *is = '\0';
          found = 1;
          *iss = is + 1;
          break;
       }
    }
    if (!found) {
       *iss = NULL;
    }
 
    if (flags & AST_STRSEP_STRIP) {
       st = ast_strip_quoted(st, "'\"", "'\"");
    }
 
    if (flags & AST_STRSEP_TRIM) {
       st = ast_strip(st);
    }
 
    if (flags & AST_STRSEP_UNESCAPE) {
       ast_unescape_quoted(st);
    }
 
    return st;
 }

◆ ast_tech_to_upper()

char * ast_tech_to_upper ( char * dev_str )

inline

Convert the tech portion of a device string to upper case.

Return values

dev_str Returns the char* passed in for convenience

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1183 of file strings.h.

Referenced by ast_endpoint_latest_snapshot(), create_new_generic_list(), find_generic_monitor_instance_list(), pvt_cause_cmp_fn(), and pvt_cause_hash_fn().

1194 {

◆ ast_to_camel_case_delim()

char* ast_to_camel_case_delim	(	const char *	s,
		const char *	delim
	)

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 2149 of file main/utils.c.

References ast_copy_string(), ast_strdup, and NULL.

 {
    char *res = ast_strdup(s);
    char *front, *back, *buf = res;
    int size;
 
    front = strtok_r(buf, delim, &back);
 
    while (front) {
       size = strlen(front);
       *front = toupper(*front);
       ast_copy_string(buf, front, size + 1);
       buf += size;
       front = strtok_r(NULL, delim, &back);
    }
 
    return res;
 }

◆ ast_trim_blanks()

char * ast_trim_blanks ( char * str )

inline

Trims trailing whitespace characters from a string.

Parameters

str	the input string

Returns: a pointer to the modified string

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 182 of file strings.h.

References str.

Referenced by ast_get_namedgroups(), ast_http_header_parse(), ast_skip_nonblanks(), callerid_write(), connectedline_write(), curl_header_callback(), determine_firstline_parts(), do_say(), http_body_discard_chunk_trailer_headers(), http_request_headers_get(), keypad_cfg_read(), load_config(), parse_line(), party_id_write(), party_name_write(), party_number_write(), party_subaddress_write(), process_description_file(), redirecting_write(), set_message_vars_from_req(), show_entry_history(), user_event_hook_cb(), and xml_translate().

191 {

◆ ast_true()

int attribute_pure ast_true ( const char * val )

Make sure something is true. Determine if a string containing a boolean value is "true". This function checks to see whether a string passed to it is an indication of an "true" value. It checks to see if the string is "yes", "true", "y", "t", "on" or "1".

Return values

0	if val is a NULL pointer.
-1	if "true".
0	otherwise.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1951 of file main/utils.c.

References ast_strlen_zero.

Referenced by __ast_http_load(), __init_manager(), _parse(), acf_curlopt_write(), acf_faxopt_write(), acf_transaction_write(), action_agent_logoff(), action_originate(), action_status(), action_updateconfig(), actual_load_config(), agent_login_channel_config(), announce_user_count_all_handler(), aoc_cli_debug_enable(), apply_general_options(), apply_option(), ast_ari_bridges_add_channel_cb(), ast_ari_bridges_record_cb(), ast_ari_channels_record_cb(), ast_ari_events_event_websocket_ws_attempted_cb(), ast_ari_events_event_websocket_ws_established_cb(), ast_bridge_timelimit(), ast_jb_read_conf(), ast_rtp_dtls_cfg_parse(), AST_TEST_DEFINE(), ast_tls_read_conf(), autopause2int(), bool_handler_fn(), boolflag_handler_fn(), build_calendar(), build_device(), build_gateway(), build_peer(), build_user(), cdr_prop_write_callback(), check_debug(), client_bitfield_handler(), config_parse_variables(), custom_bitfield_handler(), customopt_handler(), dahdi_cc_callback(), dahdi_set_dnd(), destroy_all_channels(), do_reload(), encoding_format_handler(), festival_exec(), func_channel_write_real(), func_mute_write(), function_ooh323_write(), get_encrypt_methods(), global_bitfield_handler(), handle_clear_alarms(), handle_common_options(), handle_logger_set_level(), handle_queue_set_member_ringinuse(), handle_t38_options(), hook_write(), init_logger_chain(), internal_feature_write(), is_variable_true(), load_asterisk_conf(), load_config(), load_config_meetme(), load_module(), load_moh_classes(), load_odbc_config(), loader_config_init(), manager_add_queue_member(), manager_dialplan_extension_add(), manager_mute_mixmonitor(), manager_mutestream(), manager_pause_queue_member(), manager_play_dtmf(), manager_queue_member_ringinuse(), mbl_load_adapter(), mbl_load_device(), message_template_build(), misdn_answer(), moh_parse_options(), my_load_module(), new_realtime_sqlite3_db(), odbc_load_module(), osp_load(), osplookup_exec(), parse_config(), parse_empty_options(), parse_line(), parse_playtone(), pbx_builtin_saycharacters(), pbx_builtin_saycharacters_case(), pbx_builtin_saydigits(), pbx_builtin_saymoney(), pbx_builtin_saynumber(), pbx_builtin_sayphonetic(), pbx_load_config(), pbx_load_users(), pjsip_acf_moh_passthrough_write(), pjsip_set_logger_verbose(), prack_handler(), process_dahdi(), process_echocancel(), process_my_load_module(), profile_set_param(), queue_rules_set_global_params(), queue_set_global_params(), queue_set_param(), realtime_directory(), reload(), reload_config(), reload_followme(), reload_module(), reload_single_member(), rt_handle_member_record(), rtp_reload(), run_agi(), run_startup_commands(), sayunixtime_exec(), search_directory(), search_directory_sub(), set_active(), set_config(), sla_load_config(), smdi_load(), sorcery_config_open(), sorcery_memory_cache_ami_stale_object(), sorcery_memory_cache_open(), speex_write(), stackpeek_read(), start_monitor_action(), strings_to_mask(), tds_load_module(), timers_handler(), transport_tls_bool_handler(), xfer_set(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_config_object(), xmldoc_get_syntax_fun(), and xmldoc_get_syntax_manager().

 {
    if (ast_strlen_zero(s))
       return 0;
 
    /* Determine if this is a true value */
    if (!strcasecmp(s, "yes") ||
        !strcasecmp(s, "true") ||
        !strcasecmp(s, "y") ||
        !strcasecmp(s, "t") ||
        !strcasecmp(s, "1") ||
        !strcasecmp(s, "on"))
       return -1;
 
    return 0;
 }

◆ ast_unescape_c()

char* ast_unescape_c ( char * s )

Convert some C escape sequences.

(\b\f\n\r\t)

into the equivalent characters. The string to be converted (will be modified).

Returns: The converted string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1735 of file main/utils.c.

References c, and NULL.

Referenced by ast_parse_digest().

 {
    char c, *ret, *dst;
 
    if (src == NULL)
       return NULL;
    for (ret = dst = src; (c = *src++); *dst++ = c ) {
       if (c != '\\')
          continue;   /* copy char at the end of the loop */
       switch ((c = *src++)) {
       case '\0':  /* special, trailing '\' */
          c = '\\';
          break;
       case 'b':   /* backspace */
          c = '\b';
          break;
       case 'f':   /* form feed */
          c = '\f';
          break;
       case 'n':
          c = '\n';
          break;
       case 'r':
          c = '\r';
          break;
       case 't':
          c = '\t';
          break;
       }
       /* default, use the char literally */
    }
    *dst = '\0';
    return ret;
 }

◆ ast_unescape_semicolon()

char* ast_unescape_semicolon ( char * s )

Strip backslash for "escaped" semicolons, the string to be stripped (will be modified).

Returns: The stripped string.

Examples:: /usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 1716 of file main/utils.c.

Referenced by sip_cli_notify().

 {
    char *e;
    char *work = s;
 
    while ((e = strchr(work, ';'))) {
       if ((e > work) && (*(e-1) == '\\')) {
          memmove(e - 1, e, strlen(e) + 1);
          work = e;
       } else {
          work = e + 1;
       }
    }
 
    return s;
 }

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ __AST_STR_LEN

◆ __AST_STR_STR

◆ __AST_STR_TS

◆ __AST_STR_USED

◆ _ast_str_helper

◆ _DB1

◆ AS_OR

◆ ast_join

◆ ast_str_alloca

◆ ast_str_container_alloc

◆ ast_str_create

◆ ast_str_make_space

◆ ast_str_tmp

◆ ast_strlen_zero

◆ ast_to_camel_case

◆ AST_YESNO

◆ DS_ALLOCA

◆ DS_MALLOC

◆ DS_STATIC

◆ S_COR

◆ S_OR

Enumeration Type Documentation

◆ anonymous enum

◆ ast_strsep_flags

Function Documentation

◆ __ast_str_helper()

◆ __ast_str_helper2()

◆ _ast_str_create()

◆ _ast_str_make_space()

◆ _ast_strlen_zero()

◆ ast_begins_with()

◆ ast_build_string()

◆ ast_build_string_va()

◆ ast_check_digits()

◆ ast_copy_string()

◆ ast_ends_with()

◆ ast_escape()

◆ ast_escape_alloc()

◆ ast_escape_c()

◆ ast_escape_c_alloc()

◆ ast_false()

◆ ast_generate_random_string()

◆ ast_get_time_t()

◆ ast_get_timeval()

◆ ast_join_delim()

◆ ast_read_line_from_buffer()

◆ ast_regex_string_to_regex_pattern()

◆ ast_skip_blanks()

◆ ast_skip_nonblanks()

◆ ast_str_append()

◆ ast_str_append_escapecommas()

◆ ast_str_append_substr()

◆ ast_str_append_va()

◆ ast_str_buffer()

◆ ast_str_case_hash()

◆ ast_str_container_add()

◆ ast_str_container_alloc_options()

◆ ast_str_container_remove()

◆ ast_str_copy_string()

◆ ast_str_hash()

◆ ast_str_hash_add()

◆ ast_str_hash_restrict()

◆ ast_str_reset()

◆ ast_str_set()

◆ ast_str_set_escapecommas()

◆ ast_str_set_substr()

◆ ast_str_set_va()

◆ ast_str_size()

◆ ast_str_strlen()

◆ ast_str_thread_get()

◆ ast_str_to_lower()

◆ ast_str_to_upper()

◆ ast_str_trim_blanks()

◆ ast_str_truncate()