Loading...
Searching...
No Matches
Bucket Brigades
APR Utility Functions
Collaboration diagram for Bucket Brigades:

## 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

## Macros

#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)
apr_size_t | apr_bucket_alloc_aligned_floor (apr_bucket_alloc_t *list, apr_size_t size)
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)
apr_status_t | apr_bucket_file_set_buf_size (apr_bucket *b, apr_size_t size)

## 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

## Detailed Description

## Macro Definition Documentation

## APR_BRIGADE_CHECK_CONSISTENCY

#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

## APR_BRIGADE_CONCAT

#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)
apr_bucket
Definition apr_buckets.h:224

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

Parameters

  a | The first brigade
  b | The second brigade

## APR_BRIGADE_EMPTY

#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

## APR_BRIGADE_FIRST

#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

## APR_BRIGADE_INSERT_HEAD

#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 single bucket at the front of a brigade

Parameters

  b | The brigade to add to
  e | The bucket to insert

## APR_BRIGADE_INSERT_TAIL

#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 single bucket at the end of a brigade

Parameters

  b | The brigade to add to
  e | The bucket to insert

## APR_BRIGADE_LAST

#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

## APR_BRIGADE_PREPEND

#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

## APR_BRIGADE_SENTINEL

#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

## APR_BUCKET_ALLOC_SIZE

#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.

## APR_BUCKET_BUFF_SIZE

#define APR_BUCKET_BUFF_SIZE 8000

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

## APR_BUCKET_CHECK_CONSISTENCY

#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

## apr_bucket_copy

#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

## apr_bucket_delete

#define apr_bucket_delete | ( |  | e | ) |

Value:
do { \
apr_bucket *apr__b = (e); \
APR_BUCKET_REMOVE(apr__b); \
apr_bucket_destroy(apr__b); \
} 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

## apr_bucket_destroy

#define apr_bucket_destroy | ( |  | e | ) |

Value:
do { \
apr_bucket *apr__d = (e); \
apr__d->type->destroy(apr__d->data); \
apr__d->free(apr__d); \
} while (0)
apr_bucket_type_t::destroy
void(* destroy)(void *data)
Definition apr_buckets.h:164
apr_bucket::free
void(* free)(void *e)
Definition apr_buckets.h:252
apr_bucket::data
void * data
Definition apr_buckets.h:244
apr_bucket::type
const apr_bucket_type_t * type
Definition apr_buckets.h:228

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

## APR_BUCKET_INIT

#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

## APR_BUCKET_INSERT_AFTER

#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 single bucket after a specified bucket

Parameters

  a | The bucket to insert after
  b | The bucket to insert

## APR_BUCKET_INSERT_BEFORE

#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 single bucket before a specified bucket

Parameters

  a | The bucket to insert before
  b | The bucket to insert

## APR_BUCKET_IS_EOS

#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

## APR_BUCKET_IS_FILE

#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

## APR_BUCKET_IS_FLUSH

#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

## APR_BUCKET_IS_HEAP

#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

## APR_BUCKET_IS_IMMORTAL

#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

## APR_BUCKET_IS_METADATA

#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

## APR_BUCKET_IS_MMAP

#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

## APR_BUCKET_IS_PIPE

#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

## APR_BUCKET_IS_POOL

#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

## APR_BUCKET_IS_SOCKET

#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

## APR_BUCKET_IS_TRANSIENT

#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

## APR_BUCKET_NEXT

#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

## APR_BUCKET_PREV

#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

## apr_bucket_read

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

Read some data from the bucket.

The apr_bucket_read function returns a convenient amount of data from the bucket provided, writing the address and length of the data to the pointers provided by the caller. The function tries as hard as possible to avoid a memory copy.

Buckets are expected to be a member of a brigade at the time they are read.

In typical application code, buckets are read in a loop, and after each bucket is read and processed, it is moved or deleted from the brigade and the next bucket read.

The definition of "convenient" depends on the type of bucket that is being read, and is decided by APR. In the case of memory based buckets such as heap and immortal buckets, a pointer will be returned to the location of the buffer containing the complete contents of the bucket.

