Buffer handling

Data Structures
struct	apr_buffer_t

Macros
#define	APR_BUFFER_STRING   (-1)
#define	APR_BUFFER_PLAIN   0
#define	APR_BUFFER_BASE64   1

Typedefs
typedef void *(*	apr_buffer_alloc) (void *ctx, apr_size_t size)

Functions
apr_status_t	apr_buffer_mem_set (apr_buffer_t *buf, void *mem, apr_size_t len)
apr_status_t	apr_buffer_mem_create (apr_buffer_t **mb, apr_pool_t *pool, void *mem, apr_size_t len)
apr_status_t	apr_buffer_str_set (apr_buffer_t *buf, char *str, apr_ssize_t len)
apr_status_t	apr_buffer_str_create (apr_buffer_t **sb, apr_pool_t *pool, char *str, apr_ssize_t len)
apr_status_t	apr_buffer_null_create (apr_buffer_t **nb, apr_pool_t *pool)
int	apr_buffer_is_null (const apr_buffer_t *buf)
int	apr_buffer_is_str (const apr_buffer_t *buf)
char *	apr_buffer_str (const apr_buffer_t *buf)
char *	apr_buffer_pstrdup (apr_pool_t *pool, const apr_buffer_t *buf)
void *	apr_buffer_mem (const apr_buffer_t *buf, apr_size_t *size)
void *	apr_buffer_pmemdup (apr_pool_t *pool, const apr_buffer_t *buf, apr_size_t *size)
apr_size_t	apr_buffer_len (const apr_buffer_t *buf)
apr_size_t	apr_buffer_allocated (const apr_buffer_t *buf)
apr_status_t	apr_buffer_arraydup (apr_buffer_t **out, const apr_buffer_t *in, apr_buffer_alloc alloc, void *ctx, int nelts)
apr_status_t	apr_buffer_dup (apr_buffer_t **out, const apr_buffer_t *in, apr_buffer_alloc alloc, void *ctx)
apr_buffer_t *	apr_buffer_cpy (apr_buffer_t *dst, const apr_buffer_t *src, apr_buffer_alloc alloc, void *ctx)
int	apr_buffer_cmp (const apr_buffer_t *dst, const apr_buffer_t *src)
char *	apr_buffer_pstrncat (apr_pool_t *p, const apr_buffer_t *buf, int nelts, const char *sep, int flags, apr_size_t *nbytes)

Detailed Description

An APR buffer is a structure that can contain a zero terminated string, or a non zero terminated block of memory, and allow such structures to be passed around and handled in a memory efficient way.

We allow two buffers to be compared without duplicating strings. Memory buffers can be converted to string buffers safely. The contents of buffers can be copied into and out of other systems like caches using memory allocation callbacks.

Macro Definition Documentation

APR_BUFFER_BASE64

#define APR_BUFFER_BASE64   1

Perform base64 encoding on memory buffers during apr_buffer_pstrcat().

APR_BUFFER_PLAIN

#define APR_BUFFER_PLAIN   0

Perform no encoding on memory buffers during apr_buffer_pstrcat().

APR_BUFFER_STRING

#define APR_BUFFER_STRING   (-1)

When passing a string to apr_buffer_str_create or apr_buffer_str_set, this value can be passed to indicate a string with unknown length, and have apr_buffer_str_create and apr_buffer_str_set compute the length automatically.

Typedef Documentation

apr_buffer_alloc

typedef void *(* apr_buffer_alloc) (void *ctx, apr_size_t size)

Function called to allocate memory in the buffer functions.

This allows buffers to be copied into and out of shared memory, or memory from other systems.

Function Documentation

apr_buffer_allocated()

apr_size_t apr_buffer_allocated

(

const apr_buffer_t *

buf

)

Return the allocated length.

The size of the underlying buffer is returned, including the terminating zero if present.

Use this function when you need to know how much memory the buffer is taking up.

Parameters

buf	The string/memory buffer.

Returns

The size of the buffer, including terminating zero if present.

apr_buffer_arraydup()

apr_status_t apr_buffer_arraydup	(	apr_buffer_t **	out,
		const apr_buffer_t *	in,
		apr_buffer_alloc	alloc,
		void *	ctx,
		int	nelts
	)

Return a copy of an array of memory buffers.

This function allows you to make a copy of one or more buffers, controlling the memory allocation yourself.

Use this function to copy buffers, and the contents of the buffers, into and out of a cache.

Parameters

