util_varbuf.h revision cda2a8c4fe289419f62e8b9607cafe4812974840
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi/* Licensed to the Apache Software Foundation (ASF) under one or more
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * contributor license agreements. See the NOTICE file distributed with
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd * this work for additional information regarding copyright ownership.
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd * The ASF licenses this file to You under the Apache License, Version 2.0
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd * (the "License"); you may not use this file except in compliance with
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * the License. You may obtain a copy of the License at
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc * Unless required by applicable law or agreed to in writing, software
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * distributed under the License is distributed on an "AS IS" BASIS,
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen * See the License for the specific language governing permissions and
2e545ce2450a9953665f701bb05350f0d3f26275nd * limitations under the License.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @brief Apache resizable variable length buffer library
1d980e5489836e977ba59b419e27b0ec875c4bd3takashiextern "C" {
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi/** A resizable buffer */
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi /** the actual buffer; will point to a const '\0' if avail == 0 */
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi /** allocated size of the buffer (minus one for the final \0);
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * must only be changed using ap_varbuf_grow() */
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi /** length of string in buffer, or AP_VARBUF_UNKNOWN. This determines how
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * much memory is copied by ap_varbuf_grow() and where
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * ap_varbuf_strmemcat() will append to the buffer. */
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi /** the pool for memory allocations and for registering the cleanup;
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * the buffer memory will be released when this pool is destroyed */
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi /** opaque info for memory allocation */
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar/** initialize a resizable buffer. It is safe to re-initialize a prevously
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * used ap_varbuf. The old buffer will be released when the corresponding
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * pool is destroyed.
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen * @param pool the pool to allocate small buffers from and to register the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen * cleanup with
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen * @param vb pointer to the ap_varbuf struct
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @init_size the initial size of the buffer (see ap_varbuf_grow() for details)
1d980e5489836e977ba59b419e27b0ec875c4bd3takashiAP_DECLARE(void) ap_varbuf_init(apr_pool_t *pool, struct ap_varbuf *vb,
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi/** grow a resizable buffer. If the vb->buf cannot be grown in place, it will
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * be reallocated and up to vb->strlen + 1 bytes of memory will be copied to
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * the new location. If vb->strlen == AP_VARBUF_UNKNOWN, the whole buffer
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * is copied.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param vb pointer to the ap_varbuf struct
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param new_size the minimum new size of the buffer
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @note ap_varbuf_grow() will usually at least double vb->buf's size with
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * every invocation in order to reduce reallications.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @note ap_varbuf_grow() will use pool memory for small and allocator
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * mem nodes for larger allocations.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @note ap_varbuf_grow() will call vb->pool's abort function if out of memory.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashiAP_DECLARE(void) ap_varbuf_grow(struct ap_varbuf *vb, apr_size_t new_size);
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi/** Release memory from a ap_varbuf immediately, if possible.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * This allows to free large buffers before the corresponding pool is
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * destroyed. Only larger allocations using mem nodes will be freed.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param vb pointer to the ap_varbuf struct
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @note After ap_varbuf_free(), vb must not be used unless ap_varbuf_init()
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * is called again.
1d980e5489836e977ba59b419e27b0ec875c4bd3takashiAP_DECLARE(void) ap_varbuf_free(struct ap_varbuf *vb);
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi/** Concatenate a string to an ap_varbuf
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param vb pointer to the ap_varbuf struct
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param str the string to append; must be at least len bytes long
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @param len the number of characters of *str to concatenate to the buf
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @note vb->strlen will be set to the length of the new string
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @note vb->buf will be null-terminated
1f1b6bf13313fdd14a45e52e553d3ff28689b717coarAP_DECLARE(void) ap_varbuf_strmemcat(struct ap_varbuf *vb, const char *str,
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar/** Duplicate an ap_varbuf's content into pool memory
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @param p the pool to allocate from
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @param vb the ap_varbuf to copy from
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @param prepend an optional buffer to prepend (may be NULL)
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar * @param prepend_len length of prepend
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param append an optional buffer to append (may be NULL)
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param append_len length of append
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param new_len where to store the length of the resulting string
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * (may be NULL)
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @return the new string
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung * @note ap_varbuf_pdup() uses vb->strlen to determine how much memory to
727872d18412fc021f03969b8641810d8896820bhumbedooh * copy. It works even if 0-bytes are embedded in vb->buf, prepend, or
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohAP_DECLARE(char *) ap_varbuf_pdup(apr_pool_t *p, struct ap_varbuf *vb,
0d0ba3a410038e179b695446bb149cce6264e0abnd/** Concatenate a string to an ap_varbuf
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh * @param vb pointer to the ap_varbuf struct
0d0ba3a410038e179b695446bb149cce6264e0abnd * @param str the string to append
0d0ba3a410038e179b695446bb149cce6264e0abnd * @note vb->strlen will be set to the length of the new string
727872d18412fc021f03969b8641810d8896820bhumbedooh#define ap_varbuf_strcat(vb, str) ap_varbuf_strmemcat(vb, str, strlen(str))
0d0ba3a410038e179b695446bb149cce6264e0abnd/** Perform string substitutions based on regexp match, using an ap_varbuf.
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh * This function behaves like ap_pregsub(), but appends to an ap_varbuf
205f749042ed530040a4f0080dbcb47ceae8a374rjung * instead of allocating the result from a pool.
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen * @param input An arbitrary string containing $1 through $9. These are
0d0ba3a410038e179b695446bb149cce6264e0abnd * replaced with the corresponding matched sub-expressions
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd * @param source The string that was originally matched to the regex
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd * @param nmatch the nmatch returned from ap_pregex
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd * @param pmatch the pmatch array returned from ap_pregex
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi * @param maxlen the maximum string length to append to vb
const char *input,
#ifdef __cplusplus