Bucket Brigades
[APR Utility Functions]

Data Structures
struct	apr_bucket_type_t
struct	apr_bucket
struct	apr_bucket_brigade
struct	apr_bucket_refcount
struct	apr_bucket_heap
struct	apr_bucket_pool
struct	apr_bucket_mmap
struct	apr_bucket_file
union	apr_bucket_structs
Defines
#define	APR_BUCKET_BUFF_SIZE   8000
#define	APR_BRIGADE_CHECK_CONSISTENCY(b)
#define	APR_BUCKET_CHECK_CONSISTENCY(e)
#define	APR_BRIGADE_SENTINEL(b)   APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
#define	APR_BRIGADE_EMPTY(b)   APR_RING_EMPTY(&(b)->list, apr_bucket, link)
#define	APR_BRIGADE_FIRST(b)   APR_RING_FIRST(&(b)->list)
#define	APR_BRIGADE_LAST(b)   APR_RING_LAST(&(b)->list)
#define	APR_BRIGADE_INSERT_HEAD(b, e)
#define	APR_BRIGADE_INSERT_TAIL(b, e)
#define	APR_BRIGADE_CONCAT(a, b)
#define	APR_BRIGADE_PREPEND(a, b)
#define	APR_BUCKET_INSERT_BEFORE(a, b)
#define	APR_BUCKET_INSERT_AFTER(a, b)
#define	APR_BUCKET_NEXT(e)   APR_RING_NEXT((e), link)
#define	APR_BUCKET_PREV(e)   APR_RING_PREV((e), link)
#define	APR_BUCKET_REMOVE(e)   APR_RING_REMOVE((e), link)
#define	APR_BUCKET_INIT(e)   APR_RING_ELEM_INIT((e), link)
#define	APR_BUCKET_IS_METADATA(e)   ((e)->type->is_metadata)
#define	APR_BUCKET_IS_FLUSH(e)   ((e)->type == &apr_bucket_type_flush)
#define	APR_BUCKET_IS_EOS(e)   ((e)->type == &apr_bucket_type_eos)
#define	APR_BUCKET_IS_FILE(e)   ((e)->type == &apr_bucket_type_file)
#define	APR_BUCKET_IS_PIPE(e)   ((e)->type == &apr_bucket_type_pipe)
#define	APR_BUCKET_IS_SOCKET(e)   ((e)->type == &apr_bucket_type_socket)
#define	APR_BUCKET_IS_HEAP(e)   ((e)->type == &apr_bucket_type_heap)
#define	APR_BUCKET_IS_TRANSIENT(e)   ((e)->type == &apr_bucket_type_transient)
#define	APR_BUCKET_IS_IMMORTAL(e)   ((e)->type == &apr_bucket_type_immortal)
#define	APR_BUCKET_IS_MMAP(e)   ((e)->type == &apr_bucket_type_mmap)
#define	APR_BUCKET_IS_POOL(e)   ((e)->type == &apr_bucket_type_pool)
#define	APR_BUCKET_ALLOC_SIZE   APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
#define	apr_bucket_destroy(e)
#define	apr_bucket_delete(e)
#define	apr_bucket_read(e, str, len, block)   (e)->type->read(e, str, len, block)
#define	apr_bucket_setaside(e, p)   (e)->type->setaside(e,p)
#define	apr_bucket_split(e, point)   (e)->type->split(e, point)
#define	apr_bucket_copy(e, c)   (e)->type->copy(e, c)
Typedefs
typedef struct apr_bucket_brigade	apr_bucket_brigade
typedef struct apr_bucket	apr_bucket
typedef struct apr_bucket_alloc_t	apr_bucket_alloc_t
typedef struct apr_bucket_type_t	apr_bucket_type_t
typedef apr_status_t(*	apr_brigade_flush )(apr_bucket_brigade *bb, void *ctx)
typedef struct apr_bucket_refcount	apr_bucket_refcount
typedef struct apr_bucket_heap	apr_bucket_heap
typedef struct apr_bucket_pool	apr_bucket_pool
typedef struct apr_bucket_mmap	apr_bucket_mmap
typedef struct apr_bucket_file	apr_bucket_file
typedef union apr_bucket_structs	apr_bucket_structs
Enumerations
enum	apr_read_type_e { APR_BLOCK_READ, APR_NONBLOCK_READ }
Functions
apr_bucket_brigade *	apr_brigade_create (apr_pool_t *p, apr_bucket_alloc_t *list)
apr_status_t	apr_brigade_destroy (apr_bucket_brigade *b)
apr_status_t	apr_brigade_cleanup (void *data)
apr_bucket_brigade *	apr_brigade_split_ex (apr_bucket_brigade *b, apr_bucket *e, apr_bucket_brigade *a)
apr_bucket_brigade *	apr_brigade_split (apr_bucket_brigade *b, apr_bucket *e)
apr_status_t	apr_brigade_partition (apr_bucket_brigade *b, apr_off_t point, apr_bucket **after_point)
apr_status_t	apr_brigade_length (apr_bucket_brigade *bb, int read_all, apr_off_t *length)
apr_status_t	apr_brigade_flatten (apr_bucket_brigade *bb, char *c, apr_size_t *len)
apr_status_t	apr_brigade_pflatten (apr_bucket_brigade *bb, char **c, apr_size_t *len, apr_pool_t *pool)
apr_status_t	apr_brigade_split_line (apr_bucket_brigade *bbOut, apr_bucket_brigade *bbIn, apr_read_type_e block, apr_off_t maxbytes)
apr_status_t	apr_brigade_to_iovec (apr_bucket_brigade *b, struct iovec *vec, int *nvec)
apr_status_t	apr_brigade_vputstrs (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, va_list va)
apr_status_t	apr_brigade_write (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *str, apr_size_t nbyte)
apr_status_t	apr_brigade_writev (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const struct iovec *vec, apr_size_t nvec)
apr_status_t	apr_brigade_puts (apr_bucket_brigade *bb, apr_brigade_flush flush, void *ctx, const char *str)
apr_status_t	apr_brigade_putc (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char c)
apr_status_t	apr_brigade_putstrs (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx,...)
apr_status_t	apr_brigade_printf (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt,...)
apr_status_t	apr_brigade_vprintf (apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt, va_list va)
apr_bucket *	apr_brigade_insert_file (apr_bucket_brigade *bb, apr_file_t *f, apr_off_t start, apr_off_t len, apr_pool_t *p)
apr_bucket_alloc_t *	apr_bucket_alloc_create (apr_pool_t *p)
apr_bucket_alloc_t *	apr_bucket_alloc_create_ex (apr_allocator_t *allocator)
void	apr_bucket_alloc_destroy (apr_bucket_alloc_t *list)
void *	apr_bucket_alloc (apr_size_t size, apr_bucket_alloc_t *list)
void	apr_bucket_free (void *block)
apr_status_t	apr_bucket_setaside_noop (apr_bucket *data, apr_pool_t *pool)
apr_status_t	apr_bucket_setaside_notimpl (apr_bucket *data, apr_pool_t *pool)
apr_status_t	apr_bucket_split_notimpl (apr_bucket *data, apr_size_t point)
apr_status_t	apr_bucket_copy_notimpl (apr_bucket *e, apr_bucket **c)
void	apr_bucket_destroy_noop (void *data)
apr_status_t	apr_bucket_simple_split (apr_bucket *b, apr_size_t point)
apr_status_t	apr_bucket_simple_copy (apr_bucket *a, apr_bucket **b)
apr_bucket *	apr_bucket_shared_make (apr_bucket *b, void *data, apr_off_t start, apr_size_t length)
int	apr_bucket_shared_destroy (void *data)
apr_status_t	apr_bucket_shared_split (apr_bucket *b, apr_size_t point)
apr_status_t	apr_bucket_shared_copy (apr_bucket *a, apr_bucket **b)
apr_bucket *	apr_bucket_eos_create (apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_eos_make (apr_bucket *b)
apr_bucket *	apr_bucket_flush_create (apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_flush_make (apr_bucket *b)
apr_bucket *	apr_bucket_immortal_create (const char *buf, apr_size_t nbyte, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_immortal_make (apr_bucket *b, const char *buf, apr_size_t nbyte)
apr_bucket *	apr_bucket_transient_create (const char *buf, apr_size_t nbyte, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_transient_make (apr_bucket *b, const char *buf, apr_size_t nbyte)
apr_bucket *	apr_bucket_heap_create (const char *buf, apr_size_t nbyte, void(*free_func)(void *data), apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_heap_make (apr_bucket *b, const char *buf, apr_size_t nbyte, void(*free_func)(void *data))
apr_bucket *	apr_bucket_pool_create (const char *buf, apr_size_t length, apr_pool_t *pool, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_pool_make (apr_bucket *b, const char *buf, apr_size_t length, apr_pool_t *pool)
apr_bucket *	apr_bucket_mmap_create (apr_mmap_t *mm, apr_off_t start, apr_size_t length, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_mmap_make (apr_bucket *b, apr_mmap_t *mm, apr_off_t start, apr_size_t length)
apr_bucket *	apr_bucket_socket_create (apr_socket_t *thissock, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_socket_make (apr_bucket *b, apr_socket_t *thissock)
apr_bucket *	apr_bucket_pipe_create (apr_file_t *thispipe, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_pipe_make (apr_bucket *b, apr_file_t *thispipe)
apr_bucket *	apr_bucket_file_create (apr_file_t *fd, apr_off_t offset, apr_size_t len, apr_pool_t *p, apr_bucket_alloc_t *list)
apr_bucket *	apr_bucket_file_make (apr_bucket *b, apr_file_t *fd, apr_off_t offset, apr_size_t len, apr_pool_t *p)
apr_status_t	apr_bucket_file_enable_mmap (apr_bucket *b, int enabled)
Variables
const apr_bucket_type_t	apr_bucket_type_flush
const apr_bucket_type_t	apr_bucket_type_eos
const apr_bucket_type_t	apr_bucket_type_file
const apr_bucket_type_t	apr_bucket_type_heap
const apr_bucket_type_t	apr_bucket_type_mmap
const apr_bucket_type_t	apr_bucket_type_pool
const apr_bucket_type_t	apr_bucket_type_pipe
const apr_bucket_type_t	apr_bucket_type_immortal
const apr_bucket_type_t	apr_bucket_type_transient
const apr_bucket_type_t	apr_bucket_type_socket

---

Define Documentation

#define APR_BRIGADE_CHECK_CONSISTENCY

(

b

)

checks the ring pointers in a bucket brigade for consistency. an abort() will be triggered if any inconsistencies are found. note: this is a no-op unless APR_BUCKET_DEBUG is defined.

Parameters:

b

The brigade

#define APR_BRIGADE_CONCAT	(	a,
		b		)

Value:

do {                                    \
        APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link);      \
        APR_BRIGADE_CHECK_CONSISTENCY((a));                             \
    } while (0)

Concatenate brigade b onto the end of brigade a, leaving brigade b empty

Parameters:

	a	The first brigade
	b	The second brigade

#define APR_BRIGADE_EMPTY

(

b

)

APR_RING_EMPTY(&(b)->list, apr_bucket, link)

Determine if the bucket brigade is empty

Parameters:

b

The brigade to check

Returns:

true or false

#define APR_BRIGADE_FIRST

(

b

)

APR_RING_FIRST(&(b)->list)

Return the first bucket in a brigade

Parameters:

b

The brigade to query

Returns:

The first bucket in the brigade

#define APR_BRIGADE_INSERT_HEAD	(	b,
		e		)

Value:

do {                            \
        apr_bucket *ap__b = (e);                                        \
        APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);      \
        APR_BRIGADE_CHECK_CONSISTENCY((b));                             \
    } while (0)

Insert a list of buckets at the front of a brigade

Parameters:

	b	The brigade to add to
	e	The first bucket in a list of buckets to insert

#define APR_BRIGADE_INSERT_TAIL	(	b,
		e		)

Value:

do {                            \
        apr_bucket *ap__b = (e);                                        \
        APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);      \
        APR_BRIGADE_CHECK_CONSISTENCY((b));                             \
    } while (0)

Insert a list of buckets at the end of a brigade

Parameters:

	b	The brigade to add to
	e	The first bucket in a list of buckets to insert

#define APR_BRIGADE_LAST

(

b

)

APR_RING_LAST(&(b)->list)

Return the last bucket in a brigade

Parameters:

b

The brigade to query

Returns:

The last bucket in the brigade

#define APR_BRIGADE_PREPEND	(	a,
		b		)

Value:

do {                                    \
        APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link);     \
        APR_BRIGADE_CHECK_CONSISTENCY((a));                             \
    } while (0)

Prepend brigade b onto the beginning of brigade a, leaving brigade b empty

Parameters:

	a	The first brigade
	b	The second brigade

#define APR_BRIGADE_SENTINEL

(

b

)

APR_RING_SENTINEL(&(b)->list, apr_bucket, link)

Wrappers around the RING macros to reduce the verbosity of the code that handles bucket brigades. The magic pointer value that indicates the head of the brigade

Remarks:

This is used to find the beginning and end of the brigade, eg:

      while (e != APR_BRIGADE_SENTINEL(b)) {
          ...
          e = APR_BUCKET_NEXT(e);
      }
 

Parameters:

b

The brigade

Returns:

The magic pointer value

#define APR_BUCKET_ALLOC_SIZE   APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))

The amount that apr_bucket_alloc() should allocate in the common case. Note: this is twice as big as apr_bucket_structs to allow breathing room for third-party bucket types.

#define APR_BUCKET_BUFF_SIZE   8000

default bucket buffer size - 8KB minus room for memory allocator headers

#define APR_BUCKET_CHECK_CONSISTENCY

(

e

)

checks the brigade a bucket is in for ring consistency. an abort() will be triggered if any inconsistencies are found. note: this is a no-op unless APR_BUCKET_DEBUG is defined.

Parameters:

e

The bucket

#define apr_bucket_copy	(	e,
		c		)	(e)->type->copy(e, c)