out	The duplicated buffer array. If APR_ENOMEM is returned the array may be partially duplicated, it is up to the caller to free any memory allocated, and to pass zeroed buffers if needed.
in	The string/memory buffer.
alloc	The function callback to allocate memory for the buffer
ctx	Context to pass to the callback function
nelts	Number of buffers to duplicate

Returns

APR_ENONMEM if the alloc function returned NULL, otherwise APR_SUCCESS

apr_buffer_cmp()

int apr_buffer_cmp	(	const apr_buffer_t *	dst,
		const apr_buffer_t *	src
	)

Compare two possibly NULL buffers for equality.

Each buffer can be either a string or memory buffer, or NULL.

Two NULL buffers are considered equal.

A string buffer and a memory buffer are considered equal if the length excluding any trailing zero is equal, and the contents without the trailing zero are the same.

Parameters

dst	The first buffer
src	The second buffer

Returns

Positive, negative, or zero, depending on whether src is greater than, less than, or equal to dst.

apr_buffer_cpy()

apr_buffer_t * apr_buffer_cpy	(	apr_buffer_t *	dst,
		const apr_buffer_t *	src,
		apr_buffer_alloc	alloc,
		void *	ctx
	)

Copy the contents a buffer into another buffer.

This function allows you to make a copy of the contents of a buffer, into and out of a cache.

If the source buffer is NULL, the destination buffer will be assigned NULL as content.

If the memory allocator callback is NULL, the contents of the source buffer will be assigned to the destination buffer as is.

Parameters

dst	The first buffer
src	The second buffer
alloc	The function callback to allocate memory for the buffer
ctx	The context for the callback

Returns

Returns dst.

apr_buffer_dup()

apr_status_t apr_buffer_dup	(	apr_buffer_t **	out,
		const apr_buffer_t *	in,
		apr_buffer_alloc	alloc,
		void *	ctx
	)

Return a copy of a string/memory buffer.

This function allows you to make a copy of a buffer, controlling the memory allocation yourself.

Use this function to copy a buffer, and the content of the buffer, into and out of a cache.

Parameters

out	The duplicated buffer. If APR_ENOMEM is returned the buffer may be partially duplicated, it is up to the caller to free any memory allocated, and to pass zeroed buffers if needed.
in	The string/memory buffer.
alloc	The function callback to allocate memory for the buffer
ctx	Context to pass to the callback function

Returns

APR_ENONMEM if the alloc function returned NULL, otherwise APR_SUCCESS

apr_buffer_is_null()

int apr_buffer_is_null

(

const apr_buffer_t *

buf

)

Does the buffer contain a NULL buffer.

If the internal buffer is NULL, 1 is returned, otherwise 0.

Parameters

buf	The buffer.

Returns

Returns 1 if buffer is null, otherwise 0.

apr_buffer_is_str()

int apr_buffer_is_str

(

const apr_buffer_t *

buf

)

Does the buffer contain a zero terminated string.

If the buffer is already zero terminated, 1 is returned, otherwise 0.

Parameters

buf	The buffer.

Returns

Returns 1 if zero terminated, otherwise 0.

apr_buffer_len()

apr_size_t apr_buffer_len

(

const apr_buffer_t *

buf

)

Return the buffer length.

The size of the underlying buffer is returned, excluding the terminating zero if present.

Use this function to know the length of the data in the buffer.

Parameters

buf	The string/memory buffer.

Returns

The size of the buffer, excluding terminating zero if present.

apr_buffer_mem()

void * apr_buffer_mem	(	const apr_buffer_t *	buf,
		apr_size_t *	size
	)

Return the non zero terminated string/memory buffer.

If a size is provided, the size of the buffer without the terminating zero will be returned.

Use this function when you need to pass the content of the buffer to an API requiring an area of memory and a length.

Parameters

buf	The string/memory buffer.
size	Location to write the size to.

Returns

The memory buffer.

apr_buffer_mem_create()

apr_status_t apr_buffer_mem_create	(	apr_buffer_t **	mb,
		apr_pool_t *	pool,
		void *	mem,
		apr_size_t	len
	)

Create a apr_buffer_t containing non zero terminated memory.

The buffer structure is allocated from the pool, while the contents are stored as is. It is the responsibility of the caller to ensure the contents have a lifetime as long as the pool.

Parameters

mb	The memory buffer returned
pool	The pool to allocate from
mem	The memory to assign to the buffer
len	The length of the memory

Returns

