FFmpeg
Files | Data Structures | Macros | Functions | Variables

A buffer to print data progressively. More...

Files

file  bprint.h
 AVBPrint public header.
 

Data Structures

struct  AVBPrint
 

Macros

#define FF_PAD_STRUCTURE(name, size, ...)
 Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with future versions. More...
 

Functions

void av_bprint_init (AVBPrint *buf, unsigned size_init, unsigned size_max)
 Init a print buffer. More...
 
void av_bprint_init_for_buffer (AVBPrint *buf, char *buffer, unsigned size)
 Init a print buffer using a pre-existing buffer. More...
 
void av_bprintf (AVBPrint *buf, const char *fmt,...) av_printf_format(2
 Append a formatted string to a print buffer. More...
 
void void av_vbprintf (AVBPrint *buf, const char *fmt, va_list vl_arg)
 Append a formatted string to a print buffer. More...
 
void av_bprint_chars (AVBPrint *buf, char c, unsigned n)
 Append char c n times to a print buffer. More...
 
void av_bprint_append_data (AVBPrint *buf, const char *data, unsigned size)
 Append data to a print buffer. More...
 
void av_bprint_strftime (AVBPrint *buf, const char *fmt, const struct tm *tm)
 Append a formatted date and time to a print buffer. More...
 
void av_bprint_get_buffer (AVBPrint *buf, unsigned size, unsigned char **mem, unsigned *actual_size)
 Allocate bytes in the buffer for external use. More...
 
void av_bprint_clear (AVBPrint *buf)
 Reset the string to "" but keep internal allocated data. More...
 
static int av_bprint_is_complete (const AVBPrint *buf)
 Test if the print buffer is complete (not truncated). More...
 
int av_bprint_finalize (AVBPrint *buf, char **ret_str)
 Finalize a print buffer. More...
 
void av_bprint_escape (AVBPrint *dstbuf, const char *src, const char *special_chars, enum AVEscapeMode mode, int flags)
 Escape the content in src and append it to dstbuf. More...
 

Variables

char * str
 Buffer to print data progressively. More...
 
unsigned len
 length so far More...
 
unsigned size
 allocated memory More...
 
unsigned size_max
 maximum allocated memory More...
 
char reserved_internal_buffer [1]
 
struct AVBPrint AVBPrint
 

Max size special values

Convenience macros for special values for av_bprint_init() size_max parameter.

#define AV_BPRINT_SIZE_UNLIMITED   ((unsigned)-1)
 Buffer will be reallocated as necessary, with an amortized linear cost. More...
 
#define AV_BPRINT_SIZE_AUTOMATIC   1
 Use the exact size available in the AVBPrint structure itself. More...
 
#define AV_BPRINT_SIZE_COUNT_ONLY   0
 Do not write anything to the buffer, only calculate the total length. More...
 

Detailed Description

A buffer to print data progressively.

Macro Definition Documentation

◆ FF_PAD_STRUCTURE

#define FF_PAD_STRUCTURE (   name,
  size,
  ... 
)
Value:
struct ff_pad_helper_##name { __VA_ARGS__ }; \
typedef struct name { \
__VA_ARGS__ \
char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \
} name;
unsigned size
allocated memory
Definition: bprint.h:99

Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with future versions.

Definition at line 48 of file bprint.h.

◆ AV_BPRINT_SIZE_UNLIMITED

#define AV_BPRINT_SIZE_UNLIMITED   ((unsigned)-1)

Buffer will be reallocated as necessary, with an amortized linear cost.

Definition at line 111 of file bprint.h.

◆ AV_BPRINT_SIZE_AUTOMATIC

#define AV_BPRINT_SIZE_AUTOMATIC   1

Use the exact size available in the AVBPrint structure itself.

Thus ensuring no dynamic memory allocation. The internal buffer is large enough to hold a reasonable paragraph of text, such as the current paragraph.

Definition at line 118 of file bprint.h.

◆ AV_BPRINT_SIZE_COUNT_ONLY

#define AV_BPRINT_SIZE_COUNT_ONLY   0

Do not write anything to the buffer, only calculate the total length.

The write operations can then possibly be repeated in a buffer with exactly the necessary size (using size_init = size_max = AVBPrint.len + 1).

Definition at line 125 of file bprint.h.

Function Documentation

◆ av_bprint_init()

void av_bprint_init ( AVBPrint buf,
unsigned  size_init,
unsigned  size_max 
)

Init a print buffer.

Parameters
bufbuffer to init
size_initinitial size (including the final 0)
size_maxmaximum size;
  • 0 means do not write anything, just count the length
  • 1 is replaced by the maximum value for automatic storage any large value means that the internal buffer will be reallocated as needed up to that limit
  • -1 is converted to UINT_MAX, the largest limit possible. Check also AV_BPRINT_SIZE_* macros.

◆ av_bprint_init_for_buffer()

void av_bprint_init_for_buffer ( AVBPrint buf,
char *  buffer,
unsigned  size 
)

Init a print buffer using a pre-existing buffer.

The buffer will not be reallocated.