Copy a bucket.

Parameters:

	e	The bucket to copy
	c	Returns a pointer to the new bucket

#define apr_bucket_delete

(

e

)

Value:

do {                                    \
        APR_BUCKET_REMOVE(e);                                           \
        apr_bucket_destroy(e);                                          \
    } while (0)

Delete a bucket by removing it from its brigade (if any) and then destroying it.

Remarks:

This mainly acts as an aid in avoiding code verbosity. It is the preferred exact equivalent to:

      APR_BUCKET_REMOVE(e);
      apr_bucket_destroy(e);
 

Parameters:

e

The bucket to delete

#define apr_bucket_destroy

(

e

)

Value:

do {                                    \
        (e)->type->destroy((e)->data);                                  \
        (e)->free(e);                                                   \
    } while (0)

Free the resources used by a bucket. If multiple buckets refer to the same resource it is freed when the last one goes away.

See also:

apr_bucket_delete()

Parameters:

e

The bucket to destroy

#define APR_BUCKET_INIT

(

e

)

APR_RING_ELEM_INIT((e), link)

Initialize a new bucket's prev/next pointers

Parameters:

e

The bucket to initialize

#define APR_BUCKET_INSERT_AFTER	(	a,
		b		)

Value:

do {                            \
        apr_bucket *ap__a = (a), *ap__b = (b);                          \
        APR_RING_INSERT_AFTER(ap__a, ap__b, link);                      \
        APR_BUCKET_CHECK_CONSISTENCY(ap__a);                            \
    } while (0)

