Sat Nov 25 00:46:14 2006

Asterisk developer's documentation


strings.h File Reference

String manipulation functions. More...

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

Go to the source code of this file.

Data Structures

struct  ast_realloca

Defines

#define ast_restrdupa(ra, s)

Functions

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)
 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(char *str),{while(*str &&*str< 33) str++;return 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.
static force_inline int ast_strlen_zero (const char *s)
int ast_true (const char *val)
char * strcasestr (const char *, const char *)
char * strndup (const char *, size_t)
size_t strnlen (const char *, size_t)
uint64_t strtoq (const char *nptr, char **endptr, int base)
int vasprintf (char **strp, const char *fmt, va_list ap)

Variables

size_t const char * fmt
size_t * space


Detailed Description

String manipulation functions.

Definition in file strings.h.


Define Documentation

#define ast_restrdupa ra,
 ) 
 

Definition at line 220 of file strings.h.


Function Documentation

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

Referenced by get_unaligned_uint16(), get_unaligned_uint32(), put_unaligned_uint16(), and put_unaligned_uint32().

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 533 of file utils.c.

Referenced by ast_build_string(), and manager_event().

00534 {
00535    int result;
00536 
00537    if (!buffer || !*buffer || !space || !*space)
00538       return -1;
00539 
00540    result = vsnprintf(*buffer, *space, fmt, ap);
00541 
00542    if (result < 0)
00543       return -1;
00544    else if (result > *space)
00545       result = *space;
00546 
00547    *buffer += result;
00548    *space -= result;
00549    return 0;
00550 }

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 581 of file utils.c.

References ast_strlen_zero().

Referenced by ast_rtp_reload(), ast_strings_to_mask(), handle_common_options(), and pbx_load_module().

00582 {
00583    if (ast_strlen_zero(s))
00584       return 0;
00585 
00586    /* Determine if this is a false value */
00587    if (!strcasecmp(s, "no") ||
00588        !strcasecmp(s, "false") ||
00589        !strcasecmp(s, "n") ||
00590        !strcasecmp(s, "f") ||
00591        !strcasecmp(s, "0") ||
00592        !strcasecmp(s, "off"))
00593       return -1;
00594 
00595    return 0;
00596 }

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.

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

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

Definition at line 33 of file strings.h.