Some buckets, such as the socket bucket, might have no concept of length. If an attempt is made to read such a bucket, the apr_bucket_read function will read a convenient amount of data from the socket. The socket bucket is magically morphed into a heap bucket containing the just-read data, and a new socket bucket is inserted just after this heap bucket.

To understand why apr_bucket_read might do this, consider the loop described above to read and process buckets. The current bucket is magically morphed into a heap bucket and returned to the caller. The caller processes the data, and deletes the heap bucket, moving onto the next bucket, the new socket bucket. This process repeats, giving the illusion of a bucket brigade that contains potentially infinite amounts of data. It is up to the caller to decide at what point to stop reading buckets.

Some buckets, such as the file bucket, might have a fixed size, but be significantly larger than is practical to store in RAM in one go. As with the socket bucket, if an attempt is made to read from a file bucket, the file bucket is magically morphed into a heap bucket containing a convenient amount of data read from the current offset in the file. During the read, the offset will be moved forward on the file, and a new file bucket will be inserted directly after the current bucket representing the remainder of the file. If the heap bucket was large enough to store the whole remainder of the file, no more file buckets are inserted, and the file bucket will disappear completely.

The pattern for reading buckets described above does create the illusion that the code is willing to swallow buckets that might be too large for the system to handle in one go. This however is just an illusion: APR will always ensure that large (file) or infinite (socket) buckets are broken into convenient bite sized heap buckets before data is returned to the caller.

There is a potential gotcha to watch for: if buckets are read in a loop, and aren't deleted after being processed, the potentially large bucket will slowly be converted into RAM resident heap buckets. If the file is larger than available RAM, an out of memory condition could be caused if the application is not careful to manage this.

Parameters

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

## APR_BUCKET_REMOVE

#define APR_BUCKET_REMOVE | ( |  | e | ) | APR_RING_REMOVE((e), link)

Remove a bucket from its bucket brigade

Parameters

  e | The bucket to remove

## apr_bucket_setaside

#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

## apr_bucket_split

#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

## apr_brigade_flush

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

Function called when a brigade should be flushed

## apr_bucket

typedef struct apr_bucket apr_bucket

See also
  apr_bucket

## apr_bucket_alloc_t

typedef struct apr_bucket_alloc_t apr_bucket_alloc_t

See also
  apr_bucket_alloc_t

## apr_bucket_brigade

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

## apr_bucket_file

typedef struct apr_bucket_file apr_bucket_file

See also
  apr_bucket_file

## apr_bucket_heap

typedef struct apr_bucket_heap apr_bucket_heap

See also
  apr_bucket_heap

## apr_bucket_mmap

typedef struct apr_bucket_mmap apr_bucket_mmap

See also
  apr_bucket_mmap

## apr_bucket_pool

typedef struct apr_bucket_pool apr_bucket_pool

See also
  apr_bucket_pool

## apr_bucket_refcount

typedef struct apr_bucket_refcount apr_bucket_refcount

See also
  apr_bucket_refcount

## apr_bucket_structs

typedef union apr_bucket_structs apr_bucket_structs

See also
  apr_bucket_structs

## apr_bucket_type_t

typedef struct apr_bucket_type_t apr_bucket_type_t

See also
  apr_bucket_type_t

## Enumeration Type Documentation

## apr_read_type_e

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_brigade_cleanup()

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_brigade_create()

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_brigade_destroy()

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_brigade_flatten()

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_brigade_insert_file()

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_brigade_length()

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_brigade_partition()

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_brigade_pflatten()

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_brigade_printf()

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_brigade_putc()

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_brigade_puts()

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_brigade_putstrs()

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_brigade_split()

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 e to the last bucket (inclusively) of brigade b are moved from b to the returned brigade.

Parameters

  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_brigade_split_ex()

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 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.

Parameters

  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. The brigade a will be cleared if it is not empty.

Returns
  The brigade supplied in a or a new one if a was NULL.

Warning
  Note that this function allocates a new brigade if a is NULL so memory consumption should be carefully considered.

## apr_brigade_split_line()

apr_status_t apr_brigade_split_line | ( | apr_bucket_brigade * | bbOut,
|  | apr_bucket_brigade * | bbIn,
|  | apr_read_type_e | block,
|  | apr_off_t | maxbytes
| ) |  |