Insert a list of buckets after a specified bucket

Parameters:

	a	The bucket to insert after
	b	The buckets to insert

#define APR_BUCKET_INSERT_BEFORE	(	a,
		b		)

Value:

do {                            \
        apr_bucket *ap__a = (a), *ap__b = (b);                          \
        APR_RING_INSERT_BEFORE(ap__a, ap__b, link);                     \
        APR_BUCKET_CHECK_CONSISTENCY(ap__a);                            \
    } while (0)

Insert a list of buckets before a specified bucket

Parameters:

	a	The bucket to insert before
	b	The buckets to insert

#define APR_BUCKET_IS_EOS

(

e

)

((e)->type == &apr_bucket_type_eos)

Determine if a bucket is an EOS bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_FILE

(

e

)

((e)->type == &apr_bucket_type_file)

Determine if a bucket is a FILE bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_FLUSH

(

e

)

((e)->type == &apr_bucket_type_flush)

Determine if a bucket is a FLUSH bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_HEAP

(

e

)

((e)->type == &apr_bucket_type_heap)

Determine if a bucket is a HEAP bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_IMMORTAL

(

e

)

((e)->type == &apr_bucket_type_immortal)

Determine if a bucket is a IMMORTAL bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_METADATA

(

e

)

((e)->type->is_metadata)

