Variable length buffer library

Collaboration diagram for Variable length buffer library:

Data Structures
struct	ap_varbuf

Macros
#define	AP_VARBUF_UNKNOWN   APR_SIZE_MAX
#define	ap_varbuf_strcat(vb, str)   ap_varbuf_strmemcat(vb, str, strlen(str))

Functions
void	ap_varbuf_init (apr_pool_t *pool, struct ap_varbuf *vb, apr_size_t init_size)
void	ap_varbuf_grow (struct ap_varbuf *vb, apr_size_t new_size)
void	ap_varbuf_free (struct ap_varbuf *vb)
void	ap_varbuf_strmemcat (struct ap_varbuf *vb, const char *str, int len)
char *	ap_varbuf_pdup (apr_pool_t *p, struct ap_varbuf *vb, const char *prepend, apr_size_t prepend_len, const char *append, apr_size_t append_len, apr_size_t *new_len)
apr_status_t	ap_varbuf_regsub (struct ap_varbuf *vb, const char *input, const char *source, apr_size_t nmatch, ap_regmatch_t pmatch[], apr_size_t maxlen)
apr_status_t	ap_varbuf_cfg_getline (struct ap_varbuf *vb, ap_configfile_t *cfp, apr_size_t max_len)

Detailed Description

This set of functions provides resizable buffers. While the primary usage is with NUL-terminated strings, most functions also work with arbitrary binary data.

Macro Definition Documentation

ap_varbuf_strcat

#define ap_varbuf_strcat	(		vb,
			str
	)		ap_varbuf_strmemcat(vb, str, strlen(str))

Concatenate a string to an ap_varbuf.

Parameters

vb	Pointer to the ap_varbuf struct
str	The string to append

Note

vb->strlen will be set to the length of the new string

AP_VARBUF_UNKNOWN

#define AP_VARBUF_UNKNOWN   APR_SIZE_MAX

Function Documentation

ap_varbuf_cfg_getline()

apr_status_t ap_varbuf_cfg_getline	(	struct ap_varbuf *	vb,
		ap_configfile_t *	cfp,
		apr_size_t	max_len
	)

Read a line from an ap_configfile_t and append it to an ap_varbuf.

Parameters

vb	Pointer to the ap_varbuf struct
cfp	Pointer to the ap_configfile_t
max_len	Maximum line length, including leading/trailing whitespace

Returns

See ap_cfg_getline()

Note

vb->strlen will be set to the length of the line

If vb->strlen equals AP_VARBUF_UNKNOWN, it will be set to strlen(vb->buf) first.

ap_varbuf_free()

void ap_varbuf_free

(

struct ap_varbuf *

vb

)

Release memory from a ap_varbuf immediately, if possible. This allows to free large buffers before the corresponding pool is cleared. Only larger allocations using mem nodes will be freed.

Parameters

vb	Pointer to the ap_varbuf struct

Note

After ap_varbuf_free(), vb must not be used unless ap_varbuf_init() is called again.

ap_varbuf_grow()

void ap_varbuf_grow	(	struct ap_varbuf *	vb,
		apr_size_t	new_size
	)

Grow a resizable buffer. If the vb->buf cannot be grown in place, it will be reallocated and the first vb->strlen + 1 bytes of memory will be copied to the new location. If vb->strlen == AP_VARBUF_UNKNOWN, the whole buffer is copied.

Parameters

vb	Pointer to the ap_varbuf struct
new_size	The minimum new size of the buffer

Note

ap_varbuf_grow() will usually at least double vb->buf's size with every invocation in order to reduce reallocations.

ap_varbuf_grow() will use pool memory for small and allocator mem nodes for larger allocations.

ap_varbuf_grow() will call vb->pool's abort function if out of memory.

ap_varbuf_init()

void ap_varbuf_init	(	apr_pool_t *	pool,
		struct ap_varbuf *	vb,
		apr_size_t	init_size
	)

Initialize a resizable buffer. It is safe to re-initialize a previously used ap_varbuf. The old buffer will be released when the corresponding pool is cleared. The buffer remains usable until the pool is cleared, even if the ap_varbuf was located on the stack and has gone out of scope.

Parameters

pool	The pool to allocate small buffers from and to register the cleanup with
vb	Pointer to the ap_varbuf struct
init_size	The initial size of the buffer (see ap_varbuf_grow() for details)

ap_varbuf_pdup()

char* ap_varbuf_pdup	(	apr_pool_t *	p,
		struct ap_varbuf *	vb,
		const char *	prepend,
		apr_size_t	prepend_len,
		const char *	append,
		apr_size_t	append_len,
		apr_size_t *	new_len
	)

Duplicate an ap_varbuf's content into pool memory.

Parameters

p	The pool to allocate from
vb	The ap_varbuf to copy from
prepend	An optional buffer to prepend (may be NULL)
prepend_len	Length of prepend
append	An optional buffer to append (may be NULL)
append_len	Length of append
new_len	Where to store the length of the resulting string (may be NULL)

Returns

The new string

Note

ap_varbuf_pdup() uses vb->strlen to determine how much memory to copy. It works even if 0-bytes are embedded in vb->buf, prepend, or append.

If vb->strlen equals AP_VARBUF_UNKNOWN, it will be set to strlen(vb->buf).

ap_varbuf_regsub()

apr_status_t ap_varbuf_regsub	(	struct ap_varbuf *	vb,
		const char *	input,
		const char *	source,
		apr_size_t	nmatch,
		ap_regmatch_t	pmatch[],
		apr_size_t	maxlen
	)

Perform string substitutions based on regexp match, using an ap_varbuf. This function behaves like ap_pregsub(), but appends to an ap_varbuf instead of allocating the result from a pool.

Parameters

vb	The ap_varbuf to which the string will be appended
input	An arbitrary string containing $1 through $9. These are replaced with the corresponding matched sub-expressions
source	The string that was originally matched to the regex
nmatch	The nmatch returned from ap_pregex
pmatch	The pmatch array returned from ap_pregex
maxlen	The maximum string length to append to vb, 0 for unlimited

Returns

APR_SUCCESS if successful

Note

Just like ap_pregsub(), this function does not copy the part of *source before the matching part (i.e. the first pmatch[0].rm_so characters).

If vb->strlen equals AP_VARBUF_UNKNOWN, it will be set to strlen(vb->buf) first.

ap_varbuf_strmemcat()

void ap_varbuf_strmemcat	(	struct ap_varbuf *	vb,
		const char *	str,
		int	len
	)

Concatenate a string to an ap_varbuf. vb->strlen determines where the string is appended in the buffer. If vb->strlen == AP_VARBUF_UNKNOWN, the string will be appended at the first NUL byte in the buffer. If len == 0, ap_varbuf_strmemcat() does nothing.

Parameters

vb	Pointer to the ap_varbuf struct
str	The string to append; must be at least len bytes long
len	The number of characters of *str to concatenate to the buf

Note

vb->strlen will be set to the length of the new string

if len != 0, vb->buf will always be NUL-terminated