Apache Portable Runtime
apr_buffer.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 /**
18  * @file apr_buffer.h
19  * @brief APR-UTIL Buffer
20  */
21 #ifndef APR_BUFFER_H
22 #define APR_BUFFER_H
23 
24 /**
25  * @defgroup APR_Util_Buffer Buffer handling
26  *
27  * An APR buffer is a structure that can contain a zero terminated string, or
28  * a non zero terminated block of memory, and allow such structures to be
29  * passed around and handled in a memory efficient way.
30  *
31  * We allow two buffers to be compared without duplicating strings. Memory
32  * buffers can be converted to string buffers safely. The contents of buffers
33  * can be copied into and out of other systems like caches using memory
34  * allocation callbacks.
35  * @ingroup APR_Util
36  * @{
37  */
38 
39 #include "apr.h"
40 #include "apr_pools.h"
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 /**
47  * When passing a string to apr_buffer_str_create or apr_buffer_str_set, this
48  * value can be passed to indicate a string with unknown length, and have
49  * apr_buffer_str_create and apr_buffer_str_set compute the length automatically.
50  */
51 #define APR_BUFFER_STRING (-1)
52 
53 
54 /**
55  * Perform no encoding on memory buffers during apr_buffer_pstrcat().
56  */
57 #define APR_BUFFER_PLAIN 0
58 /**
59  * Perform base64 encoding on memory buffers during apr_buffer_pstrcat().
60  */
61 #define APR_BUFFER_BASE64 1
62 
63 
64 /**
65  * Structure for efficiently tracking a buffer that could contain
66  * a zero terminated string, or a fixed length non zero string.
67  */
68 typedef struct
69 {
70  /** pointer to the data, which could be a string or a memory block. */
71  union {
72  char *str;
73  void *mem;
74  } d;
75 
76  /** is the data zero terminated */
77  unsigned int zero_terminated:1;
78 
79  /** size of the data, excluding terminating zero */
80 #if defined(SIZE_MAX) && SIZE_MAX == APR_UINT64_MAX
81  apr_size_t size:63;
82 #elif defined(SIZE_MAX) && SIZE_MAX == APR_UINT32_MAX
83  apr_size_t size:31;
84 #else
85 #error sizeof size_t is neither 64 nor 32 bit (SIZE_MAX not defined)
86 #endif
87 
88 } apr_buffer_t;
89 
90 
91 /**
92  * Set a apr_buffer_t with non zero terminated memory.
93  *
94  * @param buf The buffer to allocate to
95  * @param mem The memory buffer to assign to the buffer
96  * @param len The length of the memory buffer
97  * @return APR_SUCCESS, or APR_EINVAL if len overflows.
98  */
100  void *mem, apr_size_t len)
101  __attribute__((nonnull(1)));
102 
103 
104 /**
105  * Create a apr_buffer_t containing non zero terminated memory.
106  *
107  * The buffer structure is allocated from the pool, while the contents are
108  * stored as is. It is the responsibility of the caller to ensure the
109  * contents have a lifetime as long as the pool.
110  * @param mb The memory buffer returned
111  * @param pool The pool to allocate from
112  * @param mem The memory to assign to the buffer
113  * @param len The length of the memory
114  * @return Returns APR_ENOMEM if we could not allocate enough memory,
115  * APR_EINVAL if len overflows, otherwise APR_SUCCESS.
116  */
118  apr_pool_t *pool,
119  void *mem, apr_size_t len)
120  __attribute__((nonnull(1,2)));
121 
122 /**
123  * Set a apr_buffer_t with a zero terminated string.
124  *
125  * @param buf The buffer to assign the data to.
126  * @param str The zero terminated string to assign to the buffer.
127  * @param len The length of the string without terminating zero, or
128  * APR_BUFFER_STRING to have the length calculated.
129  * @return APR_SUCCESS, or APR_EINVAL if len overflows.
130  */
132  char *str, apr_ssize_t len)
133  __attribute__((nonnull(1)));
134 
135 /**
136  * Create a apr_buffer_t containing a zero terminated string.
137  *
138  * The buffer structure is allocated from the pool, while the contents are
139  * stored as is. It is the responsibility of the caller to ensure the
140  * contents have a lifetime as long as the pool.
141  * @param sb The string buffer returned
142  * @param pool The pool to allocate from.
143  * @param str The string to assign to the buffer.
144  * @param len The length of the string, or APR_BUFFER_STRING to have the length
145  * calculated.
146  * @return Returns APR_ENOMEM if we could not allocate enough memory,
147  * APR_EINVAL if len overflows, otherwise APR_SUCCESS.
148  */
150  apr_pool_t *pool,
151  char *str, apr_ssize_t len)
152  __attribute__((nonnull(1)));
153 
154 /**
155  * Create a apr_buffer_t containing a NULL payload.
156  *
157  * The buffer structure is allocated from the pool.
158  * @param nb The null buffer returned
159  * @param pool The pool to allocate from.
160  * @return Returns APR_ENOMEM if we could not allocate enough memory,
161  * otherwise APR_SUCCESS.
162  */
164  apr_pool_t *pool)
165  __attribute__((nonnull(1)));
166 
167 
168 /**
169  * Does the buffer contain a NULL buffer.
170  *
171  * If the internal buffer is NULL, 1 is returned, otherwise 0.
172  *
173  * @param buf The buffer.
174  * @return Returns 1 if buffer is null, otherwise 0.
175  */
177  __attribute__((nonnull(1)));
178 
179 
180 /**
181  * Does the buffer contain a zero terminated string.
182  *
183  * If the buffer is already zero terminated, 1 is returned, otherwise 0.
184  *
185  * @param buf The buffer.
186  * @return Returns 1 if zero terminated, otherwise 0.
187  */
189  __attribute__((nonnull(1)));
190 
191 
192 /**
193  * Return the zero terminated string from a buffer containing a
194  * string.
195  *
196  * If the buffer contains a string, the original string
197  * is returned.
198  *
199  * If the buffer contains non zero terminated memory, NULL will be
200  * returned.
201  *
202  * Use this function when we want to be sure you're dealing with
203  * a string, and want to avoid duplication.
204  * @param buf The string/memory buffer.
205  * @return The zero terminated string. Returns NULL if the buffer
206  * contains memory.
207  */
209  __attribute__((nonnull(1)));
210 
211 
212 /**
213  * Return a copy of the buffer as a zero terminated string allocated from
214  * a pool.
215  *
216  * The memory or string buffer will be copied, as appropriate.
217  *
218  * Use this function when you need the buffer to become a string with
219  * the lifetime of the pool provided.
220  * @param pool The pool to allocate from.
221  * @param buf The buffer.
222  * @return The zero terminated string. Returns NULL if we could not
223  * allocate memory.
224  */
226  __attribute__((nonnull(1,2)));
227 
228 
229 /**
230  * Return the non zero terminated string/memory buffer.
231  *
232  * If a size is provided, the size of the buffer without the terminating zero
233  * will be returned.
234  *
235  * Use this function when you need to pass the content of the buffer to an
236  * API requiring an area of memory and a length.
237  * @param buf The string/memory buffer.
238  * @param size Location to write the size to.
239  * @return The memory buffer.
240  */
241 APR_DECLARE(void *) apr_buffer_mem(const apr_buffer_t *buf, apr_size_t *size)
242  __attribute__((nonnull(1)));
243 
244 
245 /**
246  * Return a copy of the content of a buffer as non zero terminated memory
247  * allocated from a pool.
248  *
249  * If a size is provided, the size of the buffer will be returned.
250  * @param pool The pool to allocate from.
251  * @param buf The string/memory buffer.
252  * @param size Location to write the size to.
253  * @return The zero memory buffer.
254  */
255 APR_DECLARE(void *) apr_buffer_pmemdup(apr_pool_t *pool, const apr_buffer_t *buf, apr_size_t *size)
256  __attribute__((nonnull(1,2)));
257 
258 
259 /**
260  * Return the buffer length.
261  *
262  * The size of the underlying buffer is returned, excluding the terminating
263  * zero if present.
264  *
265  * Use this function to know the length of the data in the buffer.
266  * @param buf The string/memory buffer.
267  * @return The size of the buffer, excluding terminating zero if present.
268  */
269 APR_DECLARE(apr_size_t) apr_buffer_len(const apr_buffer_t *buf)
270  __attribute__((nonnull(1)));
271 
272 
273 /**
274  * Return the allocated length.
275  *
276  * The size of the underlying buffer is returned, including the terminating
277  * zero if present.
278  *
279  * Use this function when you need to know how much memory the buffer is
280  * taking up.
281  * @param buf The string/memory buffer.
282  * @return The size of the buffer, including terminating zero if present.
283  */
285  __attribute__((nonnull(1)));
286 
287 
288 /**
289  * Function called to allocate memory in the buffer functions.
290  *
291  * This allows buffers to be copied into and out of shared memory, or memory
292  * from other systems.
293  */
294 typedef void *(*apr_buffer_alloc)(void *ctx, apr_size_t size);
295 
296 /**
297  * Return a copy of an array of memory buffers.
298  *
299  * This function allows you to make a copy of one or more buffers, controlling
300  * the memory allocation yourself.
301  *
302  * Use this function to copy buffers, and the contents of the buffers, into and
303  * out of a cache.
304  * @param out The duplicated buffer array. If APR_ENOMEM is returned the
305  * array may be partially duplicated, it is up to the caller to free any
306  * memory allocated, and to pass zeroed buffers if needed.
307  * @param in The string/memory buffer.
308  * @param alloc The function callback to allocate memory for the buffer
309  * @param ctx Context to pass to the callback function
310  * @param nelts Number of buffers to duplicate
311  * @return APR_ENONMEM if the alloc function returned NULL, otherwise APR_SUCCESS
312  */
314  const apr_buffer_t *in,
315  apr_buffer_alloc alloc, void *ctx,
316  int nelts)
317  __attribute__((nonnull(1,2)));
318 
319 /**
320  * Return a copy of a string/memory buffer.
321  *
322  * This function allows you to make a copy of a buffer, controlling
323  * the memory allocation yourself.
324  *
325  * Use this function to copy a buffer, and the content of the buffer, into and
326  * out of a cache.
327  *
328  * @param out The duplicated buffer. If APR_ENOMEM is returned the buffer may
329  * be partially duplicated, it is up to the caller to free any memory
330  * allocated, and to pass zeroed buffers if needed.
331  * @param in The string/memory buffer.
332  * @param alloc The function callback to allocate memory for the buffer
333  * @param ctx Context to pass to the callback function
334  * @return APR_ENONMEM if the alloc function returned NULL, otherwise APR_SUCCESS
335  */
337  const apr_buffer_t *in,
338  apr_buffer_alloc alloc, void *ctx)
339  __attribute__((nonnull(1,2)));
340 
341 /**
342  * Copy the contents a buffer into another buffer.
343  *
344  * This function allows you to make a copy of the contents of a buffer, into
345  * and out of a cache.
346  *
347  * If the source buffer is NULL, the destination buffer will be assigned NULL
348  * as content.
349  *
350  * If the memory allocator callback is NULL, the contents of the source buffer
351  * will be assigned to the destination buffer as is.
352  *
353  * @param dst The first buffer
354  * @param src The second buffer
355  * @param alloc The function callback to allocate memory for the buffer
356  * @param ctx The context for the callback
357  * @return Returns dst.
358  */
360  const apr_buffer_t *src,
361  apr_buffer_alloc alloc, void *ctx)
362  __attribute__((nonnull(1)));
363 
364 /**
365  * Compare two possibly NULL buffers for equality.
366  *
367  * Each buffer can be either a string or memory buffer, or NULL.
368  *
369  * Two NULL buffers are considered equal.
370  *
371  * A string buffer and a memory buffer are considered equal if the length
372  * excluding any trailing zero is equal, and the contents without the trailing
373  * zero are the same.
374  * @param dst The first buffer
375  * @param src The second buffer
376  * @return Positive, negative, or zero, depending on whether src is greater
377  * than, less than, or equal to dst.
378  */
380  const apr_buffer_t *src);
381 
382 /**
383  * Concatenate multiple buffers and return a string.
384  *
385  * If the buffer contains a string, it will be copied across as is, memory
386  * buffers will be transformed by the flags specified before concatenation.
387  *
388  * This function can be used with an apr_array_header_t.
389  *
390  * @param p The pool from which to allocate
391  * @param buf The buffers to concatenate
392  * @param nelts The number of buffers to concatenate
393  * @param sep The optional separator between strings
394  * @param flags Allow memory buffers to be transformed before concatenation.
395  * APR_BUFFER_NONE copies memory buffer as is. APR_BUFFER_BASE64
396  * applies base64 encoding to the memory buffer.
397  * @param nbytes (output) strlen of new string (pass in NULL to omit)
398  * @return The new string
399  */
401  int nelts, const char *sep, int flags,
402  apr_size_t *nbytes);
403 
404 #ifdef __cplusplus
405 }
406 #endif
407 
408 /** @} */
409 #endif /* APR_BUFFER_H */
410 
APR Platform Definitions.
APR memory allocation.
apr_status_t apr_buffer_dup(apr_buffer_t **out, const apr_buffer_t *in, apr_buffer_alloc alloc, void *ctx)
apr_size_t apr_buffer_len(const apr_buffer_t *buf)
void *(* apr_buffer_alloc)(void *ctx, apr_size_t size)
Definition: apr_buffer.h:294
apr_buffer_t * apr_buffer_cpy(apr_buffer_t *dst, const apr_buffer_t *src, apr_buffer_alloc alloc, void *ctx)
apr_status_t apr_buffer_null_create(apr_buffer_t **nb, apr_pool_t *pool)
int apr_buffer_is_null(const apr_buffer_t *buf)
apr_status_t apr_buffer_arraydup(apr_buffer_t **out, const apr_buffer_t *in, apr_buffer_alloc alloc, void *ctx, int nelts)
void * apr_buffer_mem(const apr_buffer_t *buf, apr_size_t *size)
void * apr_buffer_pmemdup(apr_pool_t *pool, const apr_buffer_t *buf, apr_size_t *size)
char * apr_buffer_pstrncat(apr_pool_t *p, const apr_buffer_t *buf, int nelts, const char *sep, int flags, apr_size_t *nbytes)
int apr_buffer_is_str(const apr_buffer_t *buf)
apr_status_t apr_buffer_str_create(apr_buffer_t **sb, apr_pool_t *pool, char *str, apr_ssize_t len)
apr_status_t apr_buffer_mem_create(apr_buffer_t **mb, apr_pool_t *pool, void *mem, apr_size_t len)
apr_status_t apr_buffer_str_set(apr_buffer_t *buf, char *str, apr_ssize_t len)
char * apr_buffer_str(const apr_buffer_t *buf)
apr_status_t apr_buffer_mem_set(apr_buffer_t *buf, void *mem, apr_size_t len)
char * apr_buffer_pstrdup(apr_pool_t *pool, const apr_buffer_t *buf)
int apr_buffer_cmp(const apr_buffer_t *dst, const apr_buffer_t *src)
apr_size_t apr_buffer_allocated(const apr_buffer_t *buf)
int apr_status_t
Definition: apr_errno.h:44
#define APR_DECLARE(type)
Definition: apr.h:516
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
Definition: apr_buffer.h:69
unsigned int zero_terminated
Definition: apr_buffer.h:77