Determine if a bucket contains metadata. An empty bucket is safe to arbitrarily remove if and only if this is false.

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_MMAP

(

e

)

((e)->type == &apr_bucket_type_mmap)

Determine if a bucket is a MMAP bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_PIPE

(

e

)

((e)->type == &apr_bucket_type_pipe)

Determine if a bucket is a PIPE bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_POOL

(

e

)

((e)->type == &apr_bucket_type_pool)

Determine if a bucket is a POOL bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_SOCKET

(

e

)

((e)->type == &apr_bucket_type_socket)

Determine if a bucket is a SOCKET bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_IS_TRANSIENT

(

e

)

((e)->type == &apr_bucket_type_transient)

Determine if a bucket is a TRANSIENT bucket

Parameters:

e

The bucket to inspect

Returns:

true or false

#define APR_BUCKET_NEXT

(

e

)

APR_RING_NEXT((e), link)

Get the next bucket in the list

Parameters:

e

The current bucket

Returns:

The next bucket

#define APR_BUCKET_PREV

(

e

)

APR_RING_PREV((e), link)

Get the previous bucket in the list

Parameters:

e

The current bucket

Returns:

The previous bucket

#define apr_bucket_read	(	e,
		str,
		len,
		block		)	(e)->type->read(e, str, len, block)