Parameters
bufbuffer structure to init
bufferbyte buffer to use for the string data
sizesize of buffer

◆ av_bprintf()

void av_bprintf ( AVBPrint buf,
const char *  fmt,
  ... 
)

Append a formatted string to a print buffer.

◆ av_vbprintf()

void void av_vbprintf ( AVBPrint buf,
const char *  fmt,
va_list  vl_arg 
)

Append a formatted string to a print buffer.

◆ av_bprint_chars()

void av_bprint_chars ( AVBPrint buf,
char  c,
unsigned  n 
)

Append char c n times to a print buffer.

◆ av_bprint_append_data()

void av_bprint_append_data ( AVBPrint buf,
const char *  data,
unsigned  size 
)

Append data to a print buffer.

param buf bprint buffer to use param data pointer to data param size size of data

◆ av_bprint_strftime()

void av_bprint_strftime ( AVBPrint buf,
const char *  fmt,
const struct tm *  tm 
)

Append a formatted date and time to a print buffer.

param buf bprint buffer to use param fmt date and time format string, see strftime() param tm broken-down time structure to translate

Note
due to poor design of the standard strftime function, it may produce poor results if the format string expands to a very long text and the bprint buffer is near the limit stated by the size_max option.

◆ av_bprint_get_buffer()

void av_bprint_get_buffer ( AVBPrint buf,
unsigned  size,
unsigned char **  mem,
unsigned *  actual_size 
)

Allocate bytes in the buffer for external use.

Parameters
[in]bufbuffer structure
[in]sizerequired size
[out]mempointer to the memory area
[out]actual_sizesize of the memory area after allocation; can be larger or smaller than size

◆ av_bprint_clear()

void av_bprint_clear ( AVBPrint buf)

Reset the string to "" but keep internal allocated data.

◆ av_bprint_is_complete()

static int av_bprint_is_complete ( const AVBPrint buf)
inlinestatic

Test if the print buffer is complete (not truncated).

It may have been truncated due to a memory allocation failure or the size_max limit (compare size and size_max if necessary).

Definition at line 215 of file bprint.h.

◆ av_bprint_finalize()

int av_bprint_finalize ( AVBPrint buf,
char **  ret_str 
)

Finalize a print buffer.

The print buffer can no longer be used afterwards, but the len and size fields are still valid.

  • [out] ret_str if not NULL, used to return a permanent copy of the buffer contents, or NULL if memory allocation fails; if NULL, the buffer is discarded and freed
    Returns
    0 for success or error code (probably AVERROR(ENOMEM))

◆ av_bprint_escape()

void av_bprint_escape ( AVBPrint dstbuf,
const char *  src,
const char *  special_chars,
enum AVEscapeMode  mode,
int  flags 
)

Escape the content in src and append it to dstbuf.

Parameters
dstbufalready inited destination bprint buffer
srcstring containing the text to escape
special_charsstring containing the special characters which need to be escaped, can be NULL
modeescape mode to employ, see AV_ESCAPE_MODE_* macros. Any unknown value for mode will be considered equivalent to AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without notice.
flagsflags which control how to escape, see AV_ESCAPE_FLAG_* macros

Variable Documentation

◆ str

char* str

Buffer to print data progressively.

The string buffer grows as necessary and is always 0-terminated. The content of the string is never accessed, and thus is encoding-agnostic and can even hold binary data.

Small buffers are kept in the structure itself, and thus require no memory allocation at all (unless the contents of the buffer is needed after the structure goes out of scope). This is almost as lightweight as declaring a local char buf[512].

The length of the string can go beyond the allocated size: the buffer is then truncated, but the functions still keep account of the actual total length.

In other words, AVBPrint.len can be greater than AVBPrint.size and records the total length of what would have been to the buffer if there had been enough memory.

Append operations do not need to be tested for failure: if a memory allocation fails, data stop being appended to the buffer, but the length is still updated. This situation can be tested with av_bprint_is_complete().

The AVBPrint.size_max field determines several possible behaviours:

  • size_max = -1 (= UINT_MAX) or any large value will let the buffer be reallocated as necessary, with an amortized linear cost.
  • size_max = 0 prevents writing anything to the buffer: only the total length is computed. The write operations can then possibly be repeated in a buffer with exactly the necessary size (using size_init = size_max = len + 1).
  • size_max = 1 is automatically replaced by the exact size available in the structure itself, thus ensuring no dynamic memory allocation. The internal buffer is large enough to hold a reasonable paragraph of text, such as the current paragraph. string so far

Definition at line 99 of file bprint.h.

◆ len

unsigned len

length so far

Examples
decode_audio.c.

Definition at line 99 of file bprint.h.

Referenced by av_strnlen(), and main().

◆ size

unsigned size

allocated memory

Examples
ffhash.c, hw_decode.c, and vaapi_encode.c.

Definition at line 99 of file bprint.h.

Referenced by decode_write(), and main().

◆ size_max

unsigned size_max

maximum allocated memory

Definition at line 99 of file bprint.h.

◆ reserved_internal_buffer

char reserved_internal_buffer[1]

Definition at line 99 of file bprint.h.

◆ AVBPrint