manpages

apreq_util.h(3)

include/apreq_util.h(3) libapreq2 include/apreq_util.h(3)

NAME

include/apreq_util.h - Utility functions for apreq.

SYNOPSIS

#include 'apr_file_io.h'
#include 'apr_buckets.h'
#include 'apreq.h'

Functions


char * apreq_join (apr_pool_t *p, const char *sep, const apr_array_header_t *arr, apreq_join_t mode)
apr_ssize_t apreq_index (const char *hay, apr_size_t hlen, const char *ndl, apr_size_t nlen, const apreq_match_t type)
apr_size_t apreq_quote (char *dest, const char *src, const apr_size_t slen)
apr_size_t apreq_quote_once (char *dest, const char *src, const apr_size_t slen)
apr_size_t apreq_encode (char *dest, const char *src, const apr_size_t slen)
apr_size_t apreq_cp1252_to_utf8 (char *dest, const char *src, apr_size_t slen)
apreq_charset_t apreq_charset_divine (const char *src, apr_size_t slen)
apr_status_t apreq_decode (char *dest, apr_size_t *dlen, const char *src, apr_size_t slen)
apr_status_t apreq_decodev (char *dest, apr_size_t *dlen, struct iovec *v, int nelts)
static APR_INLINE char * apreq_escape (apr_pool_t *p, const char *src, const apr_size_t slen)
static APR_INLINE apr_ssize_t apreq_unescape (char *str)
apr_int64_t apreq_atoi64f (const char *s)
apr_int64_t apreq_atoi64t (const char *s)
apr_status_t apreq_brigade_fwrite (apr_file_t *f, apr_off_t *wlen, apr_bucket_brigade *bb)
apr_status_t apreq_file_mktemp (apr_file_t **fp, apr_pool_t *pool, const char *path)
static APR_INLINE apr_status_t apreq_brigade_setaside (apr_bucket_brigade *bb, apr_pool_t *p)
static APR_INLINE apr_status_t apreq_brigade_copy (apr_bucket_brigade *d, apr_bucket_brigade *s)
static APR_INLINE void apreq_brigade_move (apr_bucket_brigade *d, apr_bucket_brigade *s, apr_bucket *e)
apr_status_t apreq_header_attribute (const char *hdr, const char *name, const apr_size_t nlen, const char **val, apr_size_t *vlen)
apr_status_t apreq_brigade_concat (apr_pool_t *pool, const char *temp_dir, apr_size_t brigade_limit, apr_bucket_brigade *out, apr_bucket_brigade *in)
apr_file_t * apreq_brigade_spoolfile (apr_bucket_brigade *bb)

Detailed Description

Utility functions for apreq.

This header contains useful functions for creating new parsers, hooks or modules. It includes

  • string <-> array converters
  • substring search functions
  • simple encoders & decoders for urlencoded strings
  • simple time, date, & file-size converters

Function Documentation

apr_int64_t apreq_atoi64f (const char * s)

Converts file sizes (KMG) to bytes

Parameters

s file size matching m/^\d+[KMG]b?$/i

Returns

64-bit integer representation of s.

Todo

What happens when s is malformed? Should this return an unsigned value instead?

apr_int64_t apreq_atoi64t (const char * s)

Converts time strings (YMDhms) to seconds

Parameters

s time string matching m/^\+?\d+[YMDhms]$/

Returns

64-bit integer representation of s as seconds.

Todo

What happens when s is malformed? Should this return an unsigned value instead?

apr_status_t apreq_brigade_concat (apr_pool_t * pool, const char * temp_dir, apr_size_t brigade_limit, apr_bucket_brigade * out, apr_bucket_brigade * in)

Concatenates the brigades, spooling large brigades into a tempfile (APREQ_SPOOL) bucket.

Parameters

pool Pool for creating a tempfile bucket.
temp_dir Directory for tempfile creation.
brigade_limit If out's length would exceed this value, the appended buckets get written to a tempfile.
out Resulting brigade.
in Brigade to append.

Returns

APR_SUCCESS.