Referenced by __ast_callerid_generate(), __ast_cli_generator(), __build_step(), __iax2_show_peers(), __login_exec(), __oh323_new(), __sip_show_channels(), _sip_show_peer(), _sip_show_peers(), acf_curl_exec(), acf_strftime(), action_agent_callback_login(), action_agent_logoff(), action_agents(), action_command(), action_extensionstate(), action_getvar(), action_hangup(), action_listcommands(), action_mailboxcount(), action_mailboxstatus(), action_originate(), action_redirect(), action_setcdruserfield(), action_setvar(), action_status(), action_timeout(), action_transfer(), action_transferhangup(), action_zapdialoffhook(), action_zapdndoff(), action_zapdndon(), action_zapshowchannels(), add_realm_authentication(), add_sip_domain(), admin_exec(), adsi_exec(), adsi_message(), advanced_options(), agent_call(), agent_devicestate(), agent_hangup(), agent_new(), agent_read(), agent_request(), agents_show(), agi_exec_full(), alarmreceiver_exec(), alsa_new(), app_exec(), append_transaction(), apply_outgoing(), apply_peer(), aqm_exec(), ast_app_group_get_count(), ast_app_group_match_get_count(), ast_app_group_split_group(), ast_async_goto(), ast_bridge_call(), ast_build_timing(), ast_callerid_parse(), ast_cdr_answer(), ast_cdr_busy(), ast_cdr_copy_vars(), ast_cdr_end(), ast_cdr_failed(), ast_cdr_free(), ast_cdr_getvar(), ast_cdr_getvar_internal(), ast_cdr_init(), ast_cdr_serialize_variables(), ast_cdr_setapp(), ast_cdr_setdestchan(), ast_cdr_start(), ast_cdr_update(), ast_db_gettree(), ast_dnsmgr_get(), ast_dnsmgr_lookup(), ast_explicit_goto(), ast_extension_close(), ast_false(), ast_feature_interpret(), ast_fileexists(), ast_frame_dump(), ast_iax2_new(), ast_isphonenumber(), ast_linear_stream(), ast_log(), ast_makesocket(), ast_modem_new(), ast_monitor_change_fname(), ast_monitor_start(), ast_monitor_stop(), ast_openstream_full(), ast_openvstream(), ast_parseable_goto(), ast_pbx_outgoing_app(), ast_pbx_outgoing_exten(), ast_privacy_set(), ast_read(), ast_remotecontrol(), ast_serialize_showchan(), ast_set_callerid(), ast_strings_to_mask(), ast_true(), astman_get_variables(), astman_send_error(), astman_send_response(), async_wait(), attempt_thread(), auth_exec(), authenticate(), authenticate_reply(), authenticate_verify(), autoanswer_complete(), background_detect_exec(), build_contact(), build_device(), build_gateway(), build_mapping(), build_peer(), build_reply_digest(), build_rpid(), build_user(), builtin_atxfer(), builtin_automonitor(), builtin_blindtransfer(), builtin_function_cdr_read(), builtin_function_cdr_write(), builtin_function_checkmd5(), builtin_function_env_write(), builtin_function_if(), builtin_function_iftime(), builtin_function_math(), builtin_function_md5(), builtin_function_set(), builtin_function_uridecode(), builtin_function_uriencode(), callerid_feed(), callerid_genmsg(), callerid_write(), cb_events(), chan_misdn_log(), chanavail_exec(), change_monitor_action(), change_password_realtime(), channel_spy(), chanspy_exec(), check_access(), check_auth(), check_goto_on_transfer(), check_sip_domain(), check_user_full(), compile_script(), complete_show_applications(), conf_exec(), conf_run(), config_text_file_load(), console_dial(), console_sendtext(), controlplayback_exec(), copy_all_header(), copy_header(), copy_via_headers(), count_exec(), create_addr(), create_addr_from_peer(), csv_log(), curl_exec(), custom_log(), database_increment(), deltree_exec(), destroy_endpoint(), destroy_trans(), dial_exec_full(), dialout(), dictate_exec(), directory_exec(), disa_exec(), do_directory(), do_immediate_setup(), do_monitor(), dump_agents(), dumpchan_exec(), dundi_exec(), dundi_flags2str(), dundi_helper(), dundi_hint2str(), dundi_lookup_exec(), dundi_lookup_local(), dundi_query_thread(), dundi_show_mappings(), dundi_show_peer(), dundifunc_read(), enum_callback(), enumlookup_exec(), extract_uri(), fast_originate(), festival_exec(), find_call(), find_sdp(), find_sip_method(), forkcdr_exec(), forward_message(), func_check_sipdomain(), func_header_read(), function_db_exists(), function_db_read(), function_db_write(), function_enum(), function_eval(), function_fieldqty(), function_txtcidname(), get_callerid_ast(), get_cid_name(), get_day(), get_destination(), get_dow(), get_month(), get_rdnis(), get_refer_info(), get_timerange(), gosub_exec(), gosubif_exec(), group_check_exec(), group_count_exec(), group_count_function_read(), group_function_read(), group_function_write(), group_list_function_read(), group_match_count_exec(), group_match_count_function_read(), handle_chanlist(), handle_command_response(), handle_controlstreamfile(), handle_getvariable(), handle_request(), handle_request_bye(), handle_request_info(), handle_request_invite(), handle_request_options(), handle_request_refer(), handle_request_subscribe(), handle_response(), handle_response_register(), handle_saydatetime(), handle_show_dialplan(), handle_showchan(), has_voicemail(), hasvoicemail_exec(), hasvoicemail_internal(), i4l_dial(), i4l_init(), iax2_call(), iax2_datetime(), iax2_devicestate(), iax2_prov_app(), iax2_show_cache(), iax2_show_channels(), iax2_show_peer(), iax2_show_users(), iax_check_version(), iax_firmware_append(), ices_exec(), launch_monitor_thread(), launch_netscript(), leave_voicemail(), load_config(), load_moh_classes(), local_ast_moh_start(), log_events(), lookupblacklist_exec(), loopback_subst(), macro_exec(), make_logchannel(), manager_add_queue_member(), manager_dbget(), manager_event(), manager_iax2_show_peers(), manager_parking_status(), manager_pause_queue_member(), manager_queues_status(), manager_remove_queue_member(), manager_sip_show_peer(), manager_sip_show_peers(), matchcid(), math_exec(), md5_exec(), md5check_exec(), messagecount(), mgcp_call(), mgcp_hangup(), mgcp_new(), mgcp_request(), mgcp_ss(), mgcpsock_read(), misdn_answer(), misdn_call(), misdn_facility_exec(), misdn_new(), misdn_request(), misdn_set_opt_exec(), mixmonitor_exec(), moh2_exec(), moh_classes_show(), monitor_handle_owned(), mp3_exec(), nbs_alloc(), notify_new_message(), oh323_call(), oh323_request(), onedigit_goto(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), oss_new(), page_exec(), park_exec(), parkandannounce_exec(), parse(), parse_dial_string(), parse_register_contact(), parse_request(), parse_sip_options(), pbx_builtin_answer(), pbx_builtin_execiftime(), pbx_builtin_gotoif(), pbx_builtin_gotoiftime(), pbx_builtin_importvar(), pbx_builtin_resetcdr(), pbx_builtin_saynumber(), pbx_builtin_setglobalvar(), pbx_builtin_setlanguage(), pbx_builtin_setvar(), pbx_extension_helper(), pbx_substitute_variables_helper_full(), PGSQL_exec(), phone_call(), phone_new(), pickup_exec(), play_mailbox_owner(), play_message_callerid(), play_message_category(), play_message_datetime(), playback_exec(), post_cdr(), pqm_exec(), privacy_exec(), process_ast_dsp(), process_message(), process_sdp(), process_text_line(), process_token(), queue_exec(), queue_function_qac(), random_exec(), read_agent_config(), read_config(), read_exec(), readfile_exec(), realtime_exec(), realtime_multi_odbc(), realtime_odbc(), realtime_update_exec(), receive_ademco_contact_id(), record_exec(), register_peer_exten(), register_verify(), registry_rerequest(), reload_config(), reply_digest(), reqprep(), respprep(), retrydial_exec(), return_exec(), rpt_exec(), rqm_exec(), run_externnotify(), senddtmf_exec(), sendimage_exec(), sendmail(), sendpage(), sendtext_exec(), sendurl_exec(), session_do(), set_agentbycallerid(), set_member_paused(), setcallerid_exec(), setup_incoming_call(), sip_addheader(), sip_getheader(), sip_hangup(), sip_new(), sip_poke_peer(), sip_register(), sip_request_call(), sip_sendtext(), sip_show_channel(), sip_show_domains(), sip_show_settings(), sip_show_user(), sip_sipredirect(), skel_exec(), skinny_new(), skinny_register(), skinny_request(), skinny_ss(), socket_read(), softhangup_exec(), spawn_mp3(), srv_callback(), ss_thread(), start_monitor_action(), start_monitor_exec(), stop_monitor_action(), system_exec_helper(), testclient_exec(), testserver_exec(), transfer_exec(), transmit_invite(), transmit_modify_request(), transmit_modify_with_sdp(), transmit_notify_request(), transmit_notify_request_with_callerid(), transmit_notify_with_mwi(), transmit_refer(), transmit_register(), try_firmware(), txtcidname_exec(), unalloc_sub(), update_registry(), upqm_exec(), userevent_exec(), valid_exit(), vm_authenticate(), vm_box_exists(), vm_change_password(), vm_exec(), vm_execmain(), vm_options(), vmauthenticate(), vpb_new(), wait_for_answer(), wait_for_hangup(), zapateller_exec(), zt_call(), zt_handle_event(), zt_new(), and zt_read().