Split a brigade to represent one LF line.

Parameters

  bbOut | The bucket brigade that will have the LF line appended to.
  bbIn | The input bucket brigade to search for a LF-line.
  block | The blocking mode to be used to split the line.
  maxbytes | The maximum bytes to read. If this many bytes are seen without a LF, the brigade will contain a partial line.

## apr_brigade_to_iovec()

apr_status_t apr_brigade_to_iovec | ( | apr_bucket_brigade * | b,
|  | struct iovec * | vec,
|  | int * | nvec
| ) |  |

Create an iovec of the elements in a bucket_brigade... return number of elements used. This is useful for writing to a file or to the network efficiently.

Parameters

  b | The bucket brigade to create the iovec from
  vec | The iovec to create
  nvec | The number of elements in the iovec. On return, it is the number of iovec elements actually filled out.

## apr_brigade_vprintf()

apr_status_t apr_brigade_vprintf | ( | apr_bucket_brigade * | b,
|  | apr_brigade_flush | flush,
|  | void * | ctx,
|  | const char * | fmt,
|  | va_list | va
| ) |  |

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
  va | The arguments to fill out the format

Returns
  APR_SUCCESS or error code

## apr_brigade_vputstrs()

apr_status_t apr_brigade_vputstrs | ( | apr_bucket_brigade * | b,
|  | apr_brigade_flush | flush,
|  | void * | ctx,
|  | va_list | va
| ) |  |

This function writes a list 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
  va | A list of strings to add

Returns
  APR_SUCCESS or error code.

## apr_brigade_write()

apr_status_t apr_brigade_write | ( | apr_bucket_brigade * | b,
|  | apr_brigade_flush | flush,
|  | void * | ctx,
|  | const char * | str,
|  | apr_size_t | nbyte
| ) |  |

This function writes a string into a bucket brigade.

The apr_brigade_write function attempts to be efficient with the handling of heap buckets. Regardless of the amount of data stored inside a heap bucket, heap buckets are a fixed size to promote their reuse.

If an attempt is made to write a string to a brigade that already ends with a heap bucket, this function will attempt to pack the string into the remaining space in the previous heap bucket, before allocating a new heap bucket.

This function always returns APR_SUCCESS, unless a flush function is passed, in which case the return value of the flush function will be returned if used.

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
  str | The string to add
  nbyte | The number of bytes to write

Returns
  APR_SUCCESS or error code

## apr_brigade_writev()

apr_status_t apr_brigade_writev | ( | apr_bucket_brigade * | b,
|  | apr_brigade_flush | flush,
|  | void * | ctx,
|  | const struct iovec * | vec,
|  | apr_size_t | nvec
| ) |  |

This function writes multiple 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
  vec | The strings to add (address plus length for each)
  nvec | The number of entries in iovec

Returns
  APR_SUCCESS or error code

## apr_bucket_alloc()

void * apr_bucket_alloc | ( | apr_size_t | size,
|  | apr_bucket_alloc_t * | list
| ) |  |

Allocate memory for use by the buckets.

Parameters

  size | The amount to allocate.
  list | The allocator from which to allocate the memory.

## apr_bucket_alloc_aligned_floor()

apr_size_t apr_bucket_alloc_aligned_floor | ( | apr_bucket_alloc_t * | list,
|  | apr_size_t | size
| ) |  |

Get the aligned size corresponding to the requested size, but minus the allocator(s) overhead such that the allocation would remain in the same boundary.

Parameters

  list | The allocator from which to the memory would be allocated.
  size | The requested size.

Returns
  The corresponding aligned/floored size.

## apr_bucket_alloc_create()

apr_bucket_alloc_t * apr_bucket_alloc_create | ( | apr_pool_t * | p | ) |

Create a bucket allocator.

Parameters

  p | This pool's underlying apr_allocator_t is used to allocate memory for the bucket allocator. When the pool is destroyed, the bucket allocator's cleanup routine will free all memory that has been allocated from it.