Error status code resulting from either apr_brigade_length(), apreq_file_mktemp(), apreq_brigade_fwrite(), or apr_file_seek().

Todo

Flesh out these error codes, making them as explicit as possible.

static APR_INLINE apr_status_t apreq_brigade_copy (apr_bucket_brigade * d, apr_bucket_brigade * s) [static]

Copy a brigade.

Parameters

d (destination) Copied buckets are appended to this brigade.
s (source) Brigade to copy from.

Returns

APR_SUCCESS.

Error status code from an unsuccessful apr_bucket_copy().

Remarks

s == d produces Undefined Behavior.

apr_status_t apreq_brigade_fwrite (apr_file_t * f, apr_off_t * wlen, apr_bucket_brigade * bb)

Writes brigade to a file.

Parameters

f File that gets the brigade.
wlen On a successful return, wlen holds the length of the brigade, which is the amount of data written to the file.
bb Bucket brigade.

Returns

APR_SUCCESS.

Error status code from either an unsuccessful apr_bucket_read(), or a failed apr_file_writev().

Remarks

This function leaks a bucket brigade into bb->p whenever the final bucket in bb is a spool bucket.

static APR_INLINE void apreq_brigade_move (apr_bucket_brigade * d, apr_bucket_brigade * s, apr_bucket * e) [static]

Move the front of a brigade.

Parameters

d (destination) Append buckets to this brigade.
s (source) Brigade to take buckets from.
e First bucket of s after the move. All buckets before e are appended to d.

Remarks

This moves all buckets when e == APR_BRIGADE_SENTINEL(s).

static APR_INLINE apr_status_t apreq_brigade_setaside (apr_bucket_brigade * bb, apr_pool_t * p) [static]

Set aside all buckets in the brigade.

Parameters

bb Brigade.
p Setaside buckets into this pool.

Returns

APR_SUCCESS.

Error status code from an unsuccessful apr_bucket_setaside().

apr_file_t* apreq_brigade_spoolfile (apr_bucket_brigade * bb)

Determines the spool file used by the brigade. Returns NULL if the brigade is not spooled in a file (does not use an APREQ_SPOOL bucket).

Parameters

bb the bucket brigade

Returns

the spool file, or NULL.

apreq_charset_t apreq_charset_divine (const char * src, apr_size_t slen)

Heuristically determine the charset of a string.

Parameters

src String to scan.
slen Length of string.

Returns

APREQ_CHARSET_ASCII if the string contains only 7-bit chars;

APREQ_CHARSET_UTF8 if the string is a valid utf8 byte sequence;

APREQ_CHARSET_LATIN1 if the string has no control chars;

APREQ_CHARSET_CP1252 if the string has control chars.

apr_size_t apreq_cp1252_to_utf8 (char * dest, const char * src, apr_size_t slen)

Convert a string from cp1252 to utf8. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.

Parameters

dest Location of utf8-encoded result string. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.
src Original string.
slen Length of original string.

Returns

length of utf8-encoded string in dest; does not exceed 3 * slen.

apr_status_t apreq_decode (char * dest, apr_size_t * dlen, const char * src, apr_size_t slen)

Url-decodes a string.

Parameters

dest Location of url-encoded result string. Caller must ensure dest is large enough to hold the encoded string and trailing null character.
dlen points to resultant length of url-decoded string in dest
src Original string.
slen Length of original string.

Returns

APR_SUCCESS.

APR_INCOMPLETE if the string ends in the middle of an escape sequence.

APREQ_ERROR_BADSEQ or APREQ_ERROR_BADCHAR on malformed input.

Remarks

In the non-success case, dlen will be set to include the last succesfully decoded value. This function decodes %uXXXX into a utf8 (wide) character, following ECMA-262 (the Javascript spec) Section B.2.1.

apr_status_t apreq_decodev (char * dest, apr_size_t * dlen, struct iovec * v, int nelts)

Url-decodes an iovec array.

Parameters

dest Location of url-encoded result string. Caller must ensure dest is large enough to hold the encoded string and trailing null character.
dlen Resultant length of dest.
v Array of iovecs that represent the source string
nelts Number of iovecs in the array.