00034 {
00035    return (!s || (*s == '\0'));
00036 }

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 564 of file utils.c.

References ast_strlen_zero().

Referenced by __load_resource(), __login_exec(), _parse(), action_agent_callback_login(), action_agent_logoff(), action_originate(), action_setcdruserfield(), apply_option(), ast_readconfig(), ast_strings_to_mask(), build_device(), build_gateway(), build_peer(), build_user(), config_load(), dial_exec_full(), do_reload(), festival_exec(), function_ilink(), get_encrypt_methods(), handle_common_options(), init_logger_chain(), init_manager(), load_config(), load_module(), load_moh_classes(), loadconfigurationfile(), manager_add_queue_member(), manager_pause_queue_member(), odbc_load_module(), parse_config(), pbx_load_module(), queue_set_param(), read_agent_config(), reload_config(), reload_queues(), rpt_master(), set_config(), start_monitor_action(), and update_common_options().

00565 {
00566    if (ast_strlen_zero(s))
00567       return 0;
00568 
00569    /* Determine if this is a true value */
00570    if (!strcasecmp(s, "yes") ||
00571        !strcasecmp(s, "true") ||
00572        !strcasecmp(s, "y") ||
00573        !strcasecmp(s, "t") ||
00574        !strcasecmp(s, "1") ||
00575        !strcasecmp(s, "on"))
00576       return -1;
00577 
00578    return 0;
00579 }

