Thu Oct 11 06:50:28 2012

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, 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, 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 359 of file strings.h.


Field Documentation

size_t __AST_STR_LEN

The current maximum length of the string

Definition at line 360 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 366 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 362 of file strings.h.

Referenced by ast_str_thread_get().


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

Generated on Thu Oct 11 06:50:28 2012 for Asterisk - the Open Source PBX by  doxygen 1.5.6