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. The brigade @a a will be
691
* cleared if it is not empty.
692
* @return The brigade supplied in @a a or a new one if @a a was NULL.
693
* @warning Note that this function allocates a new brigade if @a a is
694
* NULL so memory consumption should be carefully considered.
695
*/
696
APU_DECLARE(
apr_bucket_brigade
*)
apr_brigade_split_ex
(
apr_bucket_brigade
*b,
697
apr_bucket
*e,
698
apr_bucket_brigade
*a);
699
700
/**
701
* Create a new bucket brigade and move the buckets from the tail end
702
* of an existing brigade into the new brigade. Buckets from
703
* @a e to the last bucket (inclusively) of brigade @a b
704
* are moved from @a b to the returned brigade.
705
* @param b The brigade to split
706
* @param e The first bucket to move
707
* @return The new brigade
708
* @warning Note that this function always allocates a new brigade
709
* so memory consumption should be carefully considered.
710
*/
711
APU_DECLARE(
apr_bucket_brigade
*)
apr_brigade_split
(
apr_bucket_brigade
*b,
712
apr_bucket
*e);
713
714
/**
715
* Partition a bucket brigade at a given offset (in bytes from the start of
716
* the brigade). This is useful whenever a filter wants to use known ranges
717
* of bytes from the brigade; the ranges can even overlap.
718
* @param b The brigade to partition
719
* @param point The offset at which to partition the brigade
720
* @param after_point Returns a pointer to the first bucket after the partition
721
* @return APR_SUCCESS on success, APR_INCOMPLETE if the contents of the
722
* brigade were shorter than @a point, or an error code.
723
* @remark if APR_INCOMPLETE is returned, @a after_point will be set to
724
* the brigade sentinel.
725
*/
726
APU_DECLARE(
apr_status_t
)
apr_brigade_partition
(
apr_bucket_brigade
*b,
727
apr_off_t point,
728
apr_bucket
**after_point);
729
730
/**
731
* Return the total length of the brigade.
732
* @param bb The brigade to compute the length of
733
* @param read_all Read unknown-length buckets to force a size
734
* @param length Returns the length of the brigade (up to the end, or up
735
* to a bucket read error), or -1 if the brigade has buckets
736
* of indeterminate length and read_all is 0.
737
*/
738
APU_DECLARE(
apr_status_t
)
apr_brigade_length
(
apr_bucket_brigade
*bb,
739
int
read_all,
740
apr_off_t *length);
741
742
/**
743
* Take a bucket brigade and store the data in a flat char*
744
* @param bb The bucket brigade to create the char* from
745
* @param c The char* to write into
746
* @param len The maximum length of the char array. On return, it is the
747
* actual length of the char array.
748
*/
749
APU_DECLARE(
apr_status_t
)
apr_brigade_flatten
(
apr_bucket_brigade
*bb,
750
char
*c,
751
apr_size_t *len);
752
753
/**
754
* Creates a pool-allocated string representing a flat bucket brigade
755
* @param bb The bucket brigade to create the char array from
756
* @param c On return, the allocated char array
757
* @param len On return, the length of the char array.
758
* @param pool The pool to allocate the string from.
759
*/
760
APU_DECLARE(
apr_status_t
)
apr_brigade_pflatten
(
apr_bucket_brigade
*bb,
761
char
**c,
762
apr_size_t *len,
763
apr_pool_t
*pool);
764
765
/**
766
* Split a brigade to represent one LF line.
767
* @param bbOut The bucket brigade that will have the LF line appended to.
768
* @param bbIn The input bucket brigade to search for a LF-line.
769
* @param block The blocking mode to be used to split the line.
770
* @param maxbytes The maximum bytes to read. If this many bytes are seen
771
* without a LF, the brigade will contain a partial line.
772
*/
773
APU_DECLARE(
apr_status_t
)
apr_brigade_split_line
(
apr_bucket_brigade
*bbOut,
774
apr_bucket_brigade
*bbIn,
775
apr_read_type_e
block,
776
apr_off_t maxbytes);
777
778
/**
779
* Create an iovec of the elements in a bucket_brigade... return number
780
* of elements used. This is useful for writing to a file or to the
781
* network efficiently.
782
* @param b The bucket brigade to create the iovec from
783
* @param vec The iovec to create
784
* @param nvec The number of elements in the iovec. On return, it is the
785
* number of iovec elements actually filled out.
786
*/
787
APU_DECLARE(
apr_status_t
)
apr_brigade_to_iovec
(
apr_bucket_brigade
*b,
788
struct iovec *vec,
int
*nvec);
789
790
/**
791
* This function writes a list of strings into a bucket brigade.
792
* @param b The bucket brigade to add to
793
* @param flush The flush function to use if the brigade is full
794
* @param ctx The structure to pass to the flush function
795
* @param va A list of strings to add
796
* @return APR_SUCCESS or error code.
797
*/
798
APU_DECLARE(
apr_status_t
)
apr_brigade_vputstrs
(
apr_bucket_brigade
*b,
799
apr_brigade_flush
flush,
800
void
*ctx,
801
va_list va);
802
803
/**
804
* This function writes a string into a bucket brigade.
805
*
806
* The apr_brigade_write function attempts to be efficient with the
807
* handling of heap buckets. Regardless of the amount of data stored
808
* inside a heap bucket, heap buckets are a fixed size to promote their
809
* reuse.
810
*
811
* If an attempt is made to write a string to a brigade that already
812
* ends with a heap bucket, this function will attempt to pack the
813
* string into the remaining space in the previous heap bucket, before
814
* allocating a new heap bucket.
815
*
816
* This function always returns APR_SUCCESS, unless a flush function is
817
* passed, in which case the return value of the flush function will be
818
* returned if used.
819
* @param b The bucket brigade to add to
820
* @param flush The flush function to use if the brigade is full
821
* @param ctx The structure to pass to the flush function
822
* @param str The string to add
823
* @param nbyte The number of bytes to write
824
* @return APR_SUCCESS or error code
825
*/
826
APU_DECLARE(
apr_status_t
)
apr_brigade_write
(
apr_bucket_brigade
*b,
827
apr_brigade_flush
flush,
void
*ctx,
828
const
char
*str, apr_size_t nbyte);
829
830
/**
831
* This function writes multiple strings into a bucket brigade.
832
* @param b The bucket brigade to add to
833
* @param flush The flush function to use if the brigade is full
834
* @param ctx The structure to pass to the flush function
835
* @param vec The strings to add (address plus length for each)
836
* @param nvec The number of entries in iovec
837
* @return APR_SUCCESS or error code
838
*/
839
APU_DECLARE(
apr_status_t
)
apr_brigade_writev
(
apr_bucket_brigade
*b,
840
apr_brigade_flush
flush,
841
void
*ctx,
842
const struct iovec *vec,
843
apr_size_t nvec);
844
845
/**
846
* This function writes a string into a bucket brigade.
847
* @param bb The bucket brigade to add to
848
* @param flush The flush function to use if the brigade is full
849
* @param ctx The structure to pass to the flush function
850
* @param str The string to add
851
* @return APR_SUCCESS or error code
852
*/
853
APU_DECLARE(
apr_status_t
)
apr_brigade_puts
(
apr_bucket_brigade
*bb,
854
apr_brigade_flush
flush,
void
*ctx,
855
const
char
*str);
856
857
/**
858
* This function writes a character into a bucket brigade.
859
* @param b The bucket brigade to add to
860
* @param flush The flush function to use if the brigade is full
861
* @param ctx The structure to pass to the flush function
862
* @param c The character to add
863
* @return APR_SUCCESS or error code
864
*/
865
APU_DECLARE(
apr_status_t
)
apr_brigade_putc
(
apr_bucket_brigade
*b,
866
apr_brigade_flush
flush,
void
*ctx,
867
const
char
c);
868
869
/**
870
* This function writes an unspecified number of strings into a bucket brigade.
871
* @param b The bucket brigade to add to
872
* @param flush The flush function to use if the brigade is full
873
* @param ctx The structure to pass to the flush function
874
* @param ... The strings to add
875
* @return APR_SUCCESS or error code
876
*/
877
APU_DECLARE_NONSTD(
apr_status_t
)
apr_brigade_putstrs
(
apr_bucket_brigade
*b,
878
apr_brigade_flush
flush,
879
void
*ctx, ...);
880
881
/**
882
* Evaluate a printf and put the resulting string at the end
883
* of the bucket brigade.
884
* @param b The brigade to write to
885
* @param flush The flush function to use if the brigade is full
886
* @param ctx The structure to pass to the flush function
887
* @param fmt The format of the string to write
888
* @param ... The arguments to fill out the format
889
* @return APR_SUCCESS or error code
890
*/
891
APU_DECLARE_NONSTD(
apr_status_t
)
apr_brigade_printf
(
apr_bucket_brigade
*b,
892
apr_brigade_flush
flush,
893
void
*ctx,
894
const
char
*fmt, ...)
895
__attribute__((format(printf,4,5)));
896
897
/**
898
* Evaluate a printf and put the resulting string at the end
899
* of the bucket brigade.
900
* @param b The brigade to write to
901
* @param flush The flush function to use if the brigade is full
902
* @param ctx The structure to pass to the flush function
903
* @param fmt The format of the string to write
904
* @param va The arguments to fill out the format
905
* @return APR_SUCCESS or error code
906
*/
907
APU_DECLARE(
apr_status_t
)
apr_brigade_vprintf
(
apr_bucket_brigade
*b,
908
apr_brigade_flush
flush,
909
void
*ctx,
910
const
char
*fmt, va_list va);
911
912
/**
913
* Utility function to insert a file (or a segment of a file) onto the
914
* end of the brigade. The file is split into multiple buckets if it
915
* is larger than the maximum size which can be represented by a
916
* single bucket.
917
* @param bb the brigade to insert into
918
* @param f the file to insert
919
* @param start the offset of the start of the segment
920
* @param len the length of the segment of the file to insert
921
* @param p pool from which file buckets are allocated
922
* @return the last bucket inserted
923
*/
924
APU_DECLARE(
apr_bucket
*)
apr_brigade_insert_file
(
apr_bucket_brigade
*bb,
925
apr_file_t
*f,
926
apr_off_t start,
927
apr_off_t len,
928
apr_pool_t
*p);
929
930
931
932
/* ***** Bucket freelist functions ***** */
933
/**
934
* Create a bucket allocator.
935
* @param p This pool's underlying apr_allocator_t is used to allocate memory
936
* for the bucket allocator. When the pool is destroyed, the bucket
937
* allocator's cleanup routine will free all memory that has been
938
* allocated from it.
939
* @remark The reason the allocator gets its memory from the pool's
940
* apr_allocator_t rather than from the pool itself is because
941
* the bucket allocator will free large memory blocks back to the
942
* allocator when it's done with them, thereby preventing memory
943
* footprint growth that would occur if we allocated from the pool.
944
* @warning The allocator must never be used by more than one thread at a time.
945
*/
946
APU_DECLARE_NONSTD(
apr_bucket_alloc_t
*)
apr_bucket_alloc_create
(
apr_pool_t
*p);
947
948
/**
949
* Create a bucket allocator.
950
* @param allocator This apr_allocator_t is used to allocate both the bucket
951
* allocator and all memory handed out by the bucket allocator. The
952
* caller is responsible for destroying the bucket allocator and the
953
* apr_allocator_t -- no automatic cleanups will happen.
954
* @warning The allocator must never be used by more than one thread at a time.
955
*/
956
APU_DECLARE_NONSTD(
apr_bucket_alloc_t
*)
apr_bucket_alloc_create_ex
(
apr_allocator_t
*allocator);
957
958
/**
959
* Destroy a bucket allocator.
960
* @param list The allocator to be destroyed
961
*/
962
APU_DECLARE_NONSTD(
void
)
apr_bucket_alloc_destroy
(
apr_bucket_alloc_t
*list);
963
964
/**
965
* Allocate memory for use by the buckets.
966
* @param size The amount to allocate.
967
* @param list The allocator from which to allocate the memory.
968
*/
969
APU_DECLARE_NONSTD(
void
*)
apr_bucket_alloc
(apr_size_t size,
apr_bucket_alloc_t
*list);
970
971
/**
972
* Free memory previously allocated with apr_bucket_alloc().
973
* @param block The block of memory to be freed.
974
*/
975
APU_DECLARE_NONSTD(
void
)
apr_bucket_free
(
void
*block);
976
977
978
/* ***** Bucket Functions ***** */
979
/**
980
* Free the resources used by a bucket. If multiple buckets refer to
981
* the same resource it is freed when the last one goes away.
982
* @see apr_bucket_delete()
983
* @param e The bucket to destroy
984
*/
985
#define apr_bucket_destroy(e) do { \
986
(e)->type->destroy((e)->data); \
987
(e)->free(e); \
988
} while (0)
989
990
/**
991
* Delete a bucket by removing it from its brigade (if any) and then
992
* destroying it.
993
* @remark This mainly acts as an aid in avoiding code verbosity. It is
994
* the preferred exact equivalent to:
995
* <pre>
996
* APR_BUCKET_REMOVE(e);
997
* apr_bucket_destroy(e);
998
* </pre>
999
* @param e The bucket to delete
1000
*/
1001
#define apr_bucket_delete(e) do { \
1002
APR_BUCKET_REMOVE(e); \
1003
apr_bucket_destroy(e); \
1004
} while (0)
1005
1006
/**
1007
* Read some data from the bucket.
1008
*
1009
* The apr_bucket_read function returns a convenient amount of data
1010
* from the bucket provided, writing the address and length of the
1011
* data to the pointers provided by the caller. The function tries
1012
* as hard as possible to avoid a memory copy.
1013
*
1014
* Buckets are expected to be a member of a brigade at the time they
1015
* are read.
1016
*
1017
* In typical application code, buckets are read in a loop, and after
1018
* each bucket is read and processed, it is moved or deleted from the
1019
* brigade and the next bucket read.
1020
*
1021
* The definition of "convenient" depends on the type of bucket that
1022
* is being read, and is decided by APR. In the case of memory based
1023
* buckets such as heap and immortal buckets, a pointer will be
1024
* returned to the location of the buffer containing the complete
1025
* contents of the bucket.
1026
*
1027
* Some buckets, such as the socket bucket, might have no concept
1028
* of length. If an attempt is made to read such a bucket, the
1029
* apr_bucket_read function will read a convenient amount of data
1030
* from the socket. The socket bucket is magically morphed into a
1031
* heap bucket containing the just-read data, and a new socket bucket
1032
* is inserted just after this heap bucket.
1033
*
1034
* To understand why apr_bucket_read might do this, consider the loop
1035
* described above to read and process buckets. The current bucket
1036
* is magically morphed into a heap bucket and returned to the caller.
1037
* The caller processes the data, and deletes the heap bucket, moving
1038
* onto the next bucket, the new socket bucket. This process repeats,
1039
* giving the illusion of a bucket brigade that contains potentially
1040
* infinite amounts of data. It is up to the caller to decide at what
1041
* point to stop reading buckets.
1042
*
1043
* Some buckets, such as the file bucket, might have a fixed size,
1044
* but be significantly larger than is practical to store in RAM in
1045
* one go. As with the socket bucket, if an attempt is made to read
1046
* from a file bucket, the file bucket is magically morphed into a
1047
* heap bucket containing a convenient amount of data read from the
1048
* current offset in the file. During the read, the offset will be
1049
* moved forward on the file, and a new file bucket will be inserted
1050
* directly after the current bucket representing the remainder of the
1051
* file. If the heap bucket was large enough to store the whole
1052
* remainder of the file, no more file buckets are inserted, and the
1053
* file bucket will disappear completely.
1054
*
1055
* The pattern for reading buckets described above does create the
1056
* illusion that the code is willing to swallow buckets that might be
1057
* too large for the system to handle in one go. This however is just
1058
* an illusion: APR will always ensure that large (file) or infinite
1059
* (socket) buckets are broken into convenient bite sized heap buckets
1060
* before data is returned to the caller.
1061
*
1062
* There is a potential gotcha to watch for: if buckets are read in a
1063
* loop, and aren't deleted after being processed, the potentially large
1064
* bucket will slowly be converted into RAM resident heap buckets. If
1065
* the file is larger than available RAM, an out of memory condition
1066
* could be caused if the application is not careful to manage this.
1067
*
1068
* @param e The bucket to read from
1069
* @param str The location to store a pointer to the data in
1070
* @param len The location to store the amount of data read
1071
* @param block Whether the read function blocks
1072
*/
1073
#define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)
1074
1075
/**
1076
* Setaside data so that stack data is not destroyed on returning from
1077
* the function
1078
* @param e The bucket to setaside
1079
* @param p The pool to setaside into
1080
*/
1081
#define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)
1082
1083
/**
1084
* Split one bucket in two at the point provided.
1085
*
1086
* Once split, the original bucket becomes the first of the two new buckets.
1087
*
1088
* (It is assumed that the bucket is a member of a brigade when this
1089
* function is called).
1090
* @param e The bucket to split
1091
* @param point The offset to split the bucket at
1092
*/
1093
#define apr_bucket_split(e,point) (e)->type->split(e, point)
1094
1095
/**
1096
* Copy a bucket.
1097
* @param e The bucket to copy
1098
* @param c Returns a pointer to the new bucket
1099
*/
1100
#define apr_bucket_copy(e,c) (e)->type->copy(e, c)
1101
1102
/* Bucket type handling */
1103
1104
/**
1105
* This function simply returns APR_SUCCESS to denote that the bucket does
1106
* not require anything to happen for its setaside() function. This is
1107
* appropriate for buckets that have "immortal" data -- the data will live
1108
* at least as long as the bucket.
1109
* @param data The bucket to setaside
1110
* @param pool The pool defining the desired lifetime of the bucket data
1111
* @return APR_SUCCESS
1112
*/
1113
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_setaside_noop
(
apr_bucket
*data,
1114
apr_pool_t
*pool);
1115
1116
/**
1117
* A place holder function that signifies that the setaside function was not
1118
* implemented for this bucket
1119
* @param data The bucket to setaside
1120
* @param pool The pool defining the desired lifetime of the bucket data
1121
* @return APR_ENOTIMPL
1122
*/
1123
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_setaside_notimpl
(
apr_bucket
*data,
1124
apr_pool_t
*pool);
1125
1126
/**
1127
* A place holder function that signifies that the split function was not
1128
* implemented for this bucket
1129
* @param data The bucket to split
1130
* @param point The location to split the bucket
1131
* @return APR_ENOTIMPL
1132
*/
1133
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_split_notimpl
(
apr_bucket
*data,
1134
apr_size_t point);
1135
1136
/**
1137
* A place holder function that signifies that the copy function was not
1138
* implemented for this bucket
1139
* @param e The bucket to copy
1140
* @param c Returns a pointer to the new bucket
1141
* @return APR_ENOTIMPL
1142
*/
1143
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_copy_notimpl
(
apr_bucket
*e,
1144
apr_bucket
**c);
1145
1146
/**
1147
* A place holder function that signifies that this bucket does not need
1148
* to do anything special to be destroyed. That's only the case for buckets
1149
* that either have no data (metadata buckets) or buckets whose data pointer
1150
* points to something that's not a bucket-type-specific structure, as with
1151
* simple buckets where data points to a string and pipe buckets where data
1152
* points directly to the apr_file_t.
1153
* @param data The bucket data to destroy
1154
*/
1155
APU_DECLARE_NONSTD(
void
)
apr_bucket_destroy_noop
(
void
*data);
1156
1157
/**
1158
* There is no apr_bucket_destroy_notimpl, because destruction is required
1159
* to be implemented (it could be a noop, but only if that makes sense for
1160
* the bucket type)
1161
*/
1162
1163
/* There is no apr_bucket_read_notimpl, because it is a required function
1164
*/
1165
1166
1167
/* All of the bucket types implemented by the core */
1168
/**
1169
* The flush bucket type. This signifies that all data should be flushed to
1170
* the next filter. The flush bucket should be sent with the other buckets.
1171
*/
1172
APU_DECLARE_DATA extern const
apr_bucket_type_t
apr_bucket_type_flush
;
1173
/**
1174
* The EOS bucket type. This signifies that there will be no more data, ever.
1175
* All filters MUST send all data to the next filter when they receive a
1176
* bucket of this type
1177
*/
1178
APU_DECLARE_DATA extern const
apr_bucket_type_t
apr_bucket_type_eos
;
1179
/**
1180
* The FILE bucket type. This bucket represents a file on disk
1181
*/
1182
APU_DECLARE_DATA extern const
apr_bucket_type_t
apr_bucket_type_file
;
1183
/**
1184
* The HEAP bucket type. This bucket represents a data allocated from the
1185
* heap.
1186
*/
1187
APU_DECLARE_DATA extern const
apr_bucket_type_t
apr_bucket_type_heap
;
1188
#if APR_HAS_MMAP
1189
/**
1190
* The MMAP bucket type. This bucket represents an MMAP'ed file
1191
*/
1192
APU_DECLARE_DATA
extern
const
apr_bucket_type_t
apr_bucket_type_mmap
;
1193
#endif
1194
/**
1195
* The POOL bucket type. This bucket represents a data that was allocated
1196
* from a pool. IF this bucket is still available when the pool is cleared,
1197
* the data is copied on to the heap.
1198
*/
1199
APU_DECLARE_DATA
extern
const
apr_bucket_type_t
apr_bucket_type_pool
;
1200
/**
1201
* The PIPE bucket type. This bucket represents a pipe to another program.
1202
*/
1203
APU_DECLARE_DATA
extern
const
apr_bucket_type_t
apr_bucket_type_pipe
;
1204
/**
1205
* The IMMORTAL bucket type. This bucket represents a segment of data that
1206
* the creator is willing to take responsibility for. The core will do
1207
* nothing with the data in an immortal bucket
1208
*/
1209
APU_DECLARE_DATA
extern
const
apr_bucket_type_t
apr_bucket_type_immortal
;
1210
/**
1211
* The TRANSIENT bucket type. This bucket represents a data allocated off
1212
* the stack. When the setaside function is called, this data is copied on
1213
* to the heap
1214
*/
1215
APU_DECLARE_DATA
extern
const
apr_bucket_type_t
apr_bucket_type_transient
;
1216
/**
1217
* The SOCKET bucket type. This bucket represents a socket to another machine
1218
*/
1219
APU_DECLARE_DATA
extern
const
apr_bucket_type_t
apr_bucket_type_socket
;
1220
1221
1222
/* ***** Simple buckets ***** */
1223
1224
/**
1225
* Split a simple bucket into two at the given point. Most non-reference
1226
* counting buckets that allow multiple references to the same block of
1227
* data (eg transient and immortal) will use this as their split function
1228
* without any additional type-specific handling.
1229
* @param b The bucket to be split
1230
* @param point The offset of the first byte in the new bucket
1231
* @return APR_EINVAL if the point is not within the bucket;
1232
* APR_ENOMEM if allocation failed;
1233
* or APR_SUCCESS
1234
*/
1235
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_simple_split
(
apr_bucket
*b,
1236
apr_size_t point);
1237
1238
/**
1239
* Copy a simple bucket. Most non-reference-counting buckets that allow
1240
* multiple references to the same block of data (eg transient and immortal)
1241
* will use this as their copy function without any additional type-specific
1242
* handling.
1243
* @param a The bucket to copy
1244
* @param b Returns a pointer to the new bucket
1245
* @return APR_ENOMEM if allocation failed;
1246
* or APR_SUCCESS
1247
*/
1248
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_simple_copy
(
apr_bucket
*a,
1249
apr_bucket
**b);
1250
1251
1252
/* ***** Shared, reference-counted buckets ***** */
1253
1254
/**
1255
* Initialize a bucket containing reference-counted data that may be
1256
* shared. The caller must allocate the bucket if necessary and
1257
* initialize its type-dependent fields, and allocate and initialize
1258
* its own private data structure. This function should only be called
1259
* by type-specific bucket creation functions.
1260
* @param b The bucket to initialize
1261
* @param data A pointer to the private data structure
1262
* with the reference count at the start
1263
* @param start The start of the data in the bucket
1264
* relative to the private base pointer
1265
* @param length The length of the data in the bucket
1266
* @return The new bucket, or NULL if allocation failed
1267
*/
1268
APU_DECLARE(
apr_bucket
*)
apr_bucket_shared_make
(
apr_bucket
*b,
void
*data,
1269
apr_off_t start,
1270
apr_size_t length);
1271
1272
/**
1273
* Decrement the refcount of the data in the bucket. This function
1274
* should only be called by type-specific bucket destruction functions.
1275
* @param data The private data pointer from the bucket to be destroyed
1276
* @return TRUE or FALSE; TRUE if the reference count is now
1277
* zero, indicating that the shared resource itself can
1278
* be destroyed by the caller.
1279
*/
1280
APU_DECLARE(
int
)
apr_bucket_shared_destroy
(
void
*data);
1281
1282
/**
1283
* Split a bucket into two at the given point, and adjust the refcount
1284
* to the underlying data. Most reference-counting bucket types will
1285
* be able to use this function as their split function without any
1286
* additional type-specific handling.
1287
* @param b The bucket to be split
1288
* @param point The offset of the first byte in the new bucket
1289
* @return APR_EINVAL if the point is not within the bucket;
1290
* APR_ENOMEM if allocation failed;
1291
* or APR_SUCCESS
1292
*/
1293
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_shared_split
(
apr_bucket
*b,
1294
apr_size_t point);
1295
1296
/**
1297
* Copy a refcounted bucket, incrementing the reference count. Most
1298
* reference-counting bucket types will be able to use this function
1299
* as their copy function without any additional type-specific handling.
1300
* @param a The bucket to copy
1301
* @param b Returns a pointer to the new bucket
1302
* @return APR_ENOMEM if allocation failed;
1303
or APR_SUCCESS
1304
*/
1305
APU_DECLARE_NONSTD(
apr_status_t
)
apr_bucket_shared_copy
(
apr_bucket
*a,
1306
apr_bucket
**b);
1307
1308
1309
/* ***** Functions to Create Buckets of varying types ***** */
1310
/*
1311
* Each bucket type foo has two initialization functions:
1312
* apr_bucket_foo_make which sets up some already-allocated memory as a
1313
* bucket of type foo; and apr_bucket_foo_create which allocates memory
1314
* for the bucket, calls apr_bucket_make_foo, and initializes the
1315
* bucket's list pointers. The apr_bucket_foo_make functions are used
1316
* inside the bucket code to change the type of buckets in place;
1317
* other code should call apr_bucket_foo_create. All the initialization
1318
* functions change nothing if they fail.
1319
*/
1320
1321
/**
1322
* Create an End of Stream bucket. This indicates that there is no more data
1323
* coming from down the filter stack. All filters should flush at this point.
1324
* @param list The freelist from which this bucket should be allocated
1325
* @return The new bucket, or NULL if allocation failed
1326
*/
1327
APU_DECLARE(
apr_bucket
*)
apr_bucket_eos_create
(
apr_bucket_alloc_t
*list);
1328
1329
/**
1330
* Make the bucket passed in an EOS bucket. This indicates that there is no
1331
* more data coming from down the filter stack. All filters should flush at
1332
* this point.
1333
* @param b The bucket to make into an EOS bucket
1334
* @return The new bucket, or NULL if allocation failed
1335
*/
1336
APU_DECLARE(
apr_bucket
*)
apr_bucket_eos_make
(
apr_bucket
*b);
1337
1338
/**
1339
* Create a flush bucket. This indicates that filters should flush their
1340
* data. There is no guarantee that they will flush it, but this is the
1341
* best we can do.
1342
* @param list The freelist from which this bucket should be allocated
1343
* @return The new bucket, or NULL if allocation failed
1344
*/
1345
APU_DECLARE(
apr_bucket
*)
apr_bucket_flush_create
(
apr_bucket_alloc_t
*list);
1346
1347
/**
1348
* Make the bucket passed in a FLUSH bucket. This indicates that filters
1349
* should flush their data. There is no guarantee that they will flush it,
1350
* but this is the best we can do.
1351
* @param b The bucket to make into a FLUSH bucket
1352
* @return The new bucket, or NULL if allocation failed
1353
*/
1354
APU_DECLARE(
apr_bucket
*)
apr_bucket_flush_make
(
apr_bucket
*b);
1355
1356
/**
1357
* Create a bucket referring to long-lived data.
1358
* @param buf The data to insert into the bucket
1359
* @param nbyte The size of the data to insert.
1360
* @param list The freelist from which this bucket should be allocated
1361
* @return The new bucket, or NULL if allocation failed
1362
*/
1363
APU_DECLARE(
apr_bucket
*)
apr_bucket_immortal_create
(const
char
*buf,
1364
apr_size_t nbyte,
1365
apr_bucket_alloc_t
*list);
1366
1367
/**
1368
* Make the bucket passed in a bucket refer to long-lived data
1369
* @param b The bucket to make into a IMMORTAL bucket
1370
* @param buf The data to insert into the bucket
1371
* @param nbyte The size of the data to insert.
1372
* @return The new bucket, or NULL if allocation failed
1373
*/
1374
APU_DECLARE(
apr_bucket
*)
apr_bucket_immortal_make
(
apr_bucket
*b,
1375
const
char
*buf,
1376
apr_size_t nbyte);
1377
1378
/**
1379
* Create a bucket referring to data on the stack.
1380
* @param buf The data to insert into the bucket
1381
* @param nbyte The size of the data to insert.
1382
* @param list The freelist from which this bucket should be allocated
1383
* @return The new bucket, or NULL if allocation failed
1384
*/
1385
APU_DECLARE(
apr_bucket
*)
apr_bucket_transient_create
(const
char
*buf,
1386
apr_size_t nbyte,
1387
apr_bucket_alloc_t
*list);
1388
1389
/**
1390
* Make the bucket passed in a bucket refer to stack data
1391
* @param b The bucket to make into a TRANSIENT bucket
1392
* @param buf The data to insert into the bucket
1393
* @param nbyte The size of the data to insert.
1394
* @return The new bucket, or NULL if allocation failed
1395
*/
1396
APU_DECLARE(
apr_bucket
*)
apr_bucket_transient_make
(
apr_bucket
*b,
1397
const
char
*buf,
1398
apr_size_t nbyte);
1399
1400
/**
1401
* Create a bucket referring to memory on the heap. If the caller asks
1402
* for the data to be copied, this function always allocates 4K of
1403
* memory so that more data can be added to the bucket without
1404
* requiring another allocation. Therefore not all the data may be put
1405
* into the bucket. If copying is not requested then the bucket takes
1406
* over responsibility for free()ing the memory.
1407
* @param buf The buffer to insert into the bucket
1408
* @param nbyte The size of the buffer to insert.
1409
* @param free_func Function to use to free the data; NULL indicates that the
1410
* bucket should make a copy of the data
1411
* @param list The freelist from which this bucket should be allocated
1412
* @return The new bucket, or NULL if allocation failed
1413
*/
1414
APU_DECLARE(
apr_bucket
*)
apr_bucket_heap_create
(const
char
*buf,
1415
apr_size_t nbyte,
1416
void
(*free_func)(
void
*data),
1417
apr_bucket_alloc_t
*list);
1418
/**
1419
* Make the bucket passed in a bucket refer to heap data
1420
* @param b The bucket to make into a HEAP bucket
1421
* @param buf The buffer to insert into the bucket
1422
* @param nbyte The size of the buffer to insert.
1423
* @param free_func Function to use to free the data; NULL indicates that the
1424
* bucket should make a copy of the data
1425
* @return The new bucket, or NULL if allocation failed
1426
*/
1427
APU_DECLARE(
apr_bucket
*)
apr_bucket_heap_make
(
apr_bucket
*b, const
char
*buf,
1428
apr_size_t nbyte,
1429
void
(*free_func)(
void
*data));
1430
1431
/**
1432
* Create a bucket referring to memory allocated from a pool.
1433
*
1434
* @param buf The buffer to insert into the bucket
1435
* @param length The number of bytes referred to by this bucket
1436
* @param pool The pool the memory was allocated from
1437
* @param list The freelist from which this bucket should be allocated
1438
* @return The new bucket, or NULL if allocation failed
1439
*/
1440
APU_DECLARE(
apr_bucket
*)
apr_bucket_pool_create
(const
char
*buf,
1441
apr_size_t length,
1442
apr_pool_t
*pool,
1443
apr_bucket_alloc_t
*list);
1444
1445
/**
1446
* Make the bucket passed in a bucket refer to pool data
1447
* @param b The bucket to make into a pool bucket
1448
* @param buf The buffer to insert into the bucket
1449
* @param length The number of bytes referred to by this bucket
1450
* @param pool The pool the memory was allocated from
1451
* @return The new bucket, or NULL if allocation failed
1452
*/
1453
APU_DECLARE(
apr_bucket
*)
apr_bucket_pool_make
(
apr_bucket
*b, const
char
*buf,
1454
apr_size_t length,
1455
apr_pool_t
*pool);
1456
1457
#if APR_HAS_MMAP
1458
/**
1459
* Create a bucket referring to mmap()ed memory.
1460
* @param mm The mmap to insert into the bucket
1461
* @param start The offset of the first byte in the mmap
1462
* that this bucket refers to
1463
* @param length The number of bytes referred to by this bucket
1464
* @param list The freelist from which this bucket should be allocated
1465
* @return The new bucket, or NULL if allocation failed
1466
*/
1467
APU_DECLARE(
apr_bucket
*)
apr_bucket_mmap_create
(
apr_mmap_t
*mm,
1468
apr_off_t start,
1469
apr_size_t length,
1470
apr_bucket_alloc_t
*list);
1471
1472
/**
1473
* Make the bucket passed in a bucket refer to an MMAP'ed file
1474
* @param b The bucket to make into a MMAP bucket
1475
* @param mm The mmap to insert into the bucket
1476
* @param start The offset of the first byte in the mmap
1477
* that this bucket refers to
1478
* @param length The number of bytes referred to by this bucket
1479
* @return The new bucket, or NULL if allocation failed
1480
*/
1481
APU_DECLARE(
apr_bucket
*)
apr_bucket_mmap_make
(
apr_bucket
*b,
apr_mmap_t
*mm,
1482
apr_off_t start,
1483
apr_size_t length);
1484
#endif
1485
1486
/**
1487
* Create a bucket referring to a socket.
1488
* @param thissock The socket to put in the bucket
1489
* @param list The freelist from which this bucket should be allocated
1490
* @return The new bucket, or NULL if allocation failed
1491
*/
1492
APU_DECLARE(
apr_bucket
*)
apr_bucket_socket_create
(
apr_socket_t
*thissock,
1493
apr_bucket_alloc_t
*list);
1494
/**
1495
* Make the bucket passed in a bucket refer to a socket
1496
* @param b The bucket to make into a SOCKET bucket
1497
* @param thissock The socket to put in the bucket
1498
* @return The new bucket, or NULL if allocation failed
1499
*/
1500
APU_DECLARE(
apr_bucket
*)
apr_bucket_socket_make
(
apr_bucket
*b,
1501
apr_socket_t
*thissock);
1502
1503
/**
1504
* Create a bucket referring to a pipe.
1505
* @param thispipe The pipe to put in the bucket
1506
* @param list The freelist from which this bucket should be allocated
1507
* @return The new bucket, or NULL if allocation failed
1508
*/
1509
APU_DECLARE(
apr_bucket
*)
apr_bucket_pipe_create
(
apr_file_t
*thispipe,
1510
apr_bucket_alloc_t
*list);
1511
1512
/**
1513
* Make the bucket passed in a bucket refer to a pipe
1514
* @param b The bucket to make into a PIPE bucket
1515
* @param thispipe The pipe to put in the bucket
1516
* @return The new bucket, or NULL if allocation failed
1517
*/
1518
APU_DECLARE(
apr_bucket
*)
apr_bucket_pipe_make
(
apr_bucket
*b,
1519
apr_file_t
*thispipe);
1520
1521
/**
1522
* Create a bucket referring to a file.
1523
* @param fd The file to put in the bucket
1524
* @param offset The offset where the data of interest begins in the file
1525
* @param len The amount of data in the file we are interested in
1526
* @param p The pool into which any needed structures should be created
1527
* while reading from this file bucket
1528
* @param list The freelist from which this bucket should be allocated
1529
* @return The new bucket, or NULL if allocation failed
1530
* @remark If the file is truncated such that the segment of the file
1531
* referenced by the bucket no longer exists, an attempt to read
1532
* from the bucket will fail with APR_EOF.
1533
* @remark apr_brigade_insert_file() should generally be used to
1534
* insert files into brigades, since that function can correctly
1535
* handle large file issues.
1536
*/
1537
APU_DECLARE(
apr_bucket
*)
apr_bucket_file_create
(
apr_file_t
*fd,
1538
apr_off_t offset,
1539
apr_size_t len,
1540
apr_pool_t
*p,
1541
apr_bucket_alloc_t
*list);
1542
1543
/**
1544
* Make the bucket passed in a bucket refer to a file
1545
* @param b The bucket to make into a FILE bucket
1546
* @param fd The file to put in the bucket
1547
* @param offset The offset where the data of interest begins in the file
1548
* @param len The amount of data in the file we are interested in
1549
* @param p The pool into which any needed structures should be created
1550
* while reading from this file bucket
1551
* @return The new bucket, or NULL if allocation failed
1552
*/
1553
APU_DECLARE(
apr_bucket
*)
apr_bucket_file_make
(
apr_bucket
*b,
apr_file_t
*fd,
1554
apr_off_t offset,
1555
apr_size_t len,
apr_pool_t
*p);
1556
1557
/**
1558
* Enable or disable memory-mapping for a FILE bucket (default is enabled)
1559
* @param b The bucket
1560
* @param enabled Whether memory-mapping should be enabled
1561
* @return APR_SUCCESS normally, or an error code if the operation fails
1562
*/
1563
APU_DECLARE(
apr_status_t
)
apr_bucket_file_enable_mmap
(
apr_bucket
*b,
1564
int
enabled);
1565
1566
/** @} */
1567
#ifdef __cplusplus
1568
}
1569
#endif
1570
1571
#endif
/* !APR_BUCKETS_H */
Generated by
1.8.4