Read the data from the bucket.

If it is not practical to return all the data in the bucket, the current bucket is split and replaced by two buckets, the first representing the data returned in this call, and the second representing the rest of the data as yet unread. The original bucket will become the first bucket after this call.

(It is assumed that the bucket is a member of a brigade when this function is called).

Parameters:

	e	The bucket to read from
	str	The location to store the data in
	len	The amount of data read
	block	Whether the read function blocks

#define APR_BUCKET_REMOVE

(

e

)

APR_RING_REMOVE((e), link)

Remove a bucket from its bucket brigade

Parameters:

e

The bucket to remove

#define apr_bucket_setaside	(	e,
		p		)	(e)->type->setaside(e,p)

Setaside data so that stack data is not destroyed on returning from the function

Parameters:

	e	The bucket to setaside
	p	The pool to setaside into

#define apr_bucket_split	(	e,
		point		)	(e)->type->split(e, point)

Split one bucket in two at the point provided.

Once split, the original bucket becomes the first of the two new buckets.

(It is assumed that the bucket is a member of a brigade when this function is called).

Parameters:

	e	The bucket to split
	point	The offset to split the bucket at

---

Typedef Documentation

typedef apr_status_t(* apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx)

Function called when a brigade should be flushed

typedef struct apr_bucket apr_bucket

See also:

apr_bucket

typedef struct apr_bucket_alloc_t apr_bucket_alloc_t

See also:

apr_bucket_alloc_t

typedef struct apr_bucket_brigade apr_bucket_brigade

The one-sentence buzzword-laden overview: Bucket brigades represent a complex data stream that can be passed through a layered IO system without unnecessary copying. A longer overview follows...

A bucket brigade is a doubly linked list (ring) of buckets, so we aren't limited to inserting at the front and removing at the end. Buckets are only passed around as members of a brigade, although singleton buckets can occur for short periods of time.

Buckets are data stores of various types. They can refer to data in memory, or part of a file or mmap area, or the output of a process, etc. Buckets also have some type-dependent accessor functions: read, split, copy, setaside, and destroy.

read returns the address and size of the data in the bucket. If the data isn't in memory then it is read in and the bucket changes type so that it can refer to the new location of the data. If all the data doesn't fit in the bucket then a new bucket is inserted into the brigade to hold the rest of it.

split divides the data in a bucket into two regions. After a split the original bucket refers to the first part of the data and a new bucket inserted into the brigade after the original bucket refers to the second part of the data. Reference counts are maintained as necessary.