Returns APR_ENOMEM if we could not allocate enough memory, APR_EINVAL if len overflows, otherwise APR_SUCCESS.

apr_buffer_mem_set()

apr_status_t apr_buffer_mem_set	(	apr_buffer_t *	buf,
		void *	mem,
		apr_size_t	len
	)

Set a apr_buffer_t with non zero terminated memory.

Parameters

buf	The buffer to allocate to
mem	The memory buffer to assign to the buffer
len	The length of the memory buffer

Returns

APR_SUCCESS, or APR_EINVAL if len overflows.

apr_buffer_null_create()

apr_status_t apr_buffer_null_create	(	apr_buffer_t **	nb,
		apr_pool_t *	pool
	)

Create a apr_buffer_t containing a NULL payload.

The buffer structure is allocated from the pool.

Parameters

nb	The null buffer returned
pool	The pool to allocate from.

Returns

Returns APR_ENOMEM if we could not allocate enough memory, otherwise APR_SUCCESS.

apr_buffer_pmemdup()

void * apr_buffer_pmemdup	(	apr_pool_t *	pool,
		const apr_buffer_t *	buf,
		apr_size_t *	size
	)

Return a copy of the content of a buffer as non zero terminated memory allocated from a pool.

If a size is provided, the size of the buffer will be returned.

Parameters

pool	The pool to allocate from.
buf	The string/memory buffer.
size	Location to write the size to.

Returns

The zero memory buffer.

apr_buffer_pstrdup()

char * apr_buffer_pstrdup	(	apr_pool_t *	pool,
		const apr_buffer_t *	buf
	)

Return a copy of the buffer as a zero terminated string allocated from a pool.

The memory or string buffer will be copied, as appropriate.

Use this function when you need the buffer to become a string with the lifetime of the pool provided.

Parameters

pool	The pool to allocate from.
buf	The buffer.

Returns

The zero terminated string. Returns NULL if we could not allocate memory.

apr_buffer_pstrncat()

char * apr_buffer_pstrncat	(	apr_pool_t *	p,
		const apr_buffer_t *	buf,
		int	nelts,
		const char *	sep,
		int	flags,
		apr_size_t *	nbytes
	)

Concatenate multiple buffers and return a string.

If the buffer contains a string, it will be copied across as is, memory buffers will be transformed by the flags specified before concatenation.

This function can be used with an apr_array_header_t.

Parameters

p	The pool from which to allocate
buf	The buffers to concatenate
nelts	The number of buffers to concatenate
sep	The optional separator between strings
flags	Allow memory buffers to be transformed before concatenation. APR_BUFFER_NONE copies memory buffer as is. APR_BUFFER_BASE64 applies base64 encoding to the memory buffer.
nbytes	(output) strlen of new string (pass in NULL to omit)

Returns

The new string

apr_buffer_str()

char * apr_buffer_str

(

const apr_buffer_t *

buf

)

Return the zero terminated string from a buffer containing a string.

If the buffer contains a string, the original string is returned.

If the buffer contains non zero terminated memory, NULL will be returned.

Use this function when we want to be sure you're dealing with a string, and want to avoid duplication.

Parameters

buf	The string/memory buffer.

Returns

The zero terminated string. Returns NULL if the buffer contains memory.

apr_buffer_str_create()

apr_status_t apr_buffer_str_create	(	apr_buffer_t **	sb,
		apr_pool_t *	pool,
		char *	str,
		apr_ssize_t	len
	)

Create a apr_buffer_t containing a zero terminated string.

The buffer structure is allocated from the pool, while the contents are stored as is. It is the responsibility of the caller to ensure the contents have a lifetime as long as the pool.

Parameters

sb	The string buffer returned
pool	The pool to allocate from.
str	The string to assign to the buffer.
len	The length of the string, or APR_BUFFER_STRING to have the length calculated.

Returns

Returns APR_ENOMEM if we could not allocate enough memory, APR_EINVAL if len overflows, otherwise APR_SUCCESS.

apr_buffer_str_set()

apr_status_t apr_buffer_str_set	(	apr_buffer_t *	buf,
		char *	str,
		apr_ssize_t	len
	)

Set a apr_buffer_t with a zero terminated string.

Parameters

buf	The buffer to assign the data to.
str	The zero terminated string to assign to the buffer.
len	The length of the string without terminating zero, or APR_BUFFER_STRING to have the length calculated.

Returns

APR_SUCCESS, or APR_EINVAL if len overflows.