Remarks
  The reason the allocator gets its memory from the pool's apr_allocator_t rather than from the pool itself is because the bucket allocator will free large memory blocks back to the allocator when it's done with them, thereby preventing memory footprint growth that would occur if we allocated from the pool.

Warning
  The allocator must never be used by more than one thread at a time.

## apr_bucket_alloc_create_ex()

apr_bucket_alloc_t * apr_bucket_alloc_create_ex | ( | apr_allocator_t * | allocator | ) |

Create a bucket allocator.

Parameters

  allocator | This apr_allocator_t is used to allocate both the bucket allocator and all memory handed out by the bucket allocator. The caller is responsible for destroying the bucket allocator and the apr_allocator_t – no automatic cleanups will happen.

Warning
  The allocator must never be used by more than one thread at a time.

## apr_bucket_alloc_destroy()

void apr_bucket_alloc_destroy | ( | apr_bucket_alloc_t * | list | ) |

Destroy a bucket allocator.

Parameters

  list | The allocator to be destroyed

## apr_bucket_copy_notimpl()

apr_status_t apr_bucket_copy_notimpl | ( | apr_bucket * | e,
|  | apr_bucket ** | c
| ) |  |

A place holder function that signifies that the copy function was not implemented for this bucket

Parameters

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

Returns
  APR_ENOTIMPL

## apr_bucket_destroy_noop()

void apr_bucket_destroy_noop | ( | void * | data | ) |

A place holder function that signifies that this bucket does not need to do anything special to be destroyed. That's only the case for buckets that either have no data (metadata buckets) or buckets whose data pointer points to something that's not a bucket-type-specific structure, as with simple buckets where data points to a string and pipe buckets where data points directly to the apr_file_t.

Parameters

  data | The bucket data to destroy

## apr_bucket_eos_create()

apr_bucket * apr_bucket_eos_create | ( | apr_bucket_alloc_t * | list | ) |

Create an End of Stream bucket. This indicates that there is no more data coming from down the filter stack. All filters should flush at this point.

Parameters

  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_eos_make()

apr_bucket * apr_bucket_eos_make | ( | apr_bucket * | b | ) |

Make the bucket passed in an EOS bucket. This indicates that there is no more data coming from down the filter stack. All filters should flush at this point.

Parameters

  b | The bucket to make into an EOS bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_file_create()

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
| ) |  |

Create a bucket referring to a file.

Parameters

  fd | The file to put in the bucket
  offset | The offset where the data of interest begins in the file
  len | The amount of data in the file we are interested in
  p | The pool into which any needed structures should be created while reading from this file bucket
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

Remarks
  If the file is truncated such that the segment of the file referenced by the bucket no longer exists, an attempt to read from the bucket will fail with APR_EOF.
  apr_brigade_insert_file() should generally be used to insert files into brigades, since that function can correctly handle large file issues.

## apr_bucket_file_enable_mmap()

apr_status_t apr_bucket_file_enable_mmap | ( | apr_bucket * | b,
|  | int | enabled
| ) |  |

Enable or disable memory-mapping for a FILE bucket (default is enabled)

Parameters

  b | The bucket
  enabled | Whether memory-mapping should be enabled

Returns
  APR_SUCCESS normally, or an error code if the operation fails

## apr_bucket_file_make()

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
| ) |  |

Make the bucket passed in a bucket refer to a file

Parameters

  b | The bucket to make into a FILE bucket
  fd | The file to put in the bucket
  offset | The offset where the data of interest begins in the file
  len | The amount of data in the file we are interested in
  p | The pool into which any needed structures should be created while reading from this file bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_file_set_buf_size()

apr_status_t apr_bucket_file_set_buf_size | ( | apr_bucket * | b,
|  | apr_size_t | size
| ) |  |

Set the size of the read buffer allocated by a FILE bucket (default is APR_BUCKET_BUFF_SIZE) memory-mapping is disabled only)

Parameters

  b | The bucket
  size | Size of the allocated buffers

Returns
  APR_SUCCESS normally, or an error code if the operation fails

Remarks
  Relevant/used only when memory-mapping is disabled (

See also
  apr_bucket_file_enable_mmap)

## apr_bucket_flush_create()

apr_bucket * apr_bucket_flush_create | ( | apr_bucket_alloc_t * | list | ) |

