Apache Portable Runtime
Loading...
Searching...
No Matches
apr_buckets.h
Go to the documentation of this file.
1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16/**
17 * @file apr_buckets.h
18 * @brief APR-UTIL Buckets/Bucket Brigades
19 */
20
21#ifndef APR_BUCKETS_H
22#define APR_BUCKETS_H
23
24#if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG)
25#define APR_RING_DEBUG
26#endif
27
28#include "apu.h"
29#include "apr_network_io.h"
30#include "apr_file_io.h"
31#include "apr_general.h"
32#include "apr_mmap.h"
33#include "apr_errno.h"
34#include "apr_ring.h"
35#include "apr.h"
36#if APR_HAVE_SYS_UIO_H
37#include <sys/uio.h> /* for struct iovec */
38#endif
39#if APR_HAVE_STDARG_H
40#include <stdarg.h>
41#endif
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 * @defgroup APR_Util_Bucket_Brigades Bucket Brigades
49 * @ingroup APR
50 * @{
51 */
52
53/** default bucket buffer size - 8KB minus room for memory allocator headers */
54#define APR_BUCKET_BUFF_SIZE 8000
55
56/** if passed to apr_brigade_split_boundary(), the string length will
57 * be calculated
58 */
59#define APR_BUCKETS_STRING -1
60
61/** Determines how a bucket or brigade should be read */
62typedef enum {
63 APR_BLOCK_READ, /**< block until data becomes available */
64 APR_NONBLOCK_READ /**< return immediately if no data is available */
66
67/**
68 * The one-sentence buzzword-laden overview: Bucket brigades represent
69 * a complex data stream that can be passed through a layered IO
70 * system without unnecessary copying. A longer overview follows...
71 *
72 * A bucket brigade is a doubly linked list (ring) of buckets, so we
73 * aren't limited to inserting at the front and removing at the end.
74 * Buckets are only passed around as members of a brigade, although
75 * singleton buckets can occur for short periods of time.
76 *
77 * Buckets are data stores of various types. They can refer to data in
78 * memory, or part of a file or mmap area, or the output of a process,
79 * etc. Buckets also have some type-dependent accessor functions:
80 * read, split, copy, setaside, and destroy.
81 *
82 * read returns the address and size of the data in the bucket. If the
83 * data isn't in memory then it is read in and the bucket changes type
84 * so that it can refer to the new location of the data. If all the
85 * data doesn't fit in the bucket then a new bucket is inserted into
86 * the brigade to hold the rest of it.
87 *
88 * split divides the data in a bucket into two regions. After a split
89 * the original bucket refers to the first part of the data and a new
90 * bucket inserted into the brigade after the original bucket refers
91 * to the second part of the data. Reference counts are maintained as
92 * necessary.
93 *
94 * setaside ensures that the data in the bucket has a long enough
95 * lifetime. Sometimes it is convenient to create a bucket referring
96 * to data on the stack in the expectation that it will be consumed
97 * (output to the network) before the stack is unwound. If that
98 * expectation turns out not to be valid, the setaside function is
99 * called to move the data somewhere safer.
100 *
101 * copy makes a duplicate of the bucket structure as long as it's
102 * possible to have multiple references to a single copy of the
103 * data itself. Not all bucket types can be copied.
104 *
105 * destroy maintains the reference counts on the resources used by a
106 * bucket and frees them if necessary.
107 *
108 * Note: all of the above functions have wrapper macros (apr_bucket_read(),
109 * apr_bucket_destroy(), etc), and those macros should be used rather
110 * than using the function pointers directly.
111 *
112 * To write a bucket brigade, they are first made into an iovec, so that we
113 * don't write too little data at one time. Currently we ignore compacting the
114 * buckets into as few buckets as possible, but if we really want good
115 * performance, then we need to compact the buckets before we convert to an
116 * iovec, or possibly while we are converting to an iovec.
117 */
118
119/*
120 * Forward declaration of the main types.
121 */
122
123/** @see apr_bucket_brigade */
125/** @see apr_bucket */
126typedef struct apr_bucket apr_bucket;
127/** @see apr_bucket_alloc_t */
129
130/** @see apr_bucket_type_t */
132
133/**
134 * Basic bucket type
135 */
137 /**
138 * The name of the bucket type
139 */
140 const char *name;
141 /**
142 * The number of functions this bucket understands. Can not be less than
143 * five.
144 */
146 /**
147 * Whether the bucket contains metadata (ie, information that
148 * describes the regular contents of the brigade). The metadata
149 * is not returned by apr_bucket_read() and is not indicated by
150 * the ->length of the apr_bucket itself. In other words, an
151 * empty bucket is safe to arbitrarily remove if and only if it
152 * contains no metadata. In this sense, "data" is just raw bytes
153 * that are the "content" of the brigade and "metadata" describes
154 * that data but is not a proper part of it.
155 */
156 enum {
157 /** This bucket type represents actual data to send to the client. */
159 /** This bucket type represents metadata. */
162 /**
163 * Free the private data and any resources used by the bucket (if they
164 * aren't shared with another bucket). This function is required to be
165 * implemented for all bucket types, though it might be a no-op on some
166 * of them (namely ones that never allocate any private data structures).
167 * @param data The private data pointer from the bucket to be destroyed
168 */
169 void (*destroy)(void *data);
170
171 /**
172 * Read the data from the bucket. This is required to be implemented
173 * for all bucket types.
174 * @param b The bucket to read from
175 * @param str A place to store the data read. Allocation should only be
176 * done if absolutely necessary.
177 * @param len The amount of data read.
178 * @param block Should this read function block if there is more data that
179 * cannot be read immediately.
180 */
181 apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len,
182 apr_read_type_e block);
183
184 /**
185 * Make it possible to set aside the data for at least as long as the
186 * given pool. Buckets containing data that could potentially die before
187 * this pool (e.g. the data resides on the stack, in a child pool of
188 * the given pool, or in a disjoint pool) must somehow copy, shift, or
189 * transform the data to have the proper lifetime.
190 * @param e The bucket to convert
191 * @remark Some bucket types contain data that will always outlive the
192 * bucket itself. For example no data (EOS and FLUSH), or the data
193 * resides in global, constant memory (IMMORTAL), or the data is on
194 * the heap (HEAP). For these buckets, apr_bucket_setaside_noop can
195 * be used.
196 */
198
199 /**
200 * Split one bucket in two at the specified position by duplicating
201 * the bucket structure (not the data) and modifying any necessary
202 * start/end/offset information. If it's not possible to do this
203 * for the bucket type (perhaps the length of the data is indeterminate,
204 * as with pipe and socket buckets), then APR_ENOTIMPL is returned.
205 * @param e The bucket to split
206 * @param point The offset of the first byte in the new bucket
207 */
208 apr_status_t (*split)(apr_bucket *e, apr_size_t point);
209
210 /**
211 * Copy the bucket structure (not the data), assuming that this is
212 * possible for the bucket type. If it's not, APR_ENOTIMPL is returned.
213 * @param e The bucket to copy
214 * @param c Returns a pointer to the new bucket
215 */
217
218};
219
220/**
221 * apr_bucket structures are allocated on the malloc() heap and
222 * their lifetime is controlled by the parent apr_bucket_brigade
223 * structure. Buckets can move from one brigade to another e.g. by
224 * calling APR_BRIGADE_CONCAT(). In general the data in a bucket has
225 * the same lifetime as the bucket and is freed when the bucket is
226 * destroyed; if the data is shared by more than one bucket (e.g.
227 * after a split) the data is freed when the last bucket goes away.
228 */
230 /** Links to the rest of the brigade */
232 /** The type of bucket. */
234 /** The length of the data in the bucket. This could have been implemented
235 * with a function, but this is an optimization, because the most
236 * common thing to do will be to get the length. If the length is unknown,
237 * the value of this field will be (apr_size_t)(-1).
238 */
239 apr_size_t length;
240 /** The start of the data in the bucket relative to the private base
241 * pointer. The vast majority of bucket types allow a fixed block of
242 * data to be referenced by multiple buckets, each bucket pointing to
243 * a different segment of the data. That segment starts at base+start
244 * and ends at base+start+length.
245 * If the length == (apr_size_t)(-1), then start == -1.
246 */
247 apr_off_t start;
248 /** type-dependent data hangs off this pointer */
249 void *data;
250 /**
251 * Pointer to function used to free the bucket. This function should
252 * always be defined and it should be consistent with the memory
253 * function used to allocate the bucket. For example, if malloc() is
254 * used to allocate the bucket, this pointer should point to free().
255 * @param e Pointer to the bucket being freed
256 */
257 void (*free)(void *e);
258 /** The freelist from which this bucket was allocated */
260};
261
262/** A list of buckets */
264 /** The pool to associate the brigade with. The data is not allocated out
265 * of the pool, but a cleanup is registered with this pool. If the
266 * brigade is destroyed by some mechanism other than pool destruction,
267 * the destroying function is responsible for killing the cleanup.
268 */
270 /** The buckets in the brigade are on this list. */
271 /*
272 * The apr_bucket_list structure doesn't actually need a name tag
273 * because it has no existence independent of struct apr_bucket_brigade;
274 * the ring macros are designed so that you can leave the name tag
275 * argument empty in this situation but apparently the Windows compiler
276 * doesn't like that.
277 */
278 APR_RING_HEAD(apr_bucket_list, apr_bucket) list;
279 /** The freelist from which this bucket was allocated */
281};
282
283
284/**
285 * Function called when a brigade should be flushed
286 */
288
289/*
290 * define APR_BUCKET_DEBUG if you want your brigades to be checked for
291 * validity at every possible instant. this will slow your code down
292 * substantially but is a very useful debugging tool.
293 */
294#ifdef APR_BUCKET_DEBUG
295
296#define APR_BRIGADE_CHECK_CONSISTENCY(b) do { \
297 APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link); \
298 assert(b->p != NULL); \
299 assert(b->bucket_alloc != NULL); \
300} while (0)
301
302#define APR_BUCKET_CHECK_CONSISTENCY(e) \
303 APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link)
304
305#else
306/**
307 * checks the ring pointers in a bucket brigade for consistency. an
308 * abort() will be triggered if any inconsistencies are found.
309 * note: this is a no-op unless APR_BUCKET_DEBUG is defined.
310 * @param b The brigade
311 */
312#define APR_BRIGADE_CHECK_CONSISTENCY(b)
313/**
314 * checks the brigade a bucket is in for ring consistency. an
315 * abort() will be triggered if any inconsistencies are found.
316 * note: this is a no-op unless APR_BUCKET_DEBUG is defined.
317 * @param e The bucket
318 */
319#define APR_BUCKET_CHECK_CONSISTENCY(e)
320#endif
321
322
323/**
324 * Wrappers around the RING macros to reduce the verbosity of the code
325 * that handles bucket brigades.
326 */
327/**
328 * The magic pointer value that indicates the head of the brigade
329 * @remark This is used to find the beginning and end of the brigade, eg:
330 * <pre>
331 * while (e != APR_BRIGADE_SENTINEL(b)) {
332 * ...
333 * e = APR_BUCKET_NEXT(e);
334 * }
335 * </pre>
336 * @param b The brigade
337 * @return The magic pointer value
338 */
339#define APR_BRIGADE_SENTINEL(b) APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
340
341/**
342 * Determine if the bucket brigade is empty
343 * @param b The brigade to check
344 * @return true or false
345 */
346#define APR_BRIGADE_EMPTY(b) APR_RING_EMPTY(&(b)->list, apr_bucket, link)
347
348/**
349 * Return the first bucket in a brigade
350 * @param b The brigade to query
351 * @return The first bucket in the brigade
352 */
353#define APR_BRIGADE_FIRST(b) APR_RING_FIRST(&(b)->list)
354/**
355 * Return the last bucket in a brigade
356 * @param b The brigade to query
357 * @return The last bucket in the brigade
358 */
359#define APR_BRIGADE_LAST(b) APR_RING_LAST(&(b)->list)
360
361/**
362 * Insert a single bucket at the front of a brigade
363 * @param b The brigade to add to
364 * @param e The bucket to insert
365 */
366#define APR_BRIGADE_INSERT_HEAD(b, e) do { \
367 apr_bucket *ap__b = (e); \
368 APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link); \
369 APR_BRIGADE_CHECK_CONSISTENCY((b)); \
370 } while (0)
371
372/**
373 * Insert a single bucket at the end of a brigade
374 * @param b The brigade to add to
375 * @param e The bucket to insert
376 */
377#define APR_BRIGADE_INSERT_TAIL(b, e) do { \
378 apr_bucket *ap__b = (e); \
379 APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link); \
380 APR_BRIGADE_CHECK_CONSISTENCY((b)); \
381 } while (0)
382
383/**
384 * Concatenate brigade b onto the end of brigade a, leaving brigade b empty
385 * @param a The first brigade
386 * @param b The second brigade
387 */
388#define APR_BRIGADE_CONCAT(a, b) do { \
389 APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link); \
390 APR_BRIGADE_CHECK_CONSISTENCY((a)); \
391 } while (0)
392
393/**
394 * Prepend brigade b onto the beginning of brigade a, leaving brigade b empty
395 * @param a The first brigade
396 * @param b The second brigade
397 */
398#define APR_BRIGADE_PREPEND(a, b) do { \
399 APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link); \
400 APR_BRIGADE_CHECK_CONSISTENCY((a)); \
401 } while (0)
402
403/**
404 * Insert a single bucket before a specified bucket
405 * @param a The bucket to insert before
406 * @param b The bucket to insert
407 */
408#define APR_BUCKET_INSERT_BEFORE(a, b) do { \
409 apr_bucket *ap__a = (a), *ap__b = (b); \
410 APR_RING_INSERT_BEFORE(ap__a, ap__b, link); \
411 APR_BUCKET_CHECK_CONSISTENCY(ap__a); \
412 } while (0)
413
414/**
415 * Insert a single bucket after a specified bucket
416 * @param a The bucket to insert after
417 * @param b The bucket to insert
418 */
419#define APR_BUCKET_INSERT_AFTER(a, b) do { \
420 apr_bucket *ap__a = (a), *ap__b = (b); \
421 APR_RING_INSERT_AFTER(ap__a, ap__b, link); \
422 APR_BUCKET_CHECK_CONSISTENCY(ap__a); \
423 } while (0)
424
425/**
426 * Get the next bucket in the list
427 * @param e The current bucket
428 * @return The next bucket
429 */
430#define APR_BUCKET_NEXT(e) APR_RING_NEXT((e), link)
431/**
432 * Get the previous bucket in the list
433 * @param e The current bucket
434 * @return The previous bucket
435 */
436#define APR_BUCKET_PREV(e) APR_RING_PREV((e), link)
437
438/**
439 * Remove a bucket from its bucket brigade
440 * @param e The bucket to remove
441 */
442#define APR_BUCKET_REMOVE(e) APR_RING_REMOVE((e), link)
443
444/**
445 * Initialize a new bucket's prev/next pointers
446 * @param e The bucket to initialize
447 */
448#define APR_BUCKET_INIT(e) APR_RING_ELEM_INIT((e), link)
449
450/**
451 * Determine if a bucket contains metadata. An empty bucket is
452 * safe to arbitrarily remove if and only if this is false.
453 * @param e The bucket to inspect
454 * @return true or false
455 */
456#define APR_BUCKET_IS_METADATA(e) ((e)->type->is_metadata)
457
458/**
459 * Determine if a bucket is a FLUSH bucket
460 * @param e The bucket to inspect
461 * @return true or false
462 */
463#define APR_BUCKET_IS_FLUSH(e) ((e)->type == &apr_bucket_type_flush)
464/**
465 * Determine if a bucket is an EOS bucket
466 * @param e The bucket to inspect
467 * @return true or false
468 */
469#define APR_BUCKET_IS_EOS(e) ((e)->type == &apr_bucket_type_eos)
470/**
471 * Determine if a bucket is a FILE bucket
472 * @param e The bucket to inspect
473 * @return true or false
474 */
475#define APR_BUCKET_IS_FILE(e) ((e)->type == &apr_bucket_type_file)
476/**
477 * Determine if a bucket is a PIPE bucket
478 * @param e The bucket to inspect
479 * @return true or false
480 */
481#define APR_BUCKET_IS_PIPE(e) ((e)->type == &apr_bucket_type_pipe)
482/**
483 * Determine if a bucket is a SOCKET bucket
484 * @param e The bucket to inspect
485 * @return true or false
486 */
487#define APR_BUCKET_IS_SOCKET(e) ((e)->type == &apr_bucket_type_socket)
488/**
489 * Determine if a bucket is a HEAP bucket
490 * @param e The bucket to inspect
491 * @return true or false
492 */
493#define APR_BUCKET_IS_HEAP(e) ((e)->type == &apr_bucket_type_heap)
494/**
495 * Determine if a bucket is a TRANSIENT bucket
496 * @param e The bucket to inspect
497 * @return true or false
498 */
499#define APR_BUCKET_IS_TRANSIENT(e) ((e)->type == &apr_bucket_type_transient)
500/**
501 * Determine if a bucket is a IMMORTAL bucket
502 * @param e The bucket to inspect
503 * @return true or false
504 */
505#define APR_BUCKET_IS_IMMORTAL(e) ((e)->type == &apr_bucket_type_immortal)
506#if APR_HAS_MMAP
507/**
508 * Determine if a bucket is a MMAP bucket
509 * @param e The bucket to inspect
510 * @return true or false
511 */
512#define APR_BUCKET_IS_MMAP(e) ((e)->type == &apr_bucket_type_mmap)
513#endif
514/**
515 * Determine if a bucket is a POOL bucket
516 * @param e The bucket to inspect
517 * @return true or false
518 */
519#define APR_BUCKET_IS_POOL(e) ((e)->type == &apr_bucket_type_pool)
520
521/*
522 * General-purpose reference counting for the various bucket types.
523 *
524 * Any bucket type that keeps track of the resources it uses (i.e.
525 * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to
526 * attach a reference count to the resource so that it can be freed
527 * when the last bucket that uses it goes away. Resource-sharing may
528 * occur because of bucket splits or buckets that refer to globally
529 * cached data. */
530
531/** @see apr_bucket_refcount */
533/**
534 * The structure used to manage the shared resource must start with an
535 * apr_bucket_refcount which is updated by the general-purpose refcount
536 * code. A pointer to the bucket-type-dependent private data structure
537 * can be cast to a pointer to an apr_bucket_refcount and vice versa.
538 */
540 /** The number of references to this bucket */
542};
543
544/* ***** Reference-counted bucket types ***** */
545
546/** @see apr_bucket_heap */
548/**
549 * A bucket referring to data allocated off the heap.
550 */
552 /** Number of buckets using this memory */
554 /** The start of the data actually allocated. This should never be
555 * modified, it is only used to free the bucket.
556 */
557 char *base;
558 /** how much memory was allocated */
559 apr_size_t alloc_len;
560 /** function to use to delete the data */
561 void (*free_func)(void *data);
562};
563
564/** @see apr_bucket_pool */
566/**
567 * A bucket referring to data allocated from a pool
568 */
570 /** The pool bucket must be able to be easily morphed to a heap
571 * bucket if the pool gets cleaned up before all references are
572 * destroyed. This apr_bucket_heap structure is populated automatically
573 * when the pool gets cleaned up, and subsequent calls to pool_read()
574 * will result in the apr_bucket in question being morphed into a
575 * regular heap bucket. (To avoid having to do many extra refcount
576 * manipulations and b->data manipulations, the apr_bucket_pool
577 * struct actually *contains* the apr_bucket_heap struct that it
578 * will become as its first element; the two share their
579 * apr_bucket_refcount members.)
580 */
582 /** The block of data actually allocated from the pool.
583 * Segments of this block are referenced by adjusting
584 * the start and length of the apr_bucket accordingly.
585 * This will be NULL after the pool gets cleaned up.
586 */
587 const char *base;
588 /** The pool the data was allocated from. When the pool
589 * is cleaned up, this gets set to NULL as an indicator
590 * to pool_read() that the data is now on the heap and
591 * so it should morph the bucket into a regular heap
592 * bucket before continuing.
593 */
595 /** The freelist this structure was allocated from, which is
596 * needed in the cleanup phase in order to allocate space on the heap
597 */
599};
600
601#if APR_HAS_MMAP
602/** @see apr_bucket_mmap */
604/**
605 * A bucket referring to an mmap()ed file
606 */
608 /** Number of buckets using this memory */
610 /** The mmap this sub_bucket refers to */
612};
613#endif
614
615/** @see apr_bucket_file */
617/**
618 * A bucket referring to an file
619 */
621 /** Number of buckets using this memory */
623#if APR_HAS_MMAP
624 /** Whether this bucket should be memory-mapped if
625 * a caller tries to read from it */
627#endif /* APR_HAS_MMAP */
628 /** The file this bucket refers to */
630 /** The pool into which any needed structures should
631 * be created while reading from this file bucket */
633 /** File read block size */
634 apr_size_t read_size;
635};
636
637/** @see apr_bucket_structs */
639/**
640 * A union of all bucket structures so we know what
641 * the max size is.
642 */
644 apr_bucket b; /**< Bucket */
645 apr_bucket_heap heap; /**< Heap */
646 apr_bucket_pool pool; /**< Pool */
647#if APR_HAS_MMAP
648 apr_bucket_mmap mmap; /**< MMap */
649#endif
650 apr_bucket_file file; /**< File */
651};
652
653/**
654 * The amount that apr_bucket_alloc() should allocate in the common case.
655 * Note: this is twice as big as apr_bucket_structs to allow breathing
656 * room for third-party bucket types.
657 */
658#define APR_BUCKET_ALLOC_SIZE APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
659
660/* ***** Bucket Brigade Functions ***** */
661/**
662 * Create a new bucket brigade. The bucket brigade is originally empty.
663 * @param p The pool to associate with the brigade. Data is not allocated out
664 * of the pool, but a cleanup is registered.
665 * @param list The bucket allocator to use
666 * @return The empty bucket brigade
667 */
669 apr_bucket_alloc_t *list)
670 __attribute__((nonnull(1,2)));
671
672/**
673 * Destroy an entire bucket brigade. This includes destroying all of the
674 * buckets within the bucket brigade's bucket list.
675 * @param b The bucket brigade to destroy
676 */
678 __attribute__((nonnull(1)));
679
680/**
681 * Empty out an entire bucket brigade. This includes destroying all of the
682 * buckets within the bucket brigade's bucket list. This is similar to
683 * apr_brigade_destroy(), except that it does not deregister the brigade's
684 * pool cleanup function.
685 * @param data The bucket brigade to clean up
686 * @remark Generally, you should use apr_brigade_destroy(). This function
687 * can be useful in situations where you have a single brigade that
688 * you wish to reuse many times by destroying all of the buckets in
689 * the brigade and putting new buckets into it later.
690 */
692 __attribute__((nonnull(1)));
693
694/**
695 * Move the buckets from the tail end of the existing brigade @a b into
696 * the brigade @a a. If @a a is NULL a new brigade is created. Buckets
697 * from @a e to the last bucket (inclusively) of brigade @a b are moved
698 * from @a b to the returned brigade @a a.
699 *
700 * @param b The brigade to split
701 * @param e The first bucket to move
702 * @param a The brigade which should be used for the result or NULL if
703 * a new brigade should be created. The brigade @a a will be
704 * cleared if it is not empty.
705 * @return The brigade supplied in @a a or a new one if @a a was NULL.
706 * @warning Note that this function allocates a new brigade if @a a is
707 * NULL so memory consumption should be carefully considered.
708 */
710 apr_bucket *e,
712 __attribute__((nonnull(1,2)));
713
714/**
715 * Create a new bucket brigade and move the buckets from the tail end
716 * of an existing brigade into the new brigade. Buckets from
717 * @a e to the last bucket (inclusively) of brigade @a b
718 * are moved from @a b to the returned brigade.
719 * @param b The brigade to split
720 * @param e The first bucket to move
721 * @return The new brigade
722 * @warning Note that this function always allocates a new brigade
723 * so memory consumption should be carefully considered.
724 */
726 apr_bucket *e)
727 __attribute__((nonnull(1,2)));
728
729/**
730 * Partition a bucket brigade at a given offset (in bytes from the start of
731 * the brigade). This is useful whenever a filter wants to use known ranges
732 * of bytes from the brigade; the ranges can even overlap.
733 * @param b The brigade to partition
734 * @param point The offset at which to partition the brigade
735 * @param after_point Returns a pointer to the first bucket after the partition
736 * @return APR_SUCCESS on success, APR_INCOMPLETE if the contents of the
737 * brigade were shorter than @a point, or an error code.
738 * @remark if APR_INCOMPLETE is returned, @a after_point will be set to
739 * the brigade sentinel.
740 */
742 apr_off_t point,
743 apr_bucket **after_point)
744 __attribute__((nonnull(1,3)));
745
746/**
747 * Return the total length of the brigade.
748 * @param bb The brigade to compute the length of
749 * @param read_all Read unknown-length buckets to force a size
750 * @param length Returns the length of the brigade (up to the end, or up
751 * to a bucket read error), or -1 if the brigade has buckets
752 * of indeterminate length and read_all is 0.
753 */
755 int read_all,
756 apr_off_t *length)
757 __attribute__((nonnull(1,3)));
758
759/**
760 * Take a bucket brigade and store the data in a flat char*
761 * @param bb The bucket brigade to create the char* from
762 * @param c The char* to write into
763 * @param len The maximum length of the char array. On return, it is the
764 * actual length of the char array.
765 */
767 char *c,
768 apr_size_t *len)
769 __attribute__((nonnull(1,2,3)));
770
771/**
772 * Creates a pool-allocated string representing a flat bucket brigade
773 * @param bb The bucket brigade to create the char array from
774 * @param c On return, the allocated char array
775 * @param len On return, the length of the char array.
776 * @param pool The pool to allocate the string from.
777 */
779 char **c,
780 apr_size_t *len,
781 apr_pool_t *pool)
782 __attribute__((nonnull(1,2,3,4)));
783
784/**
785 * Split a brigade to represent one LF line.
786 * @param bbOut The bucket brigade that will have the LF line appended to.
787 * @param bbIn The input bucket brigade to search for a LF-line.
788 * @param block The blocking mode to be used to split the line.
789 * @param maxbytes The maximum bytes to read. If this many bytes are seen
790 * without a LF, the brigade will contain a partial line.
791 */
793 apr_bucket_brigade *bbIn,
794 apr_read_type_e block,
795 apr_off_t maxbytes)
796 __attribute__((nonnull(1,2)));
797
798/**
799 * Split a brigade based on the provided boundary, or metadata buckets,
800 * whichever are encountered first.
801 *
802 * If the boundary is found, all buckets prior to the boundary are passed
803 * into bbOut, and APR_SUCCESS is returned.
804 *
805 * If a metadata bucket is found, or if the boundary is not found within
806 * the limit specified by maxbytes, all prior buckets are passed into bbOut,
807 * and APR_INCOMPLETE is returned.
808 *
809 * Any partial matches at the end of a bucket will be held back
810 * If the boundary is NULL or the empty string, APR_EINVAL is returned.
811 *
812 * If an error is encountered, the APR error code will be returned.
813 *
814 * @param bbOut The bucket brigade that will have the LF line appended to.
815 * @param bbIn The input bucket brigade to search for a LF-line.
816 * @param block The blocking mode to be used to split the line.
817 * @param boundary The boundary string.
818 * @param boundary_len The length of the boundary string. If set to
819 * APR_BUCKETS_STRING, the length will be calculated.
820 * @param maxbytes The maximum bytes to read.
821 */
823 apr_bucket_brigade *bbIn,
824 apr_read_type_e block,
825 const char *boundary,
826 apr_size_t boundary_len,
827 apr_off_t maxbytes)
828 __attribute__((nonnull(1,2)));
829
830/**
831 * Create an iovec of the elements in a bucket_brigade... return number
832 * of elements used. This is useful for writing to a file or to the
833 * network efficiently.
834 * @param b The bucket brigade to create the iovec from
835 * @param vec The iovec to create
836 * @param nvec The number of elements in the iovec. On return, it is the
837 * number of iovec elements actually filled out.
838 */
840 struct iovec *vec, int *nvec)
841 __attribute__((nonnull(1,2,3)));
842
843/**
844 * This function writes a list of strings into a bucket brigade.
845 * @param b The bucket brigade to add to
846 * @param flush The flush function to use if the brigade is full
847 * @param ctx The structure to pass to the flush function
848 * @param va A list of strings to add
849 * @return APR_SUCCESS or error code.
850 */
852 apr_brigade_flush flush,
853 void *ctx,
854 va_list va)
855 __attribute__((nonnull(1)));
856
857/**
858 * This function writes a string into a bucket brigade.
859 *
860 * The apr_brigade_write function attempts to be efficient with the
861 * handling of heap buckets. Regardless of the amount of data stored
862 * inside a heap bucket, heap buckets are a fixed size to promote their
863 * reuse.
864 *
865 * If an attempt is made to write a string to a brigade that already
866 * ends with a heap bucket, this function will attempt to pack the
867 * string into the remaining space in the previous heap bucket, before
868 * allocating a new heap bucket.
869 *
870 * This function always returns APR_SUCCESS, unless a flush function is
871 * passed, in which case the return value of the flush function will be
872 * returned if used.
873 * @param b The bucket brigade to add to
874 * @param flush The flush function to use if the brigade is full
875 * @param ctx The structure to pass to the flush function
876 * @param str The string to add
877 * @param nbyte The number of bytes to write
878 * @return APR_SUCCESS or error code
879 */
881 apr_brigade_flush flush, void *ctx,
882 const char *str, apr_size_t nbyte)
883 __attribute__((nonnull(1,4)));
884
885/**
886 * This function writes multiple strings into a bucket brigade.
887 * @param b The bucket brigade to add to
888 * @param flush The flush function to use if the brigade is full
889 * @param ctx The structure to pass to the flush function
890 * @param vec The strings to add (address plus length for each)
891 * @param nvec The number of entries in iovec
892 * @return APR_SUCCESS or error code
893 */
895 apr_brigade_flush flush,
896 void *ctx,
897 const struct iovec *vec,
898 apr_size_t nvec)
899 __attribute__((nonnull(1,4)));
900
901/**
902 * This function writes a string into a bucket brigade.
903 * @param bb The bucket brigade to add to
904 * @param flush The flush function to use if the brigade is full
905 * @param ctx The structure to pass to the flush function
906 * @param str The string to add
907 * @return APR_SUCCESS or error code
908 */
910 apr_brigade_flush flush, void *ctx,
911 const char *str)
912 __attribute__((nonnull(1,4)));
913
914/**
915 * This function writes a character into a bucket brigade.
916 * @param b The bucket brigade to add to
917 * @param flush The flush function to use if the brigade is full
918 * @param ctx The structure to pass to the flush function
919 * @param c The character to add
920 * @return APR_SUCCESS or error code
921 */
923 apr_brigade_flush flush, void *ctx,
924 const char c)
925 __attribute__((nonnull(1)));
926
927/**
928 * This function writes an unspecified number of strings into a bucket brigade.
929 * @param b The bucket brigade to add to
930 * @param flush The flush function to use if the brigade is full
931 * @param ctx The structure to pass to the flush function
932 * @param ... The strings to add. The final string must be NULL
933 * @return APR_SUCCESS or error code
934 */
936 apr_brigade_flush flush,
937 void *ctx, ...)
938#if defined(__GNUC__) && __GNUC__ >= 4
939 __attribute__((sentinel))
940#endif
941 __attribute__((nonnull(1)))
942 ;
943
944/**
945 * Evaluate a printf and put the resulting string at the end
946 * of the bucket brigade.
947 * @param b The brigade to write to
948 * @param flush The flush function to use if the brigade is full
949 * @param ctx The structure to pass to the flush function
950 * @param fmt The format of the string to write
951 * @param ... The arguments to fill out the format
952 * @return APR_SUCCESS or error code
953 */
955 apr_brigade_flush flush,
956 void *ctx,
957 const char *fmt, ...)
958 __attribute__((format(printf,4,5)))
959 __attribute__((nonnull(1)));
960
961/**
962 * Evaluate a printf and put the resulting string at the end
963 * of the bucket brigade.
964 * @param b The brigade to write to
965 * @param flush The flush function to use if the brigade is full
966 * @param ctx The structure to pass to the flush function
967 * @param fmt The format of the string to write
968 * @param va The arguments to fill out the format
969 * @return APR_SUCCESS or error code
970 */
972 apr_brigade_flush flush,
973 void *ctx,
974 const char *fmt, va_list va)
975 __attribute__((nonnull(1,4)));
976
977/**
978 * Utility function to insert a file (or a segment of a file) onto the
979 * end of the brigade. The file is split into multiple buckets if it
980 * is larger than the maximum size which can be represented by a
981 * single bucket.
982 * @param bb the brigade to insert into
983 * @param f the file to insert
984 * @param start the offset of the start of the segment
985 * @param len the length of the segment of the file to insert
986 * @param p pool from which file buckets are allocated
987 * @return the last bucket inserted
988 */
990 apr_file_t *f,
991 apr_off_t start,
992 apr_off_t len,
993 apr_pool_t *p)
994 __attribute__((nonnull(1,2,5)));
995
996
997
998/* ***** Bucket freelist functions ***** */
999/**
1000 * Create a bucket allocator.
1001 * @param p This pool's underlying apr_allocator_t is used to allocate memory
1002 * for the bucket allocator. When the pool is destroyed, the bucket
1003 * allocator's cleanup routine will free all memory that has been
1004 * allocated from it.
1005 * @remark The reason the allocator gets its memory from the pool's
1006 * apr_allocator_t rather than from the pool itself is because
1007 * the bucket allocator will free large memory blocks back to the
1008 * allocator when it's done with them, thereby preventing memory
1009 * footprint growth that would occur if we allocated from the pool.
1010 * @warning The allocator must never be used by more than one thread at a time.
1011 */
1013
1014/**
1015 * Create a bucket allocator.
1016 * @param allocator This apr_allocator_t is used to allocate both the bucket
1017 * allocator and all memory handed out by the bucket allocator. The
1018 * caller is responsible for destroying the bucket allocator and the
1019 * apr_allocator_t -- no automatic cleanups will happen.
1020 * @warning The allocator must never be used by more than one thread at a time.
1021 */
1023 apr_allocator_t *allocator)
1024 __attribute__((nonnull(1)));
1025
1026/**
1027 * Destroy a bucket allocator.
1028 * @param list The allocator to be destroyed
1029 */
1031 __attribute__((nonnull(1)));
1032
1033/**
1034 * Get the aligned size corresponding to the requested size, but minus the
1035 * allocator(s) overhead such that the allocation would remain in the
1036 * same boundary.
1037 * @param list The allocator from which to the memory would be allocated.
1038 * @param size The requested size.
1039 * @return The corresponding aligned/floored size.
1040 */
1042 apr_size_t size)
1043 __attribute__((nonnull(1)));
1044
1045/**
1046 * Allocate memory for use by the buckets.
1047 * @param size The amount to allocate.
1048 * @param list The allocator from which to allocate the memory.
1049 */
1050APR_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size,
1051 apr_bucket_alloc_t *list)
1052 __attribute__((nonnull(2)));
1053
1054/**
1055 * Free memory previously allocated with apr_bucket_alloc().
1056 * @param block The block of memory to be freed.
1057 */
1059 __attribute__((nonnull(1)));
1060
1061
1062/* ***** Bucket Functions ***** */
1063/**
1064 * Free the resources used by a bucket. If multiple buckets refer to
1065 * the same resource it is freed when the last one goes away.
1066 * @see apr_bucket_delete()
1067 * @param e The bucket to destroy
1068 */
1069#define apr_bucket_destroy(e) do { \
1070 apr_bucket *apr__d = (e); \
1071 apr__d->type->destroy(apr__d->data); \
1072 apr__d->free(apr__d); \
1073 } while (0)
1074
1075/**
1076 * Delete a bucket by removing it from its brigade (if any) and then
1077 * destroying it.
1078 * @remark This mainly acts as an aid in avoiding code verbosity. It is
1079 * the preferred exact equivalent to:
1080 * <pre>
1081 * APR_BUCKET_REMOVE(e);
1082 * apr_bucket_destroy(e);
1083 * </pre>
1084 * @param e The bucket to delete
1085 */
1086#define apr_bucket_delete(e) do { \
1087 apr_bucket *apr__b = (e); \
1088 APR_BUCKET_REMOVE(apr__b); \
1089 apr_bucket_destroy(apr__b); \
1090 } while (0)
1091
1092/**
1093 * Read some data from the bucket.
1094 *
1095 * The apr_bucket_read function returns a convenient amount of data
1096 * from the bucket provided, writing the address and length of the
1097 * data to the pointers provided by the caller. The function tries
1098 * as hard as possible to avoid a memory copy.
1099 *
1100 * Buckets are expected to be a member of a brigade at the time they
1101 * are read.
1102 *
1103 * In typical application code, buckets are read in a loop, and after
1104 * each bucket is read and processed, it is moved or deleted from the
1105 * brigade and the next bucket read.
1106 *
1107 * The definition of "convenient" depends on the type of bucket that
1108 * is being read, and is decided by APR. In the case of memory based
1109 * buckets such as heap and immortal buckets, a pointer will be
1110 * returned to the location of the buffer containing the complete
1111 * contents of the bucket.
1112 *
1113 * Some buckets, such as the socket bucket, might have no concept
1114 * of length. If an attempt is made to read such a bucket, the
1115 * apr_bucket_read function will read a convenient amount of data
1116 * from the socket. The socket bucket is magically morphed into a
1117 * heap bucket containing the just-read data, and a new socket bucket
1118 * is inserted just after this heap bucket.
1119 *
1120 * To understand why apr_bucket_read might do this, consider the loop
1121 * described above to read and process buckets. The current bucket
1122 * is magically morphed into a heap bucket and returned to the caller.
1123 * The caller processes the data, and deletes the heap bucket, moving
1124 * onto the next bucket, the new socket bucket. This process repeats,
1125 * giving the illusion of a bucket brigade that contains potentially
1126 * infinite amounts of data. It is up to the caller to decide at what
1127 * point to stop reading buckets.
1128 *
1129 * Some buckets, such as the file bucket, might have a fixed size,
1130 * but be significantly larger than is practical to store in RAM in
1131 * one go. As with the socket bucket, if an attempt is made to read
1132 * from a file bucket, the file bucket is magically morphed into a
1133 * heap bucket containing a convenient amount of data read from the
1134 * current offset in the file. During the read, the offset will be
1135 * moved forward on the file, and a new file bucket will be inserted
1136 * directly after the current bucket representing the remainder of the
1137 * file. If the heap bucket was large enough to store the whole
1138 * remainder of the file, no more file buckets are inserted, and the
1139 * file bucket will disappear completely.
1140 *
1141 * The pattern for reading buckets described above does create the
1142 * illusion that the code is willing to swallow buckets that might be
1143 * too large for the system to handle in one go. This however is just
1144 * an illusion: APR will always ensure that large (file) or infinite
1145 * (socket) buckets are broken into convenient bite sized heap buckets
1146 * before data is returned to the caller.
1147 *
1148 * There is a potential gotcha to watch for: if buckets are read in a
1149 * loop, and aren't deleted after being processed, the potentially large
1150 * bucket will slowly be converted into RAM resident heap buckets. If
1151 * the file is larger than available RAM, an out of memory condition
1152 * could be caused if the application is not careful to manage this.
1153 *
1154 * @param e The bucket to read from
1155 * @param str The location to store a pointer to the data in
1156 * @param len The location to store the amount of data read
1157 * @param block Whether the read function blocks
1158 */
1159#define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)
1160
1161/**
1162 * Setaside data so that stack data is not destroyed on returning from
1163 * the function
1164 * @param e The bucket to setaside
1165 * @param p The pool to setaside into
1166 */
1167#define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)
1168
1169/**
1170 * Split one bucket in two at the point provided.
1171 *
1172 * Once split, the original bucket becomes the first of the two new buckets.
1173 *
1174 * (It is assumed that the bucket is a member of a brigade when this
1175 * function is called).
1176 * @param e The bucket to split
1177 * @param point The offset to split the bucket at
1178 */
1179#define apr_bucket_split(e,point) (e)->type->split(e, point)
1180
1181/**
1182 * Copy a bucket.
1183 * @param e The bucket to copy
1184 * @param c Returns a pointer to the new bucket
1185 */
1186#define apr_bucket_copy(e,c) (e)->type->copy(e, c)
1187
1188/* Bucket type handling */
1189
1190/**
1191 * This function simply returns APR_SUCCESS to denote that the bucket does
1192 * not require anything to happen for its setaside() function. This is
1193 * appropriate for buckets that have "immortal" data -- the data will live
1194 * at least as long as the bucket.
1195 * @param data The bucket to setaside
1196 * @param pool The pool defining the desired lifetime of the bucket data
1197 * @return APR_SUCCESS
1198 */
1200 apr_pool_t *pool);
1201
1202/**
1203 * A place holder function that signifies that the setaside function was not
1204 * implemented for this bucket
1205 * @param data The bucket to setaside
1206 * @param pool The pool defining the desired lifetime of the bucket data
1207 * @return APR_ENOTIMPL
1208 */
1210 apr_pool_t *pool);
1211
1212/**
1213 * A place holder function that signifies that the split function was not
1214 * implemented for this bucket
1215 * @param data The bucket to split
1216 * @param point The location to split the bucket
1217 * @return APR_ENOTIMPL
1218 */
1220 apr_size_t point);
1221
1222/**
1223 * A place holder function that signifies that the copy function was not
1224 * implemented for this bucket
1225 * @param e The bucket to copy
1226 * @param c Returns a pointer to the new bucket
1227 * @return APR_ENOTIMPL
1228 */
1230 apr_bucket **c);
1231
1232/**
1233 * A place holder function that signifies that this bucket does not need
1234 * to do anything special to be destroyed. That's only the case for buckets
1235 * that either have no data (metadata buckets) or buckets whose data pointer
1236 * points to something that's not a bucket-type-specific structure, as with
1237 * simple buckets where data points to a string and pipe buckets where data
1238 * points directly to the apr_file_t.
1239 * @param data The bucket data to destroy
1240 */
1242
1243/**
1244 * There is no apr_bucket_destroy_notimpl, because destruction is required
1245 * to be implemented (it could be a noop, but only if that makes sense for
1246 * the bucket type)
1247 */
1248
1249/* There is no apr_bucket_read_notimpl, because it is a required function
1250 */
1251
1252
1253/* All of the bucket types implemented by the core */
1254/**
1255 * The flush bucket type. This signifies that all data should be flushed to
1256 * the next filter. The flush bucket should be sent with the other buckets.
1257 */
1259/**
1260 * The EOS bucket type. This signifies that there will be no more data, ever.
1261 * All filters MUST send all data to the next filter when they receive a
1262 * bucket of this type
1263 */
1265/**
1266 * The FILE bucket type. This bucket represents a file on disk
1267 */
1269/**
1270 * The HEAP bucket type. This bucket represents a data allocated from the
1271 * heap.
1272 */
1274#if APR_HAS_MMAP
1275/**
1276 * The MMAP bucket type. This bucket represents an MMAP'ed file
1277 */
1279#endif
1280/**
1281 * The POOL bucket type. This bucket represents a data that was allocated
1282 * from a pool. IF this bucket is still available when the pool is cleared,
1283 * the data is copied on to the heap.
1284 */
1286/**
1287 * The PIPE bucket type. This bucket represents a pipe to another program.
1288 */
1290/**
1291 * The IMMORTAL bucket type. This bucket represents a segment of data that
1292 * the creator is willing to take responsibility for. The core will do
1293 * nothing with the data in an immortal bucket
1294 */
1296/**
1297 * The TRANSIENT bucket type. This bucket represents a data allocated off
1298 * the stack. When the setaside function is called, this data is copied on
1299 * to the heap
1300 */
1302/**
1303 * The SOCKET bucket type. This bucket represents a socket to another machine
1304 */
1306
1307
1308/* ***** Simple buckets ***** */
1309
1310/**
1311 * Split a simple bucket into two at the given point. Most non-reference
1312 * counting buckets that allow multiple references to the same block of
1313 * data (eg transient and immortal) will use this as their split function
1314 * without any additional type-specific handling.
1315 * @param b The bucket to be split
1316 * @param point The offset of the first byte in the new bucket
1317 * @return APR_EINVAL if the point is not within the bucket;
1318 * APR_ENOMEM if allocation failed;
1319 * or APR_SUCCESS
1320 */
1322 apr_size_t point);
1323
1324/**
1325 * Copy a simple bucket. Most non-reference-counting buckets that allow
1326 * multiple references to the same block of data (eg transient and immortal)
1327 * will use this as their copy function without any additional type-specific
1328 * handling.
1329 * @param a The bucket to copy
1330 * @param b Returns a pointer to the new bucket
1331 * @return APR_ENOMEM if allocation failed;
1332 * or APR_SUCCESS
1333 */
1335 apr_bucket **b);
1336
1337
1338/* ***** Shared, reference-counted buckets ***** */
1339
1340/**
1341 * Initialize a bucket containing reference-counted data that may be
1342 * shared. The caller must allocate the bucket if necessary and
1343 * initialize its type-dependent fields, and allocate and initialize
1344 * its own private data structure. This function should only be called
1345 * by type-specific bucket creation functions.
1346 * @param b The bucket to initialize
1347 * @param data A pointer to the private data structure
1348 * with the reference count at the start
1349 * @param start The start of the data in the bucket
1350 * relative to the private base pointer
1351 * @param length The length of the data in the bucket
1352 * @return The new bucket, or NULL if allocation failed
1353 */
1355 apr_off_t start,
1356 apr_size_t length);
1357
1358/**
1359 * Decrement the refcount of the data in the bucket. This function
1360 * should only be called by type-specific bucket destruction functions.
1361 * @param data The private data pointer from the bucket to be destroyed
1362 * @return TRUE or FALSE; TRUE if the reference count is now
1363 * zero, indicating that the shared resource itself can
1364 * be destroyed by the caller.
1365 */
1367
1368/**
1369 * Split a bucket into two at the given point, and adjust the refcount
1370 * to the underlying data. Most reference-counting bucket types will
1371 * be able to use this function as their split function without any
1372 * additional type-specific handling.
1373 * @param b The bucket to be split
1374 * @param point The offset of the first byte in the new bucket
1375 * @return APR_EINVAL if the point is not within the bucket;
1376 * APR_ENOMEM if allocation failed;
1377 * or APR_SUCCESS
1378 */
1380 apr_size_t point);
1381
1382/**
1383 * Copy a refcounted bucket, incrementing the reference count. Most
1384 * reference-counting bucket types will be able to use this function
1385 * as their copy function without any additional type-specific handling.
1386 * @param a The bucket to copy
1387 * @param b Returns a pointer to the new bucket
1388 * @return APR_ENOMEM if allocation failed;
1389 or APR_SUCCESS
1390 */
1392 apr_bucket **b);
1393
1394
1395/* ***** Functions to Create Buckets of varying types ***** */
1396/*
1397 * Each bucket type foo has two initialization functions:
1398 * apr_bucket_foo_make which sets up some already-allocated memory as a
1399 * bucket of type foo; and apr_bucket_foo_create which allocates memory
1400 * for the bucket, calls apr_bucket_make_foo, and initializes the
1401 * bucket's list pointers. The apr_bucket_foo_make functions are used
1402 * inside the bucket code to change the type of buckets in place;
1403 * other code should call apr_bucket_foo_create. All the initialization
1404 * functions change nothing if they fail.
1405 */
1406
1407/**
1408 * Create an End of Stream bucket. This indicates that there is no more data
1409 * coming from down the filter stack. All filters should flush at this point.
1410 * @param list The freelist from which this bucket should be allocated
1411 * @return The new bucket, or NULL if allocation failed
1412 */
1414
1415/**
1416 * Make the bucket passed in an EOS bucket. This indicates that there is no
1417 * more data coming from down the filter stack. All filters should flush at
1418 * this point.
1419 * @param b The bucket to make into an EOS bucket
1420 * @return The new bucket, or NULL if allocation failed
1421 */
1423 __attribute__((nonnull(1)));
1424
1425/**
1426 * Create a flush bucket. This indicates that filters should flush their
1427 * data. There is no guarantee that they will flush it, but this is the
1428 * best we can do.
1429 * @param list The freelist from which this bucket should be allocated
1430 * @return The new bucket, or NULL if allocation failed
1431 */
1433 __attribute__((nonnull(1)));
1434
1435/**
1436 * Make the bucket passed in a FLUSH bucket. This indicates that filters
1437 * should flush their data. There is no guarantee that they will flush it,
1438 * but this is the best we can do.
1439 * @param b The bucket to make into a FLUSH bucket
1440 * @return The new bucket, or NULL if allocation failed
1441 */
1443 __attribute__((nonnull(1)));
1444
1445/**
1446 * Create a bucket referring to long-lived data.
1447 * @param buf The data to insert into the bucket
1448 * @param nbyte The size of the data to insert.
1449 * @param list The freelist from which this bucket should be allocated
1450 * @return The new bucket, or NULL if allocation failed
1451 */
1453 apr_size_t nbyte,
1454 apr_bucket_alloc_t *list)
1455 __attribute__((nonnull(1,3)));
1456
1457/**
1458 * Make the bucket passed in a bucket refer to long-lived data
1459 * @param b The bucket to make into a IMMORTAL bucket
1460 * @param buf The data to insert into the bucket
1461 * @param nbyte The size of the data to insert.
1462 * @return The new bucket, or NULL if allocation failed
1463 */
1465 const char *buf,
1466 apr_size_t nbyte)
1467 __attribute__((nonnull(1,2)));
1468
1469/**
1470 * Create a bucket referring to data on the stack.
1471 * @param buf The data to insert into the bucket
1472 * @param nbyte The size of the data to insert.
1473 * @param list The freelist from which this bucket should be allocated
1474 * @return The new bucket, or NULL if allocation failed
1475 */
1477 apr_size_t nbyte,
1478 apr_bucket_alloc_t *list)
1479 __attribute__((nonnull(1,3)));
1480
1481/**
1482 * Make the bucket passed in a bucket refer to stack data
1483 * @param b The bucket to make into a TRANSIENT bucket
1484 * @param buf The data to insert into the bucket
1485 * @param nbyte The size of the data to insert.
1486 * @return The new bucket, or NULL if allocation failed
1487 */
1489 const char *buf,
1490 apr_size_t nbyte)
1491 __attribute__((nonnull(1,2)));
1492
1493/**
1494 * Create a bucket referring to memory on the heap. If the caller asks
1495 * for the data to be copied, this function always allocates 4K of
1496 * memory so that more data can be added to the bucket without
1497 * requiring another allocation. Therefore not all the data may be put
1498 * into the bucket. If copying is not requested then the bucket takes
1499 * over responsibility for free()ing the memory.
1500 * @param buf The buffer to insert into the bucket
1501 * @param nbyte The size of the buffer to insert.
1502 * @param free_func Function to use to free the data; NULL indicates that the
1503 * bucket should make a copy of the data
1504 * @param list The freelist from which this bucket should be allocated
1505 * @return The new bucket, or NULL if allocation failed
1506 */
1508 apr_size_t nbyte,
1509 void (*free_func)(void *data),
1510 apr_bucket_alloc_t *list)
1511 __attribute__((nonnull(1,4)));
1512/**
1513 * Make the bucket passed in a bucket refer to heap data
1514 * @param b The bucket to make into a HEAP bucket
1515 * @param buf The buffer to insert into the bucket
1516 * @param nbyte The size of the buffer to insert.
1517 * @param free_func Function to use to free the data; NULL indicates that the
1518 * bucket should make a copy of the data
1519 * @return The new bucket, or NULL if allocation failed
1520 */
1522 apr_size_t nbyte,
1523 void (*free_func)(void *data))
1524 __attribute__((nonnull(1,2)));
1525
1526/**
1527 * Create a bucket referring to memory allocated from a pool.
1528 *
1529 * @param buf The buffer to insert into the bucket
1530 * @param length The number of bytes referred to by this bucket
1531 * @param pool The pool the memory was allocated from
1532 * @param list The freelist from which this bucket should be allocated
1533 * @return The new bucket, or NULL if allocation failed
1534 */
1536 apr_size_t length,
1537 apr_pool_t *pool,
1538 apr_bucket_alloc_t *list)
1539 __attribute__((nonnull(1,3,4)));
1540
1541/**
1542 * Make the bucket passed in a bucket refer to pool data
1543 * @param b The bucket to make into a pool bucket
1544 * @param buf The buffer to insert into the bucket
1545 * @param length The number of bytes referred to by this bucket
1546 * @param pool The pool the memory was allocated from
1547 * @return The new bucket, or NULL if allocation failed
1548 */
1550 apr_size_t length,
1551 apr_pool_t *pool)
1552 __attribute__((nonnull(1,2,4)));
1553
1554#if APR_HAS_MMAP
1555/**
1556 * Create a bucket referring to mmap()ed memory.
1557 * @param mm The mmap to insert into the bucket
1558 * @param start The offset of the first byte in the mmap
1559 * that this bucket refers to
1560 * @param length The number of bytes referred to by this bucket
1561 * @param list The freelist from which this bucket should be allocated
1562 * @return The new bucket, or NULL if allocation failed
1563 */
1565 apr_off_t start,
1566 apr_size_t length,
1567 apr_bucket_alloc_t *list)
1568 __attribute__((nonnull(1,4)));
1569
1570/**
1571 * Make the bucket passed in a bucket refer to an MMAP'ed file
1572 * @param b The bucket to make into a MMAP bucket
1573 * @param mm The mmap to insert into the bucket
1574 * @param start The offset of the first byte in the mmap
1575 * that this bucket refers to
1576 * @param length The number of bytes referred to by this bucket
1577 * @return The new bucket, or NULL if allocation failed
1578 */
1580 apr_off_t start,
1581 apr_size_t length)
1582 __attribute__((nonnull(1,2)));
1583#endif
1584
1585/**
1586 * Create a bucket referring to a socket.
1587 * @param thissock The socket to put in the bucket
1588 * @param list The freelist from which this bucket should be allocated
1589 * @return The new bucket, or NULL if allocation failed
1590 */
1592 apr_bucket_alloc_t *list)
1593 __attribute__((nonnull(1,2)));
1594/**
1595 * Make the bucket passed in a bucket refer to a socket
1596 * @param b The bucket to make into a SOCKET bucket
1597 * @param thissock The socket to put in the bucket
1598 * @return The new bucket, or NULL if allocation failed
1599 */
1601 apr_socket_t *thissock)
1602 __attribute__((nonnull(1,2)));
1603
1604/**
1605 * Create a bucket referring to a pipe.
1606 * @param thispipe The pipe to put in the bucket
1607 * @param list The freelist from which this bucket should be allocated
1608 * @return The new bucket, or NULL if allocation failed
1609 */
1611 apr_bucket_alloc_t *list)
1612 __attribute__((nonnull(1,2)));
1613
1614/**
1615 * Make the bucket passed in a bucket refer to a pipe
1616 * @param b The bucket to make into a PIPE bucket
1617 * @param thispipe The pipe to put in the bucket
1618 * @return The new bucket, or NULL if allocation failed
1619 */
1621 apr_file_t *thispipe)
1622 __attribute__((nonnull(1,2)));
1623
1624/**
1625 * Create a bucket referring to a file.
1626 * @param fd The file to put in the bucket
1627 * @param offset The offset where the data of interest begins in the file
1628 * @param len The amount of data in the file we are interested in
1629 * @param p The pool into which any needed structures should be created
1630 * while reading from this file bucket
1631 * @param list The freelist from which this bucket should be allocated
1632 * @return The new bucket, or NULL if allocation failed
1633 * @remark If the file is truncated such that the segment of the file
1634 * referenced by the bucket no longer exists, an attempt to read
1635 * from the bucket will fail with APR_EOF.
1636 * @remark apr_brigade_insert_file() should generally be used to
1637 * insert files into brigades, since that function can correctly
1638 * handle large file issues.
1639 */
1641 apr_off_t offset,
1642 apr_size_t len,
1643 apr_pool_t *p,
1644 apr_bucket_alloc_t *list)
1645 __attribute__((nonnull(1,4,5)));
1646
1647/**
1648 * Make the bucket passed in a bucket refer to a file
1649 * @param b The bucket to make into a FILE bucket
1650 * @param fd The file to put in the bucket
1651 * @param offset The offset where the data of interest begins in the file
1652 * @param len The amount of data in the file we are interested in
1653 * @param p The pool into which any needed structures should be created
1654 * while reading from this file bucket
1655 * @return The new bucket, or NULL if allocation failed
1656 */
1658 apr_off_t offset,
1659 apr_size_t len, apr_pool_t *p)
1660 __attribute__((nonnull(1,2,5)));
1661
1662/**
1663 * Enable or disable memory-mapping for a FILE bucket (default is enabled)
1664 * @param b The bucket
1665 * @param enabled Whether memory-mapping should be enabled
1666 * @return APR_SUCCESS normally, or an error code if the operation fails
1667 */
1669 int enabled)
1670 __attribute__((nonnull(1)));
1671
1672/**
1673 * Set the size of the read buffer allocated by a FILE bucket (default
1674 * is @a APR_BUCKET_BUFF_SIZE)
1675 * memory-mapping is disabled only)
1676 * @param b The bucket
1677 * @param size Size of the allocated buffers
1678 * @return APR_SUCCESS normally, or an error code if the operation fails
1679 * @remark Relevant/used only when memory-mapping is disabled (@see
1680 * apr_bucket_file_enable_mmap)
1681 */
1683 apr_size_t size);
1684
1685/** @} */
1686#ifdef __cplusplus
1687}
1688#endif
1689
1690#endif /* !APR_BUCKETS_H */
APR Platform Definitions.
APR Error Codes.
APR File I/O Handling.
APR Miscellaneous library routines.
APR MMAP routines.
APR Network library.
APR Rings.
apr_bucket * apr_bucket_eos_make(apr_bucket *b)
void apr_bucket_destroy_noop(void *data)
apr_status_t apr_bucket_simple_copy(apr_bucket *a, apr_bucket **b)
apr_bucket * apr_bucket_pool_make(apr_bucket *b, const char *buf, apr_size_t length, apr_pool_t *pool)
const apr_bucket_type_t apr_bucket_type_transient
apr_bucket * apr_bucket_socket_make(apr_bucket *b, apr_socket_t *thissock)
apr_status_t apr_brigade_putstrs(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx,...)
apr_bucket * apr_bucket_flush_make(apr_bucket *b)
apr_bucket * apr_bucket_socket_create(apr_socket_t *thissock, apr_bucket_alloc_t *list)
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_status_t apr_brigade_split_line(apr_bucket_brigade *bbOut, apr_bucket_brigade *bbIn, apr_read_type_e block, apr_off_t maxbytes)
apr_bucket * apr_bucket_pipe_create(apr_file_t *thispipe, apr_bucket_alloc_t *list)
apr_bucket * apr_bucket_heap_create(const char *buf, apr_size_t nbyte, void(*free_func)(void *data), apr_bucket_alloc_t *list)
const apr_bucket_type_t apr_bucket_type_heap
apr_bucket * apr_bucket_immortal_make(apr_bucket *b, const char *buf, apr_size_t nbyte)
apr_status_t apr_brigade_puts(apr_bucket_brigade *bb, apr_brigade_flush flush, void *ctx, const char *str)
apr_status_t apr_bucket_shared_copy(apr_bucket *a, apr_bucket **b)
apr_status_t apr_brigade_destroy(apr_bucket_brigade *b)
apr_status_t apr_brigade_flatten(apr_bucket_brigade *bb, char *c, apr_size_t *len)
apr_status_t apr_bucket_split_notimpl(apr_bucket *data, apr_size_t point)
const apr_bucket_type_t apr_bucket_type_pipe
apr_status_t apr_brigade_putc(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char c)
apr_status_t apr_brigade_vputstrs(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, va_list va)
const apr_bucket_type_t apr_bucket_type_immortal
apr_bucket_brigade * apr_brigade_split(apr_bucket_brigade *b, apr_bucket *e)
apr_bucket * apr_bucket_transient_make(apr_bucket *b, const char *buf, apr_size_t nbyte)
apr_bucket * apr_bucket_mmap_create(apr_mmap_t *mm, apr_off_t start, apr_size_t length, apr_bucket_alloc_t *list)
apr_status_t apr_brigade_printf(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt,...)
int apr_bucket_shared_destroy(void *data)
apr_bucket * apr_bucket_heap_make(apr_bucket *b, const char *buf, apr_size_t nbyte, void(*free_func)(void *data))
apr_status_t apr_brigade_partition(apr_bucket_brigade *b, apr_off_t point, apr_bucket **after_point)
apr_bucket * apr_bucket_flush_create(apr_bucket_alloc_t *list)
apr_status_t apr_brigade_split_boundary(apr_bucket_brigade *bbOut, apr_bucket_brigade *bbIn, apr_read_type_e block, const char *boundary, apr_size_t boundary_len, apr_off_t maxbytes)
const apr_bucket_type_t apr_bucket_type_file
apr_bucket * apr_bucket_pipe_make(apr_bucket *b, apr_file_t *thispipe)
apr_status_t apr_bucket_copy_notimpl(apr_bucket *e, apr_bucket **c)
apr_bucket * apr_bucket_shared_make(apr_bucket *b, void *data, apr_off_t start, apr_size_t length)
const apr_bucket_type_t apr_bucket_type_mmap
apr_status_t apr_brigade_length(apr_bucket_brigade *bb, int read_all, apr_off_t *length)
apr_status_t apr_brigade_write(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *str, apr_size_t nbyte)
apr_read_type_e
Definition apr_buckets.h:62
apr_bucket_alloc_t * apr_bucket_alloc_create(apr_pool_t *p)
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_file_make(apr_bucket *b, apr_file_t *fd, apr_off_t offset, apr_size_t len, apr_pool_t *p)
apr_bucket_brigade * apr_brigade_create(apr_pool_t *p, apr_bucket_alloc_t *list)
const apr_bucket_type_t apr_bucket_type_eos
apr_status_t apr_bucket_shared_split(apr_bucket *b, apr_size_t point)
const apr_bucket_type_t apr_bucket_type_pool
apr_bucket_brigade * apr_brigade_split_ex(apr_bucket_brigade *b, apr_bucket *e, apr_bucket_brigade *a)
void * apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list)
apr_status_t apr_brigade_to_iovec(apr_bucket_brigade *b, struct iovec *vec, int *nvec)
void apr_bucket_free(void *block)
struct apr_bucket_alloc_t apr_bucket_alloc_t
Definition apr_buckets.h:128
apr_status_t apr_brigade_vprintf(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt, va_list va)
apr_status_t apr_bucket_simple_split(apr_bucket *b, apr_size_t point)
apr_status_t apr_brigade_pflatten(apr_bucket_brigade *bb, char **c, apr_size_t *len, apr_pool_t *pool)
const apr_bucket_type_t apr_bucket_type_socket
apr_status_t apr_bucket_file_set_buf_size(apr_bucket *b, apr_size_t size)
apr_size_t apr_bucket_alloc_aligned_floor(apr_bucket_alloc_t *list, apr_size_t size)
apr_status_t apr_bucket_file_enable_mmap(apr_bucket *b, int enabled)
apr_bucket * apr_bucket_eos_create(apr_bucket_alloc_t *list)
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_pool_create(const char *buf, apr_size_t length, apr_pool_t *pool, apr_bucket_alloc_t *list)
apr_bucket * apr_bucket_immortal_create(const char *buf, apr_size_t nbyte, apr_bucket_alloc_t *list)
apr_status_t apr_bucket_setaside_notimpl(apr_bucket *data, apr_pool_t *pool)
apr_bucket_alloc_t * apr_bucket_alloc_create_ex(apr_allocator_t *allocator)
apr_status_t apr_bucket_setaside_noop(apr_bucket *data, apr_pool_t *pool)
const apr_bucket_type_t apr_bucket_type_flush
void apr_bucket_alloc_destroy(apr_bucket_alloc_t *list)
apr_bucket * apr_bucket_transient_create(const char *buf, apr_size_t nbyte, apr_bucket_alloc_t *list)
apr_status_t(* apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx)
Definition apr_buckets.h:287
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_cleanup(void *data)
@ APR_BLOCK_READ
Definition apr_buckets.h:63
@ APR_NONBLOCK_READ
Definition apr_buckets.h:64
struct apr_allocator_t apr_allocator_t
Definition apr_allocator.h:41
int apr_status_t
Definition apr_errno.h:44
struct apr_file_t apr_file_t
Definition apr_file_io.h:195
struct apr_socket_t apr_socket_t
Definition apr_network_io.h:219
#define APR_DECLARE_DATA
Definition apr.h:552
#define APR_DECLARE_NONSTD(type)
Definition apr.h:536
#define APR_DECLARE(type)
Definition apr.h:523
struct apr_pool_t apr_pool_t
Definition apr_pools.h:60
Definition apr_buckets.h:263
APR_RING_HEAD(apr_bucket_list, apr_bucket) list
apr_pool_t * p
Definition apr_buckets.h:269
apr_bucket_alloc_t * bucket_alloc
Definition apr_buckets.h:280
Definition apr_buckets.h:620
apr_pool_t * readpool
Definition apr_buckets.h:632
int can_mmap
Definition apr_buckets.h:626
apr_size_t read_size
Definition apr_buckets.h:634
apr_file_t * fd
Definition apr_buckets.h:629
apr_bucket_refcount refcount
Definition apr_buckets.h:622
Definition apr_buckets.h:551
apr_bucket_refcount refcount
Definition apr_buckets.h:553
char * base
Definition apr_buckets.h:557
void(* free_func)(void *data)
Definition apr_buckets.h:561
apr_size_t alloc_len
Definition apr_buckets.h:559
Definition apr_buckets.h:607
apr_mmap_t * mmap
Definition apr_buckets.h:611
apr_bucket_refcount refcount
Definition apr_buckets.h:609
Definition apr_buckets.h:569
apr_bucket_heap heap
Definition apr_buckets.h:581
apr_bucket_alloc_t * list
Definition apr_buckets.h:598
const char * base
Definition apr_buckets.h:587
apr_pool_t * pool
Definition apr_buckets.h:594
Definition apr_buckets.h:539
int refcount
Definition apr_buckets.h:541
Definition apr_buckets.h:136
@ APR_BUCKET_DATA
Definition apr_buckets.h:158
@ APR_BUCKET_METADATA
Definition apr_buckets.h:160
apr_status_t(* split)(apr_bucket *e, apr_size_t point)
Definition apr_buckets.h:208
apr_status_t(* copy)(apr_bucket *e, apr_bucket **c)
Definition apr_buckets.h:216
apr_status_t(* read)(apr_bucket *b, const char **str, apr_size_t *len, apr_read_type_e block)
Definition apr_buckets.h:181
enum apr_bucket_type_t::@0 is_metadata
const char * name
Definition apr_buckets.h:140
int num_func
Definition apr_buckets.h:145
apr_status_t(* setaside)(apr_bucket *e, apr_pool_t *pool)
Definition apr_buckets.h:197
void(* destroy)(void *data)
Definition apr_buckets.h:169
Definition apr_buckets.h:229
apr_size_t length
Definition apr_buckets.h:239
void(* free)(void *e)
Definition apr_buckets.h:257
apr_off_t start
Definition apr_buckets.h:247
apr_bucket_alloc_t * list
Definition apr_buckets.h:259
void * data
Definition apr_buckets.h:249
APR_RING_ENTRY(apr_bucket) link
const apr_bucket_type_t * type
Definition apr_buckets.h:233
Definition apr_mmap.h:62
Definition apr_buckets.h:643
apr_bucket_heap heap
Definition apr_buckets.h:645
apr_bucket_mmap mmap
Definition apr_buckets.h:648
apr_bucket b
Definition apr_buckets.h:644
apr_bucket_file file
Definition apr_buckets.h:650
apr_bucket_pool pool
Definition apr_buckets.h:646