char* strcasestr const char *  ,
const char * 
 

Definition at line 662 of file utils.c.

References ast_log(), LOG_ERROR, offset, and upper().

Referenced by do_directory(), find_sdp(), gettag(), handle_show_applications(), modlist_modentry(), parse_register_contact(), playback_exec(), reqprep(), and respprep().

00663 {
00664    char *u1, *u2;
00665    int u1len = strlen(haystack) + 1, u2len = strlen(needle) + 1;
00666 
00667    u1 = alloca(u1len);
00668    u2 = alloca(u2len);
00669    if (u1 && u2) {
00670       char *offset;
00671       if (u2len > u1len) {
00672          /* Needle bigger than haystack */
00673          return NULL;
00674       }
00675       offset = strstr(upper(haystack, u1, u1len), upper(needle, u2, u2len));
00676       if (offset) {
00677          /* Return the offset into the original string */
00678          return ((char *)((unsigned long)haystack + (unsigned long)(offset - u1)));
00679       } else {
00680          return NULL;
00681       }
00682    } else {
00683       ast_log(LOG_ERROR, "Out of memory\n");
00684       return NULL;
00685    }
00686 }

char* strndup const char *  ,
size_t 
 

Definition at line 703 of file utils.c.

References malloc, and strnlen().

00704 {
00705    size_t len = strnlen(s, n);
00706    char *new = malloc(len + 1);
00707 
00708    if (!new)
00709       return NULL;
00710 
00711    new[len] = '\0';
00712    return memcpy(new, s, len);
00713 }

size_t strnlen const char *  ,
size_t 
 

Definition at line 690 of file utils.c.

Referenced by strndup().

00691 {
00692    size_t len;
00693 
00694    for (len=0; len < n; len++)
00695       if (s[len] == '\0')
00696          break;
00697 
00698    return len;
00699 }

uint64_t strtoq const char *  nptr,
char **  endptr,
int  base
 

Definition at line 752 of file utils.c.

References LONG_MAX, LONG_MIN, and s.