Returns

APR_SUCCESS.

APR_INCOMPLETE if the iovec ends in the middle of an escape sequence.

APREQ_ERROR_BADSEQ or APREQ_ERROR_BADCHAR on malformed input.

Remarks

In the non-APR_SUCCESS case, dlen will be set to include the last succesfully decoded value. This function decodes %uXXXX into a utf8 (wide) character, following ECMA-262 (the Javascript spec) Section B.2.1.

apr_size_t apreq_encode (char * dest, const char * src, const apr_size_t slen)

Url-encodes a string.

Parameters

dest Location of url-encoded result string. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.
src Original string.
slen Length of original string.

Returns

length of url-encoded string in dest; does not exceed 3 * slen.

static APR_INLINE char* apreq_escape (apr_pool_t * p, const char * src, const apr_size_t slen) [static]

Returns an url-encoded copy of a string.

Parameters

p Pool used to allocate the return value.
src Original string.
slen Length of original string.

Returns

The url-encoded string.

Remarks

Use this function insead of apreq_encode if its caller might otherwise overflow dest.

apr_status_t apreq_file_mktemp (apr_file_t ** fp, apr_pool_t * pool, const char * path)

Makes a temporary file.

Parameters

fp Points to the temporary apr_file_t on success.
pool Pool to associate with the temp file. When the pool is destroyed, the temp file will be closed and deleted.
path The base directory which will contain the temp file. If param == NULL, the directory will be selected via tempnam(). See the tempnam manpage for details.

Returns

APR_SUCCESS.

Error status code from unsuccessful apr_filepath_merge(), or a failed apr_file_mktemp().

apr_status_t apreq_header_attribute (const char * hdr, const char * name, const apr_size_t nlen, const char ** val, apr_size_t * vlen)

Search a header string for the value of a particular named attribute.

Parameters

hdr Header string to scan.
name Name of attribute to search for.
nlen Length of name.
val Location of (first) matching value.
vlen Length of matching value.

Returns

APR_SUCCESS.

APREQ_ERROR_NOATTR if the attribute is not found.

APREQ_ERROR_BADSEQ if an unpaired quote mark was detected.

apr_ssize_t apreq_index (const char * hay, apr_size_t hlen, const char * ndl, apr_size_t nlen, const apreq_match_t type)

Returns offset of match string's location, or -1 if no match is found.

Parameters

hay Location of bytes to scan.
hlen Number of bytes available for scanning.
ndl Search string
nlen Length of search string.
type Match type.

Returns

Offset of match string, or -1 if no match is found.

char* apreq_join (apr_pool_t * p, const char * sep, const apr_array_header_t * arr, apreq_join_t mode)

Join an array of values. The result is an empty string if there are no values.

Parameters

p Pool to allocate return value.
sep String that is inserted between the joined values.
arr Array of apreq_value_t entries.
mode Join type- see apreq_join_t.

Returns

Joined string, or NULL on error

apr_size_t apreq_quote (char * dest, const char * src, const apr_size_t slen)

Places a quoted copy of src into dest. Embedded quotes are escaped with a backslash ('\').

Parameters

dest Location of quoted copy. Must be large enough to hold the copy and trailing null byte.
src Original string.
slen Length of original string.
dest Destination string.

Returns

length of quoted copy in dest.

apr_size_t apreq_quote_once (char * dest, const char * src, const apr_size_t slen)

Same as apreq_quote() except when src begins and ends in quote marks. In that case it assumes src is quoted correctly, and just copies src to dest.

Parameters

dest Location of quoted copy. Must be large enough to hold the copy and trailing null byte.
src Original string.
slen Length of original string.
dest Destination string.

Returns

length of quoted copy in dest.

static APR_INLINE apr_ssize_t apreq_unescape (char * str) [static]

An in-situ url-decoder.

Parameters

str The string to decode

Returns

Length of decoded string, or < 0 on error.

Author

Generated automatically by Doxygen for libapreq2 from the source code.

Wed Mar 10 2021 Version 2.16