Thu Apr 16 06:48:56 2015

Asterisk developer's documentation


ast_str Struct Reference

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

#include <strings.h>

Collaboration diagram for ast_str:

Collaboration graph
[legend]

Data Fields

size_t __AST_STR_LEN
char __AST_STR_STR [0]
struct ast_threadstorage__AST_STR_TS
size_t __AST_STR_USED

Detailed Description

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.

Support for dynamic strings.

A dynamic string is just a C string prefixed by a few control fields that help setting/appending/extending it using a printf-like syntax.

One should never declare a variable with this type, but only a pointer to it, e.g.

struct ast_str *ds;

The pointer can be initialized with the following:

ds = ast_str_create(init_len); creates a malloc()'ed dynamic string;

ds = ast_str_alloca(init_len); creates a string on the stack (not very dynamic!).

ds = ast_str_thread_get(ts, init_len) creates a malloc()'ed dynamic string associated to the thread-local storage key ts

Finally, the string can be manipulated with the following:

ast_str_set(&buf, max_len, fmt, ...) ast_str_append(&buf, max_len, fmt, ...)

and their varargs variant

ast_str_set_va(&buf, max_len, ap) ast_str_append_va(&buf, max_len, ap)

Parameters:
max_len The maximum allowed capacity of the ast_str. Note that if the value of max_len is less than the current capacity of the ast_str (as returned by ast_str_size), then the parameter is effectively ignored. 0 means unlimited, -1 means "at most the available space"
Returns:
All the functions return <0 in case of error, or the length of the string added to the buffer otherwise. Note that in most cases where an error is returned, characters ARE written to the ast_str.

Definition at line 364 of file strings.h.


Field Documentation

size_t __AST_STR_LEN

The current maximum length of the string

Definition at line 365 of file strings.h.

Referenced by __ast_str_helper2(), ast_str_create(), ast_str_strlen(), and ast_str_thread_get().

char __AST_STR_STR[0]

The string buffer

Definition at line 371 of file strings.h.

Referenced by ast_str_buffer(), ast_str_create(), ast_str_reset(), ast_str_size(), and ast_str_update().

What kind of storage is this ?

Definition at line 367 of file strings.h.

Referenced by ast_str_thread_get().


The documentation for this struct was generated from the following file:

Generated on Thu Apr 16 06:48:56 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6