setaside ensures that the data in the bucket has a long enough lifetime. Sometimes it is convenient to create a bucket referring to data on the stack in the expectation that it will be consumed (output to the network) before the stack is unwound. If that expectation turns out not to be valid, the setaside function is called to move the data somewhere safer.

copy makes a duplicate of the bucket structure as long as it's possible to have multiple references to a single copy of the data itself. Not all bucket types can be copied.

destroy maintains the reference counts on the resources used by a bucket and frees them if necessary.

Note: all of the above functions have wrapper macros (apr_bucket_read(), apr_bucket_destroy(), etc), and those macros should be used rather than using the function pointers directly.

To write a bucket brigade, they are first made into an iovec, so that we don't write too little data at one time. Currently we ignore compacting the buckets into as few buckets as possible, but if we really want good performance, then we need to compact the buckets before we convert to an iovec, or possibly while we are converting to an iovec.

See also:

apr_bucket_brigade

typedef struct apr_bucket_file apr_bucket_file

See also:

apr_bucket_file

typedef struct apr_bucket_heap apr_bucket_heap

See also:

apr_bucket_heap

typedef struct apr_bucket_mmap apr_bucket_mmap

See also:

apr_bucket_mmap

typedef struct apr_bucket_pool apr_bucket_pool

See also:

apr_bucket_pool

typedef struct apr_bucket_refcount apr_bucket_refcount

See also:

apr_bucket_refcount

typedef union apr_bucket_structs apr_bucket_structs

See also:

apr_bucket_structs

typedef struct apr_bucket_type_t apr_bucket_type_t

See also:

apr_bucket_type_t

---

Enumeration Type Documentation

enum apr_read_type_e

Determines how a bucket or brigade should be read

Enumerator:

APR_BLOCK_READ	block until data becomes available
APR_NONBLOCK_READ	return immediately if no data is available

---

Function Documentation

apr_status_t apr_brigade_cleanup

(

void *

data

)

empty out an entire bucket brigade. This includes destroying all of the buckets within the bucket brigade's bucket list. This is similar to apr_brigade_destroy(), except that it does not deregister the brigade's pool cleanup function.

Parameters:

data

The bucket brigade to clean up

Remarks:

Generally, you should use apr_brigade_destroy(). This function can be useful in situations where you have a single brigade that you wish to reuse many times by destroying all of the buckets in the brigade and putting new buckets into it later.

apr_bucket_brigade* apr_brigade_create	(	apr_pool_t *	p,
		apr_bucket_alloc_t *	list
	)

Create a new bucket brigade. The bucket brigade is originally empty.

Parameters:

	p	The pool to associate with the brigade. Data is not allocated out of the pool, but a cleanup is registered.
	list	The bucket allocator to use

Returns:

The empty bucket brigade

apr_status_t apr_brigade_destroy

(

apr_bucket_brigade *

b

)

destroy an entire bucket brigade. This includes destroying all of the buckets within the bucket brigade's bucket list.

Parameters:

b

The bucket brigade to destroy

apr_status_t apr_brigade_flatten	(	apr_bucket_brigade *	bb,
		char *	c,
		apr_size_t *	len
	)

Take a bucket brigade and store the data in a flat char*

Parameters:

	bb	The bucket brigade to create the char* from
	c	The char* to write into
	len	The maximum length of the char array. On return, it is the actual length of the char array.

apr_bucket* apr_brigade_insert_file	(	apr_bucket_brigade *	bb,
		apr_file_t *	f,
		apr_off_t	start,
		apr_off_t	len,
		apr_pool_t *	p
	)

Utility function to insert a file (or a segment of a file) onto the end of the brigade. The file is split into multiple buckets if it is larger than the maximum size which can be represented by a single bucket.

Parameters:

	bb	the brigade to insert into
	f	the file to insert
	start	the offset of the start of the segment
	len	the length of the segment of the file to insert
	p	pool from which file buckets are allocated

Returns:

the last bucket inserted

apr_status_t apr_brigade_length	(	apr_bucket_brigade *	bb,
		int	read_all,
		apr_off_t *	length
	)

Return the total length of the brigade.

Parameters:

	bb	The brigade to compute the length of
	read_all	Read unknown-length buckets to force a size
	length	Returns the length of the brigade (up to the end, or up to a bucket read error), or -1 if the brigade has buckets of indeterminate length and read_all is 0.

