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:

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