Codename Pineapple

Home page | Mailing list | Docs

Last updated: Sat Feb 3 05:01:56 2007

Asterisk developer's documentation :: Codename Pineapple

include » asterisk

strings.h File Reference

Detailed Description

String manipulation functions.

Definition in file strings.h.

#include <string.h>
#include <stdarg.h>
#include "asterisk/inline_api.h"
#include "asterisk/compiler.h"
#include "asterisk/compat.h"
#include "asterisk/utils.h"
#include "asterisk/threadstorage.h"

Include dependency graph for strings.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_realloca
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, alloca() or static variables, all other values indicate a struct ast_threadstorage pointer. More...

Defines

#define _DB1(x)
#define ast_restrdupa(ra, s)
#define ast_str_alloca(init_len)
#define ast_str_append_va(buf, max_len, fmt, ap)
 Append to a dynamic string using a va_list.
#define ast_str_set_va(buf, max_len, fmt, ap)
 Set a dynamic string from a va_list.
#define DS_ALLOCA   ((struct ast_threadstorage *)2)
#define DS_MALLOC   ((struct ast_threadstorage *)1)
#define DS_STATIC   ((struct ast_threadstorage *)3)
#define S_OR(a, b)   (!ast_strlen_zero(a) ? (a) : (b))
 returns the equivalent of logic or for strings: first one if not empty, otherwise second one.

Functions

int __ast_str_helper (struct ast_str **buf, size_t max_len, int append, const char *fmt, va_list ap)
 Core functionality of ast_str_(set|append)_va.
