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