Asterisk - The Open Source Telephony Project  18.5.0
Data Fields
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_lenThe 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.
Examples:
/usr/src/asterisk-18.5.0/include/asterisk/strings.h, and /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 584 of file strings.h.

Field Documentation

◆ __AST_STR_LEN

size_t __AST_STR_LEN

The current maximum length of the string

Examples:
/usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 585 of file strings.h.

Referenced by __ast_str_helper2(), and ast_str_thread_get().

◆ __AST_STR_STR

char __AST_STR_STR[0]

The string buffer

Examples:
/usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 591 of file strings.h.

◆ __AST_STR_TS

struct ast_threadstorage* __AST_STR_TS

What kind of storage is this ?

Examples:
/usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 587 of file strings.h.

Referenced by ast_str_thread_get().

◆ __AST_STR_USED

size_t __AST_STR_USED

Amount of space used

Examples:
/usr/src/asterisk-18.5.0/include/asterisk/strings.h.

Definition at line 586 of file strings.h.

Referenced by ast_str_thread_get().


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