size_t const char __attribute__ ((format(printf, 3, 4)))
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.
int ast_false (const char *val)
int ast_get_time_t (const char *src, time_t *dst, time_t _default, int *consumed)
 get values from config variables.
 AST_INLINE_API (int __attribute__((format(printf, 3, 4))) ast_str_set(struct ast_str **buf, size_t max_len, const char *fmt,...),{int res;va_list ap;va_start(ap, fmt);res=ast_str_set_va(buf, max_len, fmt, ap);va_end(ap);return res;}) AST_INLINE_API(int __attribute__((format(printf
 Set a dynamic string using variable argumentsAppend to a thread local dynamic string.
 AST_INLINE_API (struct ast_str *attribute_malloc ast_str_create(size_t init_len),{struct ast_str *buf;buf=(struct ast_str *) ast_calloc(1, sizeof(*buf)+init_len);if(buf==NULL) return NULL;buf->len=init_len;buf->used=0;buf->ts=DS_MALLOC;return buf;}) AST_INLINE_API(void ast_str_reset(struct ast_str *buf)
 Create a malloc'ed dynamic length stringReset the content of a dynamic string. Useful before a series of ast_str_append.
 AST_INLINE_API (void ast_copy_string(char *dst, const char *src, size_t size),{while(*src &&size){*dst++=*src++;size--;}if(__builtin_expect(!size, 0)) dst--;*dst= '\0';}) int ast_build_string(char **buffer
 Size-limited null-terminating string copy. Build a string in a buffer, designed to be called repeatedly.
 AST_INLINE_API (char *ast_skip_blanks(const char *str),{while(*str &&*str< 33) str++;return(char *) str;}) AST_INLINE_API(char *ast_trim_blanks(char *str)
 Gets a pointer to the first non-whitespace character in a string. Trims trailing whitespace characters from a string.
void ast_join (char *s, size_t len, char *const w[])
 ast_str_append (struct ast_str **buf, size_t max_len, const char *fmt,...)
static force_inline int ast_strlen_zero (const char *s)
int ast_true (const char *val)

Variables

size_t const char * fmt
size_t * space

Define Documentation

#define _DB1 (  x   ) 
 

#define ast_restrdupa (  ra,
s   ) 
 

Definition at line 254 of file strings.h.

#define ast_str_alloca (  init_len   ) 
 

Referenced by __manager_event(), action_listcommands(), handle_showchan(), handle_showmancmd(), handle_showmancmds(), and print_uptimestr().

#define ast_str_append_va (  buf,
max_len,
fmt,
ap   ) 
 

Append to a dynamic string using a va_list.

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

Definition at line 568 of file strings.h.

Referenced by __manager_event().

#define ast_str_set_va (  buf,
max_len,
fmt,
ap   ) 
 

Set a dynamic string from a va_list.

  • 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:
: the following two functions must be implemented as macros because we must do va_end()/va_start() on the original arguments.

Definition at line 552 of file strings.h.

Referenced by ast_cli(), ast_log(), ast_verbose(), and astman_append().

#define DS_ALLOCA   ((struct ast_threadstorage *)2)
 

Definition at line 317 of file strings.h.

#define DS_MALLOC   ((struct ast_threadstorage *)1)
 

Definition at line 316 of file strings.h.

#define DS_STATIC   ((struct ast_threadstorage *)3)
 

Definition at line 318 of file strings.h.

#define S_OR (  a,
b   )     (!ast_strlen_zero(a) ? (a) : (b))
 

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

Definition at line 45 of file strings.h.

Referenced by __login_exec(), __sip_show_channels(), _sip_show_device(), _sip_show_peer(), action_agents(), action_status(), agent_hangup(), aji_client_initialize(), aji_test(), allow_multiple_login(), ast_app_group_get_count(), ast_app_group_match_get_count(), ast_async_goto(), ast_cdr_end(), ast_cdr_free(), ast_cdr_init(), ast_cdr_start(), ast_cdr_update(), ast_cli_command(), ast_play_and_record_full(), ast_set_callerid(), ast_setstate(), build_callid_pvt(), build_callid_registry(), build_rpid(), builtin_automonitor(), check_post(), check_start(), do_parking_thread(), fast_originate(), get_also_info(), get_refer_info(), handle_chanlist(), handle_request_invite(), handle_showchan(), handle_showmancmd(), help1(), manager_parking_status(), moh_classes_show(), park_exec(), pbx_builtin_execiftime(), pgsql_reconnect(), post_cdr(), post_manager_event(), realtime_common(), realtime_exec(), register_peer_exten(), set_one_cid(), setup_env(), sip_show_domains(), sip_show_settings(), skinny_hold(), socket_process(), transmit_notify_with_mwi(), transmit_register(), zt_handle_event(), zt_hangup(), and zt_read().

Function Documentation

int __ast_str_helper (  struct ast_str **  buf,
size_t  max_len,
int  append,
const char *  fmt,
va_list  ap
) 
 

Core functionality of ast_str_(set|append)_va.

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

Definition at line 984 of file utils.c.

References ast_verbose(), and offset.

00986 {
00987    int res, need;
00988    int offset = (append && (*buf)->len) ? (*buf)->used : 0;
00989 
00990    if (max_len < 0)
00991       max_len = (*buf)->len;  /* don't exceed the allocated space */
00992    /*
00993     * Ask vsnprintf how much space we need. Remember that vsnprintf
00994     * does not count the final '\0' so we must add 1.
00995     */
00996    res = vsnprintf((*buf)->str + offset, (*buf)->len - offset, fmt, ap);
00997 
00998    need = res + offset + 1;
00999    /*
01000     * If there is not enough space and we are below the max length,
01001     * reallocate the buffer and return a message telling to retry.
01002     */
01003    if (need > (*buf)->len && (max_len == 0 || (*buf)->len < max_len) ) {
01004       if (max_len && max_len < need)   /* truncate as needed */
01005          need = max_len;
01006       else if (max_len == 0)  /* if unbounded, give more room for next time */
01007          need += 16 + need/4;
01008       if (0)   /* debugging */
01009          ast_verbose("extend from %d to %d\n", (int)(*buf)->len, need);
01010       if (ast_str_make_space(buf, need)) {
01011          ast_verbose("failed to extend from %d to %d\n", (int)(*buf)->len, need);
01012          return AST_DYNSTR_BUILD_FAILED;
01013       }
01014       (*buf)->str[offset] = '\0';   /* Truncate the partial write. */
01015 
01016       /* va_end() and va_start() must be done before calling
01017        * vsnprintf() again. */
01018       return AST_DYNSTR_BUILD_RETRY;
01019    }
01020    /* update space used, keep in mind the truncation */
01021    (*buf)->used = (res + offset > (*buf)->len) ? (*buf)->len : res + offset;
01022 
01023    return res;
01024 }

size_t const char __attribute__ (  (format(printf, 3, 4))   ) 
 

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

Definition at line 667 of file utils.c.

Referenced by ast_build_string().

00668 {
00669    int result;
00670 
00671    if (!buffer || !*buffer || !space || !*space)
00672       return -1;
00673 
00674    result = vsnprintf(*buffer, *space, fmt, ap);
00675 
00676    if (result < 0)
00677       return -1;
00678    else if (result > *space)
00679       result = *space;
00680 
00681    *buffer += result;
00682    *space -= result;
00683    return 0;
00684 }

int ast_false (  const char *  val  ) 
 

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

Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.

Definition at line 715 of file utils.c.

References ast_strlen_zero().

Referenced by aji_create_client(), aji_load_config(), ast_rtp_reload(), ast_udptl_reload(), build_device(), handle_common_options(), load_config(), reload_config(), and strings_to_mask().

00716 {
00717    if (ast_strlen_zero(s))
00718       return 0;
00719 
00720    /* Determine if this is a false value */
00721    if (!strcasecmp(s, "no") ||
00722        !strcasecmp(s, "false") ||
00723        !strcasecmp(s, "n") ||
00724        !strcasecmp(s, "f") ||
00725        !strcasecmp(s, "0") ||
00726        !strcasecmp(s, "off"))
00727       return -1;
00728 
00729    return 0;
00730 }

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

get values from config variables.

Definition at line 952 of file utils.c.

References ast_strlen_zero().

Referenced by build_device(), build_peer(), cache_lookup_internal(), handle_saydatetime(), and load_password().

00953 {
00954    long t;
00955    int scanned;
00956 
00957    if (dst == NULL)
00958       return -1;
00959 
00960    *dst = _default;
00961 
00962    if (ast_strlen_zero(src))
00963       return -1;
00964 
00965    /* only integer at the moment, but one day we could accept more formats */
00966    if (sscanf(src, "%ld%n", &t, &scanned) == 1) {
00967       *dst = t;
00968       if (consumed)
00969          *consumed = scanned;
00970       return 0;
00971    } else
00972       return -1;
00973 }

AST_INLINE_API (  int   __attribute__((format(printf, 3, 4))) ast_str_set(struct ast_str **buf, size_t max_len, const char *fmt,...)  ) 
 

Set a dynamic string using variable argumentsAppend to a thread local dynamic string.

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.

AST_INLINE_API (  struct ast_str *attribute_malloc   ast_str_create(size_t init_len)  ) 
 

Create a malloc'ed dynamic length stringReset the content of a dynamic string. Useful before a series of ast_str_append.

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

Size-limited null-terminating string copy. 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
Returns:
0 on success, non-zero on failure.

AST_INLINE_API (  char *  ast_skip_blanks(const char *str)  ) 
 

Gets a pointer to the first non-whitespace character in a string. Trims trailing whitespace characters from a string.

Parameters:
ast_trim_blanks function being used
str the input string
Returns:
a pointer to the modified string

void ast_join (  char *  s,
size_t  len,
char *const   w[]
) 
 

Definition at line 823 of file utils.c.

Referenced by __ast_cli_generator(), console_sendtext(), handle_agidumphtml(), handle_help(), handle_showagi(), help1(), help_workhorse(), and set_full_cmd().

00824 {
00825    int x, ofs = 0;
00826    const char *src;
00827 
00828    /* Join words into a string */
00829    if (!s)
00830       return;
00831    for (x = 0; ofs < len && w[x]; x++) {
00832       if (x > 0)
00833          s[ofs++] = ' ';
00834       for (src = w[x]; *src && ofs < len; src++)
00835          s[ofs++] = *src;
00836    }
00837    if (ofs == len)
00838       ofs--;
00839    s[ofs] = '\0';
00840 }

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

Referenced by __manager_event(), ast_cdr_serialize_variables(), authority_to_str(), httpstatus_callback(), pbx_builtin_serialize_variables(), print_uptimestr(), static_callback(), and xml_copy_escape().

static force_inline int ast_strlen_zero (  const char *  s  )  [static]
 

Definition at line 37 of file strings.h.

Referenced by __ast_callerid_generate(), __ast_cli_generator(), __ast_cli_register(), __ast_read(), __ast_request_and_dial(), __iax2_show_peers(), __login_exec(), __oh323_new(), _sip_show_device(), _sip_show_devices(), _sip_show_peer(), _sip_show_peers(), action_agent_logoff(), action_agents(), action_challenge(), action_command(), action_extensionstate(), action_getconfig(), action_getvar(), action_hangup(), action_mailboxcount(), action_mailboxstatus(), action_originate(), action_redirect(), action_sendtext(), action_setvar(), action_status(), action_timeout(), action_transfer(), action_transferhangup(), action_updateconfig(), action_waitevent(), action_zapdialoffhook(), action_zapdndoff(), action_zapdndon(), action_zapshowchannels(), add_agent(), add_realm_authentication(), add_sip_domain(), agent_call(), agent_devicestate(), agent_hangup(), agent_logoff_maintenance(), agent_new(), agent_read(), agent_request(), agents_show(), agents_show_online(), agi_exec_full(), alsa_new(), answer_exec_enable(), append_transaction(), apply_outgoing(), apply_peer(), ast_app_getdata(), ast_app_group_get_count(), ast_app_group_match_get_count(), ast_app_group_split_group(), ast_bridge_call(), ast_build_timing(), ast_cdr_copy_vars(), ast_cdr_getvar(), ast_cdr_getvar_internal(), ast_cdr_init(), ast_cdr_serialize_variables(), ast_cli_complete(), ast_db_gettree(), ast_dnsmgr_get(), ast_dnsmgr_lookup(), ast_explicit_goto(), ast_false(), ast_feature_interpret(), ast_frame_dump(), ast_get_time_t(), ast_iax2_new(), ast_is_valid_string(), ast_jb_read_conf(), ast_linear_stream(), ast_log(), ast_makesocket(), ast_module_check(), ast_monitor_change_fname(), ast_monitor_start(), ast_monitor_stop(), ast_park_call(), ast_parseable_goto(), ast_pbx_outgoing_app(), ast_pbx_outgoing_exten(), ast_privacy_set(), ast_remotecontrol(), ast_stream_and_wait(), ast_true(), ast_variable_delete(), ast_variable_update(), astman_get_variables(), astman_send_response_full(), async_wait(), attempt_thread(), authenticate(), authenticate_reply(), authenticate_verify(), autoanswer_complete(), begin_dial(), build_contact(), build_device(), build_gateway(), build_mapping(), build_peer(), build_reply_digest(), build_rpid(), build_user(), builtin_automonitor(), callerid_feed(), callerid_genmsg(), cb_events(), chan_misdn_log(), change_monitor_action(), check_access(), check_auth(), check_day(), check_dow(), check_goto_on_transfer(), check_month(), check_peer_ok(), check_sip_domain(), check_timerange(), check_user_full(), check_user_ok(), cli_audio_convert(), config_text_file_load(), console_dial(), console_sendtext(), copy_all_header(), copy_header(), copy_via_headers(), create_addr(), create_addr_from_peer(), destroy_endpoint(), destroy_trans(), do_immediate_setup(), do_message(), do_parking_thread(), do_pause_or_unpause(), does_peer_need_mwi(), dump_agents(), dundi_exec(), dundi_flags2str(), dundi_helper(), dundi_hint2str(), dundi_lookup_local(), dundi_query_thread(), dundi_show_mappings(), dundi_show_peer(), dundifunc_read(), enum_callback(), extract_uri(), fast_originate(), feature_exec_app(), find_call(), find_cli(), find_sdp(), find_sip_method(), find_via_branch(), func_check_sipdomain(), func_header_read(), function_agent(), get_also_info(), get_destination(), get_range(), get_rdnis(), get_refer_info(), get_timerange(), gtalk_new(), handle_chanlist(), handle_command_response(), handle_controlstreamfile(), handle_getvariable(), handle_orig(), handle_request(), handle_request_bye(), handle_request_info(), handle_request_invite(), handle_request_options(), handle_request_refer(), handle_request_subscribe(), handle_response(), handle_response_bye(), handle_response_refer(), handle_response_register(), handle_saydatetime(), handle_show_dialplan(), handle_soft_key_event_message(), handle_stimulus_message(), handle_updates(), httpd_helper_thread(), iax2_call(), iax2_datetime(), iax2_devicestate(), iax2_prov_app(), iax2_show_cache(), iax2_show_peer(), iax2_show_users(), iax_check_version(), iax_firmware_append(), is_prefix(), jb_choose_impl(), jingle_new(), launch_netscript(), load_config(), load_moh_classes(), local_ast_moh_start(), logger_print_normal(), loopback_subst(), make_filename(), make_logchannel(), manager_dbdel(), manager_dbdeltree(), manager_dbget(), manager_dbput(), manager_iax2_show_peers(), manager_jabber_send(), manager_park(), manager_parking_status(), manager_show_dialplan(), manager_show_dialplan_helper(), manager_sip_show_device(), manager_sip_show_devices(), manager_sip_show_peer(), manager_sip_show_peers(), match_or_create_dialog(), matchcid(), mgcp_call(), mgcp_hangup(), mgcp_new(), mgcp_request(), mgcp_ss(), mgcpsock_read(), misdn_answer(), misdn_call(), misdn_facility_exec(), misdn_request(), misdn_set_opt_exec(), moh2_exec(), nbs_alloc(), oh323_call(), oh323_request(), orig_app(), orig_exten(), oss_call(), oss_new(), ourdialogbranch(), park_exec(), parse(), parse_dial_string(), parse_register_contact(), parse_request(), parse_sip_options(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_execiftime(), pbx_builtin_gotoif(), pbx_builtin_gotoiftime(), pbx_builtin_hangup(), pbx_builtin_importvar(), pbx_builtin_resetcdr(), pbx_builtin_saynumber(), pbx_builtin_setvar(), pbx_builtin_waitexten(), pbx_checkcondition(), pbx_load_users(), pbx_substitute_variables_helper_full(), phone_call(), phone_new(), process_ast_dsp(), process_message(), process_sdp(), process_text_line(), read_agent_config(), read_config(), real_ctx(), realtime_exec(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_odbc(), realtime_pgsql(), realtime_update_peer(), register_peer_exten(), register_verify(), registry_rerequest(), reload_config(), replace_cid(), reply_digest(), reqprep(), reset_global_settings(), respprep(), set_address_from_contact(), set_agentbycallerid(), set_config(), set_one_cid(), setup_incoming_call(), setup_zap(), sip_addheader(), sip_hangup(), sip_new(), sip_poke_peer(), sip_register(), sip_request_call(), sip_sendtext(), sip_show_channel(), sip_show_user(), sip_sipredirect(), skinny_hold(), skinny_new(), skinny_register(), skinny_request(), skinny_ss(), socket_process(), spawn_mp3(), split_ext(), srv_callback(), ss_thread(), ssl_setup(), start_monitor_action(), start_monitor_exec(), static_callback(), stop_monitor_action(), strings_to_mask(), transmit_invite(), transmit_modify_request(), transmit_modify_with_sdp(), transmit_notify_request(), transmit_notify_request_with_callerid(), transmit_refer(), transmit_register(), transmit_request_with_auth(), try_firmware(), unalloc_sub(), update_call_counter(), update_registry(), wait_for_hangup(), word_match(), zt_call(), zt_handle_event(), and zt_hangup().

00038 {
00039    return (!s || (*s == '\0'));
00040 }

int ast_true (  const char *  val  ) 
 

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

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

Definition at line 698 of file utils.c.

References ast_strlen_zero().

Referenced by __ast_http_load(), __login_exec(), _parse(), action_agent_logoff(), action_originate(), action_updateconfig(), aji_create_client(), aji_load_config(), apply_outgoing(), ast_jb_read_conf(), build_device(), build_gateway(), build_peer(), build_user(), do_reload(), get_encrypt_methods(), gtalk_load_config(), handle_common_options(), handle_save_dialplan(), init_logger_chain(), init_manager(), jingle_load_config(), load_config(), load_module(), load_moh_classes(), pbx_load_config(), pbx_load_users(), read_agent_config(), reload(), reload_config(), set_config(), start_monitor_action(), strings_to_mask(), and update_common_options().

00699 {
00700    if (ast_strlen_zero(s))
00701       return 0;
00702 
00703    /* Determine if this is a true value */
00704    if (!strcasecmp(s, "yes") ||
00705        !strcasecmp(s, "true") ||
00706        !strcasecmp(s, "y") ||
00707        !strcasecmp(s, "t") ||
00708        !strcasecmp(s, "1") ||
00709        !strcasecmp(s, "on"))
00710       return -1;
00711 
00712    return 0;
00713 }

Variable Documentation

size_t const char* fmt
 

Definition at line 191 of file strings.h.

size_t* space
 

Definition at line 191 of file strings.h.

Referenced by ast_str2tos(), ast_tos2str(), dundi_decrypt(), phone_write_buf(), and xml_copy_escape().

Asterisk is a trademark for Digium, inc.. | Edvina.net | Asterisk.org | This documentation was generated with Doxygen