apr_status_t apr_brigade_partition	(	apr_bucket_brigade *	b,
		apr_off_t	point,
		apr_bucket **	after_point
	)

Partition a bucket brigade at a given offset (in bytes from the start of the brigade). This is useful whenever a filter wants to use known ranges of bytes from the brigade; the ranges can even overlap.

Parameters:

	b	The brigade to partition
	point	The offset at which to partition the brigade
	after_point	Returns a pointer to the first bucket after the partition

Returns:

APR_SUCCESS on success, APR_INCOMPLETE if the contents of the brigade were shorter than point, or an error code.

Remarks:

if APR_INCOMPLETE is returned, after_point will be set to the brigade sentinel.

apr_status_t apr_brigade_pflatten	(	apr_bucket_brigade *	bb,
		char **	c,
		apr_size_t *	len,
		apr_pool_t *	pool
	)

Creates a pool-allocated string representing a flat bucket brigade

Parameters:

	bb	The bucket brigade to create the char array from
	c	On return, the allocated char array
	len	On return, the length of the char array.
	pool	The pool to allocate the string from.

apr_status_t apr_brigade_printf	(	apr_bucket_brigade *	b,
		apr_brigade_flush	flush,
		void *	ctx,
		const char *	fmt,
			...
	)

Evaluate a printf and put the resulting string at the end of the bucket brigade.

Parameters:

	b	The brigade to write to
	flush	The flush function to use if the brigade is full
	ctx	The structure to pass to the flush function
	fmt	The format of the string to write
	...	The arguments to fill out the format

Returns:

APR_SUCCESS or error code

apr_status_t apr_brigade_putc	(	apr_bucket_brigade *	b,
		apr_brigade_flush	flush,
		void *	ctx,
		const char	c
	)

This function writes a character into a bucket brigade.

Parameters:

	b	The bucket brigade to add to
	flush	The flush function to use if the brigade is full
	ctx	The structure to pass to the flush function
	c	The character to add

Returns:

APR_SUCCESS or error code

apr_status_t apr_brigade_puts	(	apr_bucket_brigade *	bb,
		apr_brigade_flush	flush,
		void *	ctx,
		const char *	str
	)

This function writes a string into a bucket brigade.

Parameters:

	bb	The bucket brigade to add to
	flush	The flush function to use if the brigade is full
	ctx	The structure to pass to the flush function
	str	The string to add

Returns:

APR_SUCCESS or error code

apr_status_t apr_brigade_putstrs	(	apr_bucket_brigade *	b,
		apr_brigade_flush	flush,
		void *	ctx,
			...
	)

This function writes an unspecified number of strings into a bucket brigade.

Parameters:

	b	The bucket brigade to add to
	flush	The flush function to use if the brigade is full
	ctx	The structure to pass to the flush function
	...	The strings to add

Returns:

APR_SUCCESS or error code

apr_bucket_brigade* apr_brigade_split	(	apr_bucket_brigade *	b,
		apr_bucket *	e
	)

Create a new bucket brigade and move the buckets from the tail end of an existing brigade into the new brigade. Buckets from

Parameters:

	e	to the last bucket (inclusively) of brigade
	b	are moved from
	b	to the returned brigade.
	b	The brigade to split
	e	The first bucket to move

Returns:

The new brigade

Warning:

Note that this function always allocates a new brigade so memory consumption should be carefully considered.

apr_bucket_brigade* apr_brigade_split_ex	(	apr_bucket_brigade *	b,
		apr_bucket *	e,
		apr_bucket_brigade *	a
	)

Move the buckets from the tail end of the existing brigade

Parameters:

	b	into the brigade
	a.	If
	a	is NULL a new brigade is created. Buckets from
	e	to the last bucket (inclusively) of brigade
	b	are moved from
	b	to the returned brigade
	a.
	b	The brigade to split
	e	The first bucket to move
	a	The brigade which should be used for the result or NULL if a new brigade should be created.

Returns:

The brigade supplied in

Parameters:

	a	or a new one if
	a	was NULL.

Warning:

Note that this function allocates a new brigade if

Parameters:

a

is NULL so memory consumption should be carefully considered.

apr_status_t apr_brigade_split_line

(