Create a flush bucket. This indicates that filters should flush their data. There is no guarantee that they will flush it, but this is the best we can do.

Parameters

  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_flush_make()

apr_bucket * apr_bucket_flush_make | ( | apr_bucket * | b | ) |

Make the bucket passed in a FLUSH bucket. This indicates that filters should flush their data. There is no guarantee that they will flush it, but this is the best we can do.

Parameters

  b | The bucket to make into a FLUSH bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_free()

void apr_bucket_free | ( | void * | block | ) |

Free memory previously allocated with apr_bucket_alloc().

Parameters

  block | The block of memory to be freed.

## apr_bucket_heap_create()

apr_bucket * apr_bucket_heap_create | ( | const char * | buf,
|  | apr_size_t | nbyte,
|  | void(*)(void *data) | free_func,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to memory on the heap. If the caller asks for the data to be copied, this function always allocates 4K of memory so that more data can be added to the bucket without requiring another allocation. Therefore not all the data may be put into the bucket. If copying is not requested then the bucket takes over responsibility for free()ing the memory.

Parameters

  buf | The buffer to insert into the bucket
  nbyte | The size of the buffer to insert.
  free_func | Function to use to free the data; NULL indicates that the bucket should make a copy of the data
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_heap_make()

apr_bucket * apr_bucket_heap_make | ( | apr_bucket * | b,
|  | const char * | buf,
|  | apr_size_t | nbyte,
|  | void(*)(void *data) | free_func
| ) |  |

Make the bucket passed in a bucket refer to heap data

Parameters

  b | The bucket to make into a HEAP bucket
  buf | The buffer to insert into the bucket
  nbyte | The size of the buffer to insert.
  free_func | Function to use to free the data; NULL indicates that the bucket should make a copy of the data

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_immortal_create()

apr_bucket * apr_bucket_immortal_create | ( | const char * | buf,
|  | apr_size_t | nbyte,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to long-lived data.

Parameters

  buf | The data to insert into the bucket
  nbyte | The size of the data to insert.
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_immortal_make()

apr_bucket * apr_bucket_immortal_make | ( | apr_bucket * | b,
|  | const char * | buf,
|  | apr_size_t | nbyte
| ) |  |

Make the bucket passed in a bucket refer to long-lived data

Parameters

  b | The bucket to make into a IMMORTAL bucket
  buf | The data to insert into the bucket
  nbyte | The size of the data to insert.

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_mmap_create()

apr_bucket * apr_bucket_mmap_create | ( | apr_mmap_t * | mm,
|  | apr_off_t | start,
|  | apr_size_t | length,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to mmap()ed memory.

Parameters

  mm | The mmap to insert into the bucket
  start | The offset of the first byte in the mmap that this bucket refers to
  length | The number of bytes referred to by this bucket
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_mmap_make()

apr_bucket * apr_bucket_mmap_make | ( | apr_bucket * | b,
|  | apr_mmap_t * | mm,
|  | apr_off_t | start,
|  | apr_size_t | length
| ) |  |

Make the bucket passed in a bucket refer to an MMAP'ed file

Parameters

  b | The bucket to make into a MMAP bucket
  mm | The mmap to insert into the bucket
  start | The offset of the first byte in the mmap that this bucket refers to
  length | The number of bytes referred to by this bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_pipe_create()

apr_bucket * apr_bucket_pipe_create | ( | apr_file_t * | thispipe,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to a pipe.

Parameters

  thispipe | The pipe to put in the bucket
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_pipe_make()

apr_bucket * apr_bucket_pipe_make | ( | apr_bucket * | b,
|  | apr_file_t * | thispipe
| ) |  |

Make the bucket passed in a bucket refer to a pipe

Parameters

  b | The bucket to make into a PIPE bucket
  thispipe | The pipe to put in the bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_pool_create()

apr_bucket * apr_bucket_pool_create | ( | const char * | buf,
|  | apr_size_t | length,
|  | apr_pool_t * | pool,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to memory allocated from a pool.

Parameters

  buf | The buffer to insert into the bucket
  length | The number of bytes referred to by this bucket
  pool | The pool the memory was allocated from
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_pool_make()

apr_bucket * apr_bucket_pool_make | ( | apr_bucket * | b,
|  | const char * | buf,
|  | apr_size_t | length,
|  | apr_pool_t * | pool
| ) |  |

Make the bucket passed in a bucket refer to pool data

Parameters

  b | The bucket to make into a pool bucket
  buf | The buffer to insert into the bucket
  length | The number of bytes referred to by this bucket
  pool | The pool the memory was allocated from

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_setaside_noop()

apr_status_t apr_bucket_setaside_noop | ( | apr_bucket * | data,
|  | apr_pool_t * | pool
| ) |  |

This function simply returns APR_SUCCESS to denote that the bucket does not require anything to happen for its setaside() function. This is appropriate for buckets that have "immortal" data – the data will live at least as long as the bucket.

Parameters

  data | The bucket to setaside
  pool | The pool defining the desired lifetime of the bucket data

Returns
  APR_SUCCESS

## apr_bucket_setaside_notimpl()

apr_status_t apr_bucket_setaside_notimpl | ( | apr_bucket * | data,
|  | apr_pool_t * | pool
| ) |  |

A place holder function that signifies that the setaside function was not implemented for this bucket

Parameters

  data | The bucket to setaside
  pool | The pool defining the desired lifetime of the bucket data

Returns
  APR_ENOTIMPL

## apr_bucket_shared_copy()

apr_status_t apr_bucket_shared_copy | ( | apr_bucket * | a,
|  | apr_bucket ** | b
| ) |  |

Copy a refcounted bucket, incrementing the reference count. Most reference-counting bucket types will be able to use this function as their copy function without any additional type-specific handling.

Parameters

  a | The bucket to copy
  b | Returns a pointer to the new bucket

Returns
  APR_ENOMEM if allocation failed; or APR_SUCCESS

## apr_bucket_shared_destroy()

int apr_bucket_shared_destroy | ( | void * | data | ) |

Decrement the refcount of the data in the bucket. This function should only be called by type-specific bucket destruction functions.

Parameters

  data | The private data pointer from the bucket to be destroyed

Returns
  TRUE or FALSE; TRUE if the reference count is now zero, indicating that the shared resource itself can be destroyed by the caller.

## apr_bucket_shared_make()

apr_bucket * apr_bucket_shared_make | ( | apr_bucket * | b,
|  | void * | data,
|  | apr_off_t | start,
|  | apr_size_t | length
| ) |  |

Initialize a bucket containing reference-counted data that may be shared. The caller must allocate the bucket if necessary and initialize its type-dependent fields, and allocate and initialize its own private data structure. This function should only be called by type-specific bucket creation functions.

Parameters

  b | The bucket to initialize
  data | A pointer to the private data structure with the reference count at the start
  start | The start of the data in the bucket relative to the private base pointer
  length | The length of the data in the bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_shared_split()

apr_status_t apr_bucket_shared_split | ( | apr_bucket * | b,
|  | apr_size_t | point
| ) |  |

Split a bucket into two at the given point, and adjust the refcount to the underlying data. Most reference-counting bucket types will be able to use this function as their split function without any additional type-specific handling.

Parameters

  b | The bucket to be split
  point | The offset of the first byte in the new bucket

Returns
  APR_EINVAL if the point is not within the bucket; APR_ENOMEM if allocation failed; or APR_SUCCESS

## apr_bucket_simple_copy()

apr_status_t apr_bucket_simple_copy | ( | apr_bucket * | a,
|  | apr_bucket ** | b
| ) |  |

Copy a simple bucket. Most non-reference-counting buckets that allow multiple references to the same block of data (eg transient and immortal) will use this as their copy function without any additional type-specific handling.

Parameters

  a | The bucket to copy
  b | Returns a pointer to the new bucket

Returns
  APR_ENOMEM if allocation failed; or APR_SUCCESS

## apr_bucket_simple_split()

apr_status_t apr_bucket_simple_split | ( | apr_bucket * | b,
|  | apr_size_t | point
| ) |  |

Split a simple bucket into two at the given point. Most non-reference counting buckets that allow multiple references to the same block of data (eg transient and immortal) will use this as their split function without any additional type-specific handling.

Parameters

  b | The bucket to be split
  point | The offset of the first byte in the new bucket

Returns
  APR_EINVAL if the point is not within the bucket; APR_ENOMEM if allocation failed; or APR_SUCCESS

## apr_bucket_socket_create()

apr_bucket * apr_bucket_socket_create | ( | apr_socket_t * | thissock,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to a socket.

Parameters

  thissock | The socket to put in the bucket
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_socket_make()

apr_bucket * apr_bucket_socket_make | ( | apr_bucket * | b,
|  | apr_socket_t * | thissock
| ) |  |

Make the bucket passed in a bucket refer to a socket

Parameters

  b | The bucket to make into a SOCKET bucket
  thissock | The socket to put in the bucket

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_split_notimpl()

apr_status_t apr_bucket_split_notimpl | ( | apr_bucket * | data,
|  | apr_size_t | point
| ) |  |

A place holder function that signifies that the split function was not implemented for this bucket

Parameters

  data | The bucket to split
  point | The location to split the bucket

Returns
  APR_ENOTIMPL

## apr_bucket_transient_create()

apr_bucket * apr_bucket_transient_create | ( | const char * | buf,
|  | apr_size_t | nbyte,
|  | apr_bucket_alloc_t * | list
| ) |  |

Create a bucket referring to data on the stack.

Parameters

  buf | The data to insert into the bucket
  nbyte | The size of the data to insert.
  list | The freelist from which this bucket should be allocated

Returns
  The new bucket, or NULL if allocation failed

## apr_bucket_transient_make()

apr_bucket * apr_bucket_transient_make | ( | apr_bucket * | b,
|  | const char * | buf,
|  | apr_size_t | nbyte
| ) |  |

Make the bucket passed in a bucket refer to stack data

Parameters

  b | The bucket to make into a TRANSIENT bucket
  buf | The data to insert into the bucket
  nbyte | The size of the data to insert.

Returns
  The new bucket, or NULL if allocation failed

## Variable Documentation

## apr_bucket_type_eos

const apr_bucket_type_t apr_bucket_type_eos

extern

The EOS bucket type. This signifies that there will be no more data, ever. All filters MUST send all data to the next filter when they receive a bucket of this type

## apr_bucket_type_file

const apr_bucket_type_t apr_bucket_type_file

extern

The FILE bucket type. This bucket represents a file on disk

## apr_bucket_type_flush

const apr_bucket_type_t apr_bucket_type_flush

extern

There is no apr_bucket_destroy_notimpl, because destruction is required to be implemented (it could be a noop, but only if that makes sense for the bucket type) The flush bucket type. This signifies that all data should be flushed to the next filter. The flush bucket should be sent with the other buckets.

## apr_bucket_type_heap

const apr_bucket_type_t apr_bucket_type_heap

extern

The HEAP bucket type. This bucket represents a data allocated from the heap.

## apr_bucket_type_immortal

const apr_bucket_type_t apr_bucket_type_immortal

extern

The IMMORTAL bucket type. This bucket represents a segment of data that the creator is willing to take responsibility for. The core will do nothing with the data in an immortal bucket

## apr_bucket_type_mmap

const apr_bucket_type_t apr_bucket_type_mmap

extern

The MMAP bucket type. This bucket represents an MMAP'ed file

## apr_bucket_type_pipe

const apr_bucket_type_t apr_bucket_type_pipe

extern

The PIPE bucket type. This bucket represents a pipe to another program.

## apr_bucket_type_pool

const apr_bucket_type_t apr_bucket_type_pool

extern

The POOL bucket type. This bucket represents a data that was allocated from a pool. IF this bucket is still available when the pool is cleared, the data is copied on to the heap.

## apr_bucket_type_socket

const apr_bucket_type_t apr_bucket_type_socket

extern

The SOCKET bucket type. This bucket represents a socket to another machine

## apr_bucket_type_transient

const apr_bucket_type_t apr_bucket_type_transient

extern

The TRANSIENT bucket type. This bucket represents a data allocated off the stack. When the setaside function is called, this data is copied on to the heap