00753 {
00754     const char *s;
00755     uint64_t acc;
00756     unsigned char c;
00757     uint64_t qbase, cutoff;
00758     int neg, any, cutlim;
00759 
00760     /*
00761      * Skip white space and pick up leading +/- sign if any.
00762      * If base is 0, allow 0x for hex and 0 for octal, else
00763      * assume decimal; if base is already 16, allow 0x.
00764      */
00765     s = nptr;
00766     do {
00767             c = *s++;
00768     } while (isspace(c));
00769     if (c == '-') {
00770             neg = 1;
00771             c = *s++;
00772     } else {
00773             neg = 0;
00774             if (c == '+')
00775                     c = *s++;
00776     }
00777     if ((base == 0 || base == 16) &&
00778         c == '\0' && (*s == 'x' || *s == 'X')) {
00779             c = s[1];
00780             s += 2;
00781             base = 16;
00782     }
00783     if (base == 0)
00784             base = c == '\0' ? 8 : 10;
00785 
00786     /*
00787      * Compute the cutoff value between legal numbers and illegal
00788      * numbers.  That is the largest legal value, divided by the
00789      * base.  An input number that is greater than this value, if
00790      * followed by a legal input character, is too big.  One that
00791      * is equal to this value may be valid or not; the limit
00792      * between valid and invalid numbers is then based on the last
00793      * digit.  For instance, if the range for quads is
00794      * [-9223372036854775808..9223372036854775807] and the input base
00795      * is 10, cutoff will be set to 922337203685477580 and cutlim to
00796      * either 7 (neg==0) or 8 (neg==1), meaning that if we have
00797      * accumulated a value > 922337203685477580, or equal but the
00798      * next digit is > 7 (or 8), the number is too big, and we will
00799      * return a range error.
00800      *
00801      * Set any if any `digits' consumed; make it negative to indicate
00802      * overflow.
00803      */
00804     qbase = (unsigned)base;
00805     cutoff = neg ? (uint64_t)-(LONG_MIN + LONG_MAX) + LONG_MAX : LONG_MAX;
00806     cutlim = cutoff % qbase;
00807     cutoff /= qbase;
00808     for (acc = 0, any = 0;; c = *s++) {
00809             if (!isascii(c))
00810                     break;
00811             if (isdigit(c))
00812                     c -= '\0';
00813             else if (isalpha(c))
00814                     c -= isupper(c) ? 'A' - 10 : 'a' - 10;
00815             else
00816                     break;
00817             if (c >= base)
00818                     break;
00819             if (any < 0 || acc > cutoff || (acc == cutoff && c > cutlim))
00820                     any = -1;
00821             else {
00822                     any = 1;
00823                     acc *= qbase;
00824                     acc += c;
00825             }
00826     }
00827     if (any < 0) {
00828             acc = neg ? LONG_MIN : LONG_MAX;
00829     } else if (neg)
00830             acc = -acc;
00831     if (endptr != 0)
00832             *((const char **)endptr) = any ? s - 1 : nptr;
00833     return acc;
00834 }

int vasprintf char **  strp,
const char *  fmt,
va_list  ap
 

Definition at line 717 of file utils.c.

References malloc, and s.

00718 {
00719    int size;
00720    va_list ap2;
00721    char s;
00722 
00723    *strp = NULL;
00724    va_copy(ap2, ap);
00725    size = vsnprintf(&s, 1, fmt, ap2);
00726    va_end(ap2);
00727    *strp = malloc(size + 1);
00728    if (!*strp)
00729       return -1;
00730    vsnprintf(*strp, size + 1, fmt, ap);
00731 
00732    return size;
00733 }


Variable Documentation

size_t const char* fmt
 

Definition at line 179 of file strings.h.

Referenced by __oh323_new(), ast_cdr_getvar(), ast_openvstream(), ast_request(), check_header(), do_chanreads(), local_new(), mgcp_new(), setformat(), sip_new(), skinny_new(), try_suggested_sip_codec(), vpb_write(), and write_header().

size_t* space
 

Definition at line 179 of file strings.h.

Referenced by dundi_decrypt(), and phone_write_buf().


Generated on Sat Nov 25 00:46:14 2006 for Asterisk - the Open Source PBX by  doxygen 1.4.6