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

 APU_DECLARE (apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p
 APU_DECLARE (apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b)
 APU_DECLARE_NONSTD (apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b
 APU_DECLARE (apr_bucket *) apr_brigade_insert_file(apr_bucket_brigade *bb
 APU_DECLARE_NONSTD (apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p)
 APU_DECLARE_NONSTD (void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list)
 APU_DECLARE_NONSTD (void *) apr_bucket_alloc(apr_size_t size
const char apr_size_t void(*) free_func (void *data))

Variables

apr_bucket_alloc_t * list
apr_bucket * e
apr_bucket apr_bucket_brigade * a
apr_off_t point
apr_off_t apr_bucket ** after_point
int read_all
int apr_off_t * length
char * c
char apr_size_t * len
char apr_size_t apr_pool_t * pool
apr_bucket_brigade * bbIn
apr_bucket_brigade apr_read_type_e block
apr_bucket_brigade
apr_read_type_e apr_off_t 		maxbytes
struct iovec * vec
struct iovec int * nvec
apr_brigade_flush flush
apr_brigade_flush void * ctx
apr_brigade_flush void va_list va
apr_brigade_flush void const char * str
apr_brigade_flush void const
char apr_size_t 		nbyte
apr_brigade_flush void
apr_brigade_flush void const
char * 		fmt
apr_file_t * f
apr_file_t apr_off_t start
apr_file_t apr_off_t apr_off_t
apr_pool_t * 		p
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_flush
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_eos
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_file
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_heap
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_mmap
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_pool
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_pipe
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_immortal
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_transient
APU_DECLARE_DATA const
apr_bucket_type_t 		apr_bucket_type_socket
apr_bucket ** b
void * data
const char * buf
apr_size_t void(* free_func )(void *data)
apr_mmap_t * mm
apr_socket_t * thissock
apr_file_t * thispipe
apr_off_t offset
apr_file_t * fd
int enabled

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

#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

APU_DECLARE ( apr_bucket *   ) 

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

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

APU_DECLARE ( apr_status_t   ) 

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
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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
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
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
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.
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
Open a dbm file by file name and type of DBM
Parameters:
dbm The newly opened database
type The type of the DBM (not all may be available at run time) 
  db   for Berkeley DB files
  gdbm for GDBM files
  ndbm for NDBM files
  sdbm for SDBM files (always available)
  default for the default DBM type
name The dbm file name to open
mode The flag value 
           APR_DBM_READONLY   open for read-only access
           APR_DBM_READWRITE  open for read-write access
           APR_DBM_RWCREATE   open for r/w, create if needed
           APR_DBM_RWTRUNC    open for r/w, truncate if already there
perm Permissions to apply to if created
cntxt The pool to use when creating the dbm
Remarks:
The dbm name may not be a true file name, as many dbm packages append suffixes for seperate data and index files.
Bug:
In apr-util 0.9 and 1.x, the type arg was case insensitive. This was highly inefficient, and as of 2.x the dbm name must be provided in the correct case (lower case for all bundled providers)

Open a dbm file by file name

Parameters:
dbm The newly opened database
name The dbm file name to open
mode The flag value 
           APR_DBM_READONLY   open for read-only access
           APR_DBM_READWRITE  open for read-write access
           APR_DBM_RWCREATE   open for r/w, create if needed
           APR_DBM_RWTRUNC    open for r/w, truncate if already there
perm Permissions to apply to if created
cntxt The pool to use when creating the dbm
Remarks:
The dbm name may not be a true file name, as many dbm packages append suffixes for seperate data and index files.
Fetch a dbm record value by key
Parameters:
dbm The database
key The key datum to find this record
pvalue The value datum retrieved for this record
Store a dbm record value by key
Parameters:
dbm The database
key The key datum to store this record by
value The value datum to store in this record
Delete a dbm record value by key
Parameters:
dbm The database
key The key datum of the record to delete
Remarks:
It is not an error to delete a non-existent record.
Search for a key within the dbm
Parameters:
dbm The database
key The datum describing a key to test
Retrieve the first record key from a dbm
Parameters:
dbm The database
pkey The key datum of the first record
Retrieve the next record key from a dbm
Parameters:
dbm The database
pkey The key datum of the next record
If the specified file/path were passed to apr_dbm_open(), return the actual file/path names which would be (created and) used. At most, two files may be used; used2 may be NULL if only one file is used.
Parameters:
pool The pool for allocating used1 and used2.
type The type of DBM you require info on
See also:
apr_dbm_open_ex
Parameters:
pathname The path name to generate used-names from.
used1 The first pathname used by the apr_dbm implementation.
used2 The second pathname used by apr_dbm. If only one file is used by the specific implementation, this will be set to NULL.
Returns:
An error if the specified type is invalid.
Remarks:
The dbm file(s) don't need to exist. This function only manipulates the pathnames.
Adds a server to a client object
Parameters:
mc The memcache client object to use
ms Server to add
Remarks:
Adding servers is not thread safe, and should be done once at startup.
Warning:
Changing servers after startup may cause keys to go to different servers.
Enables a Server for use again
Parameters:
mc The memcache client object to use
ms Server to Activate
Disable a Server
Parameters:
mc The memcache client object to use
ms Server to Disable
Creates a new Server Object
Parameters:
p Pool to use
host hostname of the server
port port of the server
min minimum number of client sockets to open
smax soft maximum number of client connections to open
max hard maximum number of client connections
ttl time to live in seconds of a client connection
ns location of the new server object
See also:
apr_reslist_create
Remarks:
min, smax, and max are only used when APR_HAS_THREADS
Creates a new memcached client object
Parameters:
p Pool to use
max_servers maximum number of servers
flags Not currently used
mc location of the new memcache client object
Gets a value from the server, allocating the value out of p
Parameters:
mc client to use
p Pool to use
key null terminated string containing the key
baton location of the allocated value
len length of data at baton
flags any flags set by the client for this key
Returns:
Sets a value by key on the server
Parameters:
mc client to use
key null terminated string containing the key
baton data to store on the server
len length of data at baton
timeout time in seconds for the data to live on the server
flags any flags set by the client for this key
Adds value by key on the server
Parameters:
mc client to use
key null terminated string containing the key
baton data to store on the server
len length of data at baton
timeout time for the data to live on the server
flags any flags set by the client for this key
Returns:
APR_SUCCESS if the key was added, APR_EEXIST if the key already exists on the server.
Replaces value by key on the server
Parameters:
mc client to use
key null terminated string containing the key
baton data to store on the server
len length of data at baton
timeout time for the data to live on the server
flags any flags set by the client for this key
Returns:
APR_SUCCESS if the key was added, APR_EEXIST if the key did not exist on the server.
Deletes a key from a server
Parameters:
mc client to use
key null terminated string containing the key
timeout time for the delete to stop other clients from adding
Increments a value
Parameters:
mc client to use
key null terminated string containing the key
n number to increment by
nv new value after incrmenting
Decrements a value
Parameters:
mc client to use
key null terminated string containing the key
n number to decrement by
nv new value after decrementing
Query a server's version
Parameters:
ms server to query
p Pool to allocate answer from
baton location to store server version string
len length of the server version string
Query a server for statistics
Parameters:
ms server to query
p Pool to allocate answer from
stats location of the new statistics structure
create a FIFO queue
Parameters:
queue The new queue
queue_capacity maximum size of the queue
a pool to allocate queue from
push/add an object to the queue, blocking if the queue is already full

Parameters:
queue the queue
data the data
Returns:
APR_EINTR the blocking was interrupted (try again)

APR_EOF the queue has been terminated

APR_SUCCESS on a successful push

pop/get an object from the queue, blocking if the queue is already empty

Parameters:
queue the queue
data the data
Returns:
APR_EINTR the blocking was interrupted (try again)

APR_EOF if the queue has been terminated

APR_SUCCESS on a successful pop

push/add an object to the queue, returning immediately if the queue is full

Parameters:
queue the queue
data the data
Returns:
APR_EINTR the blocking operation was interrupted (try again)

APR_EAGAIN the queue is full

APR_EOF the queue has been terminated

APR_SUCCESS on a successful push

pop/get an object to the queue, returning immediately if the queue is empty

Parameters:
queue the queue
data the data
Returns:
APR_EINTR the blocking operation was interrupted (try again)

APR_EAGAIN the queue is empty

APR_EOF the queue has been terminated

APR_SUCCESS on a successful push

interrupt all the threads blocking on this queue.

Parameters:
queue the queue
terminate the queue, sending an interrupt to all the blocking threads

Parameters:
queue the queue
Create a new resource list with the following parameters:
Parameters:
reslist An address where the pointer to the new resource list will be stored.
min Allowed minimum number of available resources. Zero creates new resources only when needed.
smax Resources will be destroyed to meet this maximum restriction as they expire.
hmax Absolute maximum limit on the number of total resources.
ttl If non-zero, sets the maximum amount of time a resource may be available while exceeding the soft limit.
con Constructor routine that is called to create a new resource.
de Destructor routine that is called to destroy an expired resource.
params Passed to constructor and deconstructor
pool The pool from which to create this resource list. Also the same pool that is passed to the constructor and destructor routines.
Remarks:
If APR has been compiled without thread support, hmax will be automatically set to 1 and values of min and smax will be forced to 1 for any non-zero value.
Destroy the given resource list and all resources controlled by this list. FIXME: Should this block until all resources become available, or maybe just destroy all the free ones, or maybe destroy them even though they might be in use by something else? Currently it will abort if there are resources that haven't been released, so there is an assumption that all resources have been released to the list before calling this function.
Parameters:
reslist The reslist to destroy
Retrieve a resource from the list, creating a new one if necessary. If we have met our maximum number of resources, we will block until one becomes available.

Return a resource back to the list of available resources.

Invalidate a resource in the pool - e.g. a database connection that returns a "lost connection" error and can't be restored. Use this instead of apr_reslist_release if the resource is bad.

Perform routine maintenance on the resource list. This call may instantiate new resources or expire old resources.

Parameters:
reslist The resource list.
Initialize a relocatable memory block to be managed by the apr_rmm API.
Parameters:
rmm The relocatable memory block
lock An apr_anylock_t of the appropriate type of lock, or NULL if no locking is required.
membuf The block of relocatable memory to be managed
memsize The size of relocatable memory block to be managed
cont The pool to use for local storage and management
Remarks:
Both
Parameters:
membuf and
memsize must be aligned (for instance using APR_ALIGN_DEFAULT).
Destroy a managed memory block.
Parameters:
rmm The relocatable memory block to destroy
Attach to a relocatable memory block already managed by the apr_rmm API.
Parameters:
rmm The relocatable memory block
lock An apr_anylock_t of the appropriate type of lock
membuf The block of relocatable memory already under management
cont The pool to use for local storage and management
Detach from the managed block of memory.
Parameters:
rmm The relocatable memory block to detach from
Free allocation returned by apr_rmm_malloc or apr_rmm_calloc.
Parameters:
rmm The relocatable memory block
entity The memory allocation to free
Open an sdbm database by file name
Parameters:
db The newly opened database
name The sdbm file to open
mode The flag values (APR_READ and APR_BINARY flags are implicit) 
           APR_WRITE          open for read-write access
           APR_CREATE         create the sdbm if it does not exist
           APR_TRUNCATE       empty the contents of the sdbm
           APR_EXCL           fail for APR_CREATE if the file exists
           APR_DELONCLOSE     delete the sdbm when closed
           APR_SHARELOCK      support locking across process/machines
perms Permissions to apply to if created
p The pool to use when creating the sdbm
Remarks:
The sdbm name is not a true file name, as sdbm appends suffixes for seperate data and index files.
Close an sdbm file previously opened by apr_sdbm_open
Parameters:
db The database to close
Lock an sdbm database for concurency of multiple operations
Parameters:
db The database to lock
type The lock type 
           APR_FLOCK_SHARED
           APR_FLOCK_EXCLUSIVE
Remarks:
Calls to apr_sdbm_lock may be nested. All apr_sdbm functions perform implicit locking. Since an APR_FLOCK_SHARED lock cannot be portably promoted to an APR_FLOCK_EXCLUSIVE lock, apr_sdbm_store and apr_sdbm_delete calls will fail if an APR_FLOCK_SHARED lock is held. The apr_sdbm_lock call requires the database to be opened with the APR_SHARELOCK mode value.
Release an sdbm lock previously aquired by apr_sdbm_lock
Parameters:
db The database to unlock
Fetch an sdbm record value by key
Parameters:
db The database
value The value datum retrieved for this record
key The key datum to find this record
Store an sdbm record value by key
Parameters:
db The database
key The key datum to store this record by
value The value datum to store in this record
opt The method used to store the record 
           APR_SDBM_INSERT     return an error if the record exists
           APR_SDBM_REPLACE    overwrite any existing record for key
Delete an sdbm record value by key
Parameters:
db The database
key The key datum of the record to delete
Remarks:
It is not an error to delete a non-existent record.
Retrieve the first record key from a dbm
Parameters:
db The database
key The key datum of the first record
Remarks:
The keys returned are not ordered. To traverse the list of keys for an sdbm opened with APR_SHARELOCK, the caller must use apr_sdbm_lock prior to retrieving the first record, and hold the lock until after the last call to apr_sdbm_nextkey.
Retrieve the next record key from an sdbm
Parameters:
db The database
key The key datum of the next record
Returns true if the sdbm database opened for read-only access
Parameters:
db The database to test
Create a thread pool
Parameters:
me The pointer in which to return the newly created apr_thread_pool object, or NULL if thread pool creation fails.
init_threads The number of threads to be created initially, this number will also be used as the initial value for the maximum number of idle threads.
max_threads The maximum number of threads that can be created
pool The pool to use
Returns:
APR_SUCCESS if the thread pool was created successfully. Otherwise, the error code.
Destroy the thread pool and stop all the threads
Returns:
APR_SUCCESS if all threads are stopped.
Schedule a task to the bottom of the tasks of same priority.
Parameters:
me The thread pool
func The task function
param The parameter for the task function
priority The priority of the task.
owner Owner of this task.
Returns:
APR_SUCCESS if the task had been scheduled successfully
Schedule a task to be run after a delay
Parameters:
me The thread pool
func The task function
param The parameter for the task function
time Time in microseconds
owner Owner of this task.
Returns:
APR_SUCCESS if the task had been scheduled successfully
Schedule a task to the top of the tasks of same priority.
Parameters:
me The thread pool
func The task function
param The parameter for the task function
priority The priority of the task.
owner Owner of this task.
Returns:
APR_SUCCESS if the task had been scheduled successfully
Cancel tasks submitted by the owner. If there is any task from the owner that is currently running, the function will spin until the task finished.
Parameters:
me The thread pool
owner Owner of the task
Returns:
APR_SUCCESS if the task has been cancelled successfully
Note:
The task function should not be calling cancel, otherwise the function may get stuck forever. The function assert if it detect such a case.
Get owner of the task currently been executed by the thread.
Parameters:
thd The thread is executing a task
owner Pointer to receive owner of the task.
Returns:
APR_SUCCESS if the owner is retrieved successfully
Parse a given URI, fill in all supplied fields of a apr_uri_t structure. This eliminates the necessity of extracting host, port, path, query info repeatedly in the modules.
Parameters:
p The pool to allocate out of
uri The uri to parse
uptr The apr_uri_t to fill out
Returns:
APR_SUCCESS for success or error code
Special case for CONNECT parsing: it comes with the hostinfo part only
Parameters:
p The pool to allocate out of
hostinfo The hostinfo string to parse
uptr The apr_uri_t to fill out
Returns:
APR_SUCCESS for success or error code
Parse a standard-format string into a UUID
Parameters:
uuid The resulting UUID
uuid_str The formatted UUID
Set up for converting text from one charset to another.
Parameters:
convset The handle to be filled in by this function
topage The name of the target charset
frompage The name of the source charset
pool The pool to use
Remarks:
Specify APR_DEFAULT_CHARSET for one of the charset names to indicate the charset of the source code at compile time. This is useful if there are literal strings in the source code which must be translated according to the charset of the source code. APR_DEFAULT_CHARSET is not useful if the source code of the caller was not encoded in the same charset as APR at compile time.

Specify APR_LOCALE_CHARSET for one of the charset names to indicate the charset of the current locale.

Return APR_EINVAL if unable to procure a convset, or APR_ENOTIMPL if charset transcoding is not available in this instance of apr-util at all (i.e., APR_HAS_XLATE is undefined).

Find out whether or not the specified conversion is single-byte-only.
Parameters:
convset The handle allocated by apr_xlate_open, specifying the parameters of conversion
onoff Output: whether or not the conversion is single-byte-only
Remarks:
Return APR_ENOTIMPL if charset transcoding is not available in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
Convert a buffer of text from one codepage to another.
Parameters:
convset The handle allocated by apr_xlate_open, specifying the parameters of conversion
inbuf The address of the source buffer
inbytes_left Input: the amount of input data to be translated Output: the amount of input data not yet translated
outbuf The address of the destination buffer
outbytes_left Input: the size of the output buffer Output: the amount of the output buffer not yet used
Remarks:
Returns APR_ENOTIMPL if charset transcoding is not available in this instance of apr-util (i.e., APR_HAS_XLATE is undefined). Returns APR_INCOMPLETE if the input buffer ends in an incomplete multi-byte character.
To correctly terminate the output buffer for some multi-byte character set encodings, a final call must be made to this function after the complete input string has been converted, passing the inbuf and inbytes_left parameters as NULL. (Note that this mode only works from version 1.1.0 onwards)

Convert a single-byte character from one charset to another.

Parameters:
convset The handle allocated by apr_xlate_open, specifying the parameters of conversion
inchar The single-byte character to convert.
Warning:
This only works when converting between single-byte character sets. -1 will be returned if the conversion can't be performed.
Close a codepage translation handle.
Parameters:
convset The codepage translation handle to close
Remarks:
Return APR_ENOTIMPL if charset transcoding is not available in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
Parse a File, producing a xml_doc
Parameters:
p The pool for allocating the parse results.
parser A pointer to *parser (needed so calling function can get errors), will be set to NULL on successfull completion.
ppdoc A pointer to *apr_xml_doc (which has the parsed results in it)
xmlfd A file to read from.
buffer_length Buffer length which would be suitable
Returns:
Any errors found during parsing.
Feed input into the parser
Parameters:
parser The XML parser for parsing this data.
data The data to parse.
len The length of the data.
Returns:
Any errors found during parsing.
Remarks:
Use apr_xml_parser_geterror() to get more error information.
Terminate the parsing and return the result
Parameters:
parser The XML parser for parsing this data.
pdoc The resulting parse information. May be NULL to simply terminate the parsing without fetching the info.
Returns:
Any errors found during the final stage of parsing.
Remarks:
Use apr_xml_parser_geterror() to get more error information.
return the URI's (existing) index, or insert it and return a new index
Parameters:
uri_array array to insert into
uri The uri to insert
Returns:
int The uri's index

APU_DECLARE ( apr_bucket_brigade *   ) 

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

APU_DECLARE_NONSTD ( void *   ) 

Allocate memory for use by the buckets.

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

APU_DECLARE_NONSTD ( void   ) 

Destroy a bucket allocator.

Parameters:
list The allocator to be destroyed
Free memory previously allocated with apr_bucket_alloc().
Parameters:
block The block of memory to be freed.
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

APU_DECLARE_NONSTD ( apr_bucket_alloc_t *   ) 

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.
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_pool_t apr_dbd_t int apr_dbd_prepared_t APU_DECLARE_NONSTD ( apr_status_t   ) 

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
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
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
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
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
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
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
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
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
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_dbd_pvselect: select using a prepared statement + args

Parameters:
driver - the driver
pool - working pool
handle - the connection
res - pointer to query results. May point to NULL on entry
statement - the prepared statement to execute
random - Whether to support random-access to results
... - varargs list
Returns:
0 for success or error code
apr_dbd_pvbquery: query using a prepared statement + binary args

Parameters:
driver - the driver
pool - working pool
handle - the connection
nrows - number of rows affected.
statement - the prepared statement to execute
... - varargs list of binary args
Returns:
0 for success or error code
apr_dbd_pvbselect: select using a prepared statement + binary args

Parameters:
driver - the driver
pool - working pool
handle - the connection
res - pointer to query results. May point to NULL on entry
statement - the prepared statement to execute
random - Whether to support random-access to results
... - varargs list of binary args
Returns:
0 for success or error code

Variable Documentation

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_eos

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_file

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_flush

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.

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_heap

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_immortal

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_mmap

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_pipe

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_pool

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.

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_socket

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

APU_DECLARE_DATA const apr_bucket_type_t apr_bucket_type_transient

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

Generated on Mon Jun 15 09:45:29 2009 for Apache Portable Runtime by  doxygen 1.5.8