Apache Portable Runtime
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
44 extern "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 */
62 typedef 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 */
126 typedef struct apr_bucket apr_bucket;
127 /** @see apr_bucket_alloc_t */
129 
130 /** @see apr_bucket_type_t */
131 typedef struct apr_bucket_type_t 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  */
145  int num_func;
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  */
229 struct apr_bucket {
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 */
541  int refcount;
542 };
543 
544 /* ***** Reference-counted bucket types ***** */
545 
546 /** @see apr_bucket_heap */
547 typedef struct apr_bucket_heap 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 */
565 typedef struct apr_bucket_pool 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 */
603 typedef struct apr_bucket_mmap 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 */
616 typedef struct apr_bucket_file 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 */
626  int can_mmap;
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  */
1050 APR_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_pool_make(apr_bucket *b, const char *buf, apr_size_t length, apr_pool_t *pool)
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_create(const char *buf, apr_size_t length, apr_pool_t *pool, apr_bucket_alloc_t *list)
const apr_bucket_type_t apr_bucket_type_transient
apr_status_t apr_brigade_putstrs(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx,...)
apr_bucket_alloc_t * apr_bucket_alloc_create_ex(apr_allocator_t *allocator)
apr_status_t apr_brigade_split_line(apr_bucket_brigade *bbOut, apr_bucket_brigade *bbIn, apr_read_type_e block, apr_off_t maxbytes)
const apr_bucket_type_t apr_bucket_type_heap
apr_status_t apr_brigade_puts(apr_bucket_brigade *bb, apr_brigade_flush flush, void *ctx, const char *str)
apr_bucket_alloc_t * apr_bucket_alloc_create(apr_pool_t *p)
apr_status_t apr_bucket_shared_copy(apr_bucket *a, apr_bucket **b)
apr_status_t apr_brigade_destroy(apr_bucket_brigade *b)
apr_bucket * apr_bucket_socket_make(apr_bucket *b, apr_socket_t *thissock)
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_bucket * apr_bucket_immortal_make(apr_bucket *b, const char *buf, apr_size_t nbyte)
apr_status_t apr_brigade_putc(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char c)
apr_bucket_brigade * apr_brigade_split_ex(apr_bucket_brigade *b, apr_bucket *e, apr_bucket_brigade *a)
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_status_t apr_brigade_printf(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt,...)
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)
int apr_bucket_shared_destroy(void *data)
apr_bucket * apr_bucket_flush_create(apr_bucket_alloc_t *list)
apr_status_t apr_brigade_partition(apr_bucket_brigade *b, apr_off_t point, apr_bucket **after_point)
apr_bucket * apr_bucket_transient_create(const char *buf, apr_size_t nbyte, apr_bucket_alloc_t *list)
apr_bucket * apr_bucket_shared_make(apr_bucket *b, void *data, apr_off_t start, apr_size_t length)
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_status_t apr_bucket_copy_notimpl(apr_bucket *e, apr_bucket **c)
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_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_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 * apr_brigade_insert_file(apr_bucket_brigade *bb, apr_file_t *f, apr_off_t start, apr_off_t len, apr_pool_t *p)
apr_bucket * apr_bucket_transient_make(apr_bucket *b, const char *buf, apr_size_t nbyte)
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_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_bucket * apr_bucket_eos_create(apr_bucket_alloc_t *list)
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_mmap_make(apr_bucket *b, apr_mmap_t *mm, apr_off_t start, apr_size_t length)
apr_bucket * apr_bucket_pipe_create(apr_file_t *thispipe, apr_bucket_alloc_t *list)
apr_bucket_brigade * apr_brigade_split(apr_bucket_brigade *b, apr_bucket *e)
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 * apr_bucket_socket_create(apr_socket_t *thissock, apr_bucket_alloc_t *list)
apr_bucket * apr_bucket_immortal_create(const char *buf, apr_size_t nbyte, 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)
apr_status_t apr_bucket_setaside_notimpl(apr_bucket *data, apr_pool_t *pool)
void * apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list)
apr_status_t apr_bucket_setaside_noop(apr_bucket *data, apr_pool_t *pool)
apr_bucket * apr_bucket_pipe_make(apr_bucket *b, apr_file_t *thispipe)
apr_bucket_brigade * apr_brigade_create(apr_pool_t *p, apr_bucket_alloc_t *list)
const apr_bucket_type_t apr_bucket_type_flush
apr_bucket * apr_bucket_mmap_create(apr_mmap_t *mm, apr_off_t start, apr_size_t length, apr_bucket_alloc_t *list)
apr_bucket * apr_bucket_flush_make(apr_bucket *b)
void apr_bucket_alloc_destroy(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:545
#define APR_DECLARE_NONSTD(type)
Definition: apr.h:529
#define APR_DECLARE(type)
Definition: apr.h:516
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