.TH "include/apreq_util.h" 3 "Wed Mar 10 2021" "Version 2.16" "libapreq2" \" -*- nroff -*-
.ad l
.nh
.SH NAME
include/apreq_util.h \- Utility functions for apreq\&.
.SH SYNOPSIS
.br
.PP
\fC#include 'apr_file_io\&.h'\fP
.br
\fC#include 'apr_buckets\&.h'\fP
.br
\fC#include 'apreq\&.h'\fP
.br
.SS "Functions"
.in +1c
.ti -1c
.RI "char * \fBapreq_join\fP (apr_pool_t *p, const char *sep, const apr_array_header_t *arr, \fBapreq_join_t\fP mode)"
.br
.ti -1c
.RI "apr_ssize_t \fBapreq_index\fP (const char *hay, apr_size_t hlen, const char *ndl, apr_size_t nlen, const \fBapreq_match_t\fP type)"
.br
.ti -1c
.RI "apr_size_t \fBapreq_quote\fP (char *dest, const char *src, const apr_size_t slen)"
.br
.ti -1c
.RI "apr_size_t \fBapreq_quote_once\fP (char *dest, const char *src, const apr_size_t slen)"
.br
.ti -1c
.RI "apr_size_t \fBapreq_encode\fP (char *dest, const char *src, const apr_size_t slen)"
.br
.ti -1c
.RI "apr_size_t \fBapreq_cp1252_to_utf8\fP (char *dest, const char *src, apr_size_t slen)"
.br
.ti -1c
.RI "\fBapreq_charset_t\fP \fBapreq_charset_divine\fP (const char *src, apr_size_t slen)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_decode\fP (char *dest, apr_size_t *dlen, const char *src, apr_size_t slen)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_decodev\fP (char *dest, apr_size_t *dlen, struct iovec *v, int nelts)"
.br
.ti -1c
.RI "static APR_INLINE char * \fBapreq_escape\fP (apr_pool_t *p, const char *src, const apr_size_t slen)"
.br
.ti -1c
.RI "static APR_INLINE apr_ssize_t \fBapreq_unescape\fP (char *str)"
.br
.ti -1c
.RI "apr_int64_t \fBapreq_atoi64f\fP (const char *s)"
.br
.ti -1c
.RI "apr_int64_t \fBapreq_atoi64t\fP (const char *s)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_brigade_fwrite\fP (apr_file_t *f, apr_off_t *wlen, apr_bucket_brigade *bb)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_file_mktemp\fP (apr_file_t **fp, apr_pool_t *pool, const char *path)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_brigade_setaside\fP (apr_bucket_brigade *bb, apr_pool_t *p)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_brigade_copy\fP (apr_bucket_brigade *d, apr_bucket_brigade *s)"
.br
.ti -1c
.RI "static APR_INLINE void \fBapreq_brigade_move\fP (apr_bucket_brigade *d, apr_bucket_brigade *s, apr_bucket *e)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_header_attribute\fP (const char *hdr, const char *name, const apr_size_t nlen, const char **val, apr_size_t *vlen)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_brigade_concat\fP (apr_pool_t *pool, const char *temp_dir, apr_size_t brigade_limit, apr_bucket_brigade *out, apr_bucket_brigade *in)"
.br
.ti -1c
.RI "apr_file_t * \fBapreq_brigade_spoolfile\fP (apr_bucket_brigade *bb)"
.br
.in -1c
.SH "Detailed Description"
.PP
Utility functions for apreq\&.
This header contains useful functions for creating new parsers, hooks or modules\&. It includes
.PP
.IP "\(bu" 2
string <-> array converters
.IP "\(bu" 2
substring search functions
.IP "\(bu" 2
simple encoders & decoders for urlencoded strings
.IP "\(bu" 2
simple time, date, & file-size converters
.PP
.SH "Function Documentation"
.PP
.SS "apr_int64_t apreq_atoi64f (const char * s)"
Converts file sizes (KMG) to bytes
.PP
\fBParameters\fP
.RS 4
\fIs\fP file size matching m/^\\d+[KMG]b?$/i
.RE
.PP
\fBReturns\fP
.RS 4
64-bit integer representation of s\&.
.RE
.PP
\fBTodo\fP
.RS 4
What happens when s is malformed? Should this return an unsigned value instead?
.RE
.PP
.SS "apr_int64_t apreq_atoi64t (const char * s)"
Converts time strings (YMDhms) to seconds
.PP
\fBParameters\fP
.RS 4
\fIs\fP time string matching m/^\\+?\\d+[YMDhms]$/
.RE
.PP
\fBReturns\fP
.RS 4
64-bit integer representation of s as seconds\&.
.RE
.PP
\fBTodo\fP
.RS 4
What happens when s is malformed? Should this return an unsigned value instead?
.RE
.PP
.SS "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\&.
.PP
\fBParameters\fP
.RS 4
\fIpool\fP Pool for creating a tempfile bucket\&.
.br
\fItemp_dir\fP Directory for tempfile creation\&.
.br
\fIbrigade_limit\fP If out's length would exceed this value, the appended buckets get written to a tempfile\&.
.br
\fIout\fP Resulting brigade\&.
.br
\fIin\fP Brigade to append\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
Error status code resulting from either apr_brigade_length(), \fBapreq_file_mktemp()\fP, \fBapreq_brigade_fwrite()\fP, or apr_file_seek()\&.
.RE
.PP
\fBTodo\fP
.RS 4
Flesh out these error codes, making them as explicit as possible\&.
.RE
.PP
.SS "static APR_INLINE apr_status_t apreq_brigade_copy (apr_bucket_brigade * d, apr_bucket_brigade * s)\fC [static]\fP"
Copy a brigade\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP (destination) Copied buckets are appended to this brigade\&.
.br
\fIs\fP (source) Brigade to copy from\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
Error status code from an unsuccessful apr_bucket_copy()\&.
.RE
.PP
\fBRemarks\fP
.RS 4
s == d produces Undefined Behavior\&.
.RE
.PP
.SS "apr_status_t apreq_brigade_fwrite (apr_file_t * f, apr_off_t * wlen, apr_bucket_brigade * bb)"
Writes brigade to a file\&.
.PP
\fBParameters\fP
.RS 4
\fIf\fP File that gets the brigade\&.
.br
\fIwlen\fP On a successful return, wlen holds the length of the brigade, which is the amount of data written to the file\&.
.br
\fIbb\fP Bucket brigade\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
Error status code from either an unsuccessful apr_bucket_read(), or a failed apr_file_writev()\&.
.RE
.PP
\fBRemarks\fP
.RS 4
This function leaks a bucket brigade into bb->p whenever the final bucket in bb is a spool bucket\&.
.RE
.PP
.SS "static APR_INLINE void apreq_brigade_move (apr_bucket_brigade * d, apr_bucket_brigade * s, apr_bucket * e)\fC [static]\fP"
Move the front of a brigade\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP (destination) Append buckets to this brigade\&.
.br
\fIs\fP (source) Brigade to take buckets from\&.
.br
\fIe\fP First bucket of s after the move\&. All buckets before e are appended to d\&.
.RE
.PP
\fBRemarks\fP
.RS 4
This moves all buckets when e == APR_BRIGADE_SENTINEL(s)\&.
.RE
.PP
.SS "static APR_INLINE apr_status_t apreq_brigade_setaside (apr_bucket_brigade * bb, apr_pool_t * p)\fC [static]\fP"
Set aside all buckets in the brigade\&.
.PP
\fBParameters\fP
.RS 4
\fIbb\fP Brigade\&.
.br
\fIp\fP Setaside buckets into this pool\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
Error status code from an unsuccessful apr_bucket_setaside()\&.
.RE
.PP
.SS "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)\&.
.PP
\fBParameters\fP
.RS 4
\fIbb\fP the bucket brigade
.RE
.PP
\fBReturns\fP
.RS 4
the spool file, or NULL\&.
.RE
.PP
.SS "\fBapreq_charset_t\fP apreq_charset_divine (const char * src, apr_size_t slen)"
Heuristically determine the charset of a string\&.
.PP
\fBParameters\fP
.RS 4
\fIsrc\fP String to scan\&.
.br
\fIslen\fP Length of string\&.
.RE
.PP
\fBReturns\fP
.RS 4
APREQ_CHARSET_ASCII if the string contains only 7-bit chars;
.PP
APREQ_CHARSET_UTF8 if the string is a valid utf8 byte sequence;
.PP
APREQ_CHARSET_LATIN1 if the string has no control chars;
.PP
APREQ_CHARSET_CP1252 if the string has control chars\&.
.RE
.PP
.SS "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'\&.
.PP
\fBParameters\fP
.RS 4
\fIdest\fP Location of utf8-encoded result string\&. Caller must ensure it is large enough to hold the encoded string and trailing '\\0'\&.
.br
\fIsrc\fP Original string\&.
.br
\fIslen\fP Length of original string\&.
.RE
.PP
\fBReturns\fP
.RS 4
length of utf8-encoded string in dest; does not exceed 3 * slen\&.
.RE
.PP
.SS "apr_status_t apreq_decode (char * dest, apr_size_t * dlen, const char * src, apr_size_t slen)"
Url-decodes a string\&.
.PP
\fBParameters\fP
.RS 4
\fIdest\fP Location of url-encoded result string\&. Caller must ensure dest is large enough to hold the encoded string and trailing null character\&.
.br
\fIdlen\fP points to resultant length of url-decoded string in dest
.br
\fIsrc\fP Original string\&.
.br
\fIslen\fP Length of original string\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
APR_INCOMPLETE if the string ends in the middle of an escape sequence\&.
.PP
\fBAPREQ_ERROR_BADSEQ\fP or \fBAPREQ_ERROR_BADCHAR\fP on malformed input\&.
.RE
.PP
\fBRemarks\fP
.RS 4
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\&.
.RE
.PP
.SS "apr_status_t apreq_decodev (char * dest, apr_size_t * dlen, struct iovec * v, int nelts)"
Url-decodes an iovec array\&.
.PP
\fBParameters\fP
.RS 4
\fIdest\fP Location of url-encoded result string\&. Caller must ensure dest is large enough to hold the encoded string and trailing null character\&.
.br
\fIdlen\fP Resultant length of dest\&.
.br
\fIv\fP Array of iovecs that represent the source string
.br
\fInelts\fP Number of iovecs in the array\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
APR_INCOMPLETE if the iovec ends in the middle of an escape sequence\&.
.PP
\fBAPREQ_ERROR_BADSEQ\fP or \fBAPREQ_ERROR_BADCHAR\fP on malformed input\&.
.RE
.PP
\fBRemarks\fP
.RS 4
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\&.
.RE
.PP
.SS "apr_size_t apreq_encode (char * dest, const char * src, const apr_size_t slen)"
Url-encodes a string\&.
.PP
\fBParameters\fP
.RS 4
\fIdest\fP Location of url-encoded result string\&. Caller must ensure it is large enough to hold the encoded string and trailing '\\0'\&.
.br
\fIsrc\fP Original string\&.
.br
\fIslen\fP Length of original string\&.
.RE
.PP
\fBReturns\fP
.RS 4
length of url-encoded string in dest; does not exceed 3 * slen\&.
.RE
.PP
.SS "static APR_INLINE char* apreq_escape (apr_pool_t * p, const char * src, const apr_size_t slen)\fC [static]\fP"
Returns an url-encoded copy of a string\&.
.PP
\fBParameters\fP
.RS 4
\fIp\fP Pool used to allocate the return value\&.
.br
\fIsrc\fP Original string\&.
.br
\fIslen\fP Length of original string\&.
.RE
.PP
\fBReturns\fP
.RS 4
The url-encoded string\&.
.RE
.PP
\fBRemarks\fP
.RS 4
Use this function insead of apreq_encode if its caller might otherwise overflow dest\&.
.RE
.PP
.SS "apr_status_t apreq_file_mktemp (apr_file_t ** fp, apr_pool_t * pool, const char * path)"
Makes a temporary file\&.
.PP
\fBParameters\fP
.RS 4
\fIfp\fP Points to the temporary apr_file_t on success\&.
.br
\fIpool\fP Pool to associate with the temp file\&. When the pool is destroyed, the temp file will be closed and deleted\&.
.br
\fIpath\fP 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\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
Error status code from unsuccessful apr_filepath_merge(), or a failed apr_file_mktemp()\&.
.RE
.PP
.SS "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\&.
.PP
\fBParameters\fP
.RS 4
\fIhdr\fP Header string to scan\&.
.br
\fIname\fP Name of attribute to search for\&.
.br
\fInlen\fP Length of name\&.
.br
\fIval\fP Location of (first) matching value\&.
.br
\fIvlen\fP Length of matching value\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS\&.
.PP
\fBAPREQ_ERROR_NOATTR\fP if the attribute is not found\&.
.PP
\fBAPREQ_ERROR_BADSEQ\fP if an unpaired quote mark was detected\&.
.RE
.PP
.SS "apr_ssize_t apreq_index (const char * hay, apr_size_t hlen, const char * ndl, apr_size_t nlen, const \fBapreq_match_t\fP type)"
Returns offset of match string's location, or -1 if no match is found\&.
.PP
\fBParameters\fP
.RS 4
\fIhay\fP Location of bytes to scan\&.
.br
\fIhlen\fP Number of bytes available for scanning\&.
.br
\fIndl\fP Search string
.br
\fInlen\fP Length of search string\&.
.br
\fItype\fP Match type\&.
.RE
.PP
\fBReturns\fP
.RS 4
Offset of match string, or -1 if no match is found\&.
.RE
.PP
.SS "char* apreq_join (apr_pool_t * p, const char * sep, const apr_array_header_t * arr, \fBapreq_join_t\fP mode)"
Join an array of values\&. The result is an empty string if there are no values\&.
.PP
\fBParameters\fP
.RS 4
\fIp\fP Pool to allocate return value\&.
.br
\fIsep\fP String that is inserted between the joined values\&.
.br
\fIarr\fP Array of \fBapreq_value_t\fP entries\&.
.br
\fImode\fP Join type- see apreq_join_t\&.
.RE
.PP
\fBReturns\fP
.RS 4
Joined string, or NULL on error
.RE
.PP
.SS "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 ('\\')\&.
.PP
\fBParameters\fP
.RS 4
\fIdest\fP Location of quoted copy\&. Must be large enough to hold the copy and trailing null byte\&.
.br
\fIsrc\fP Original string\&.
.br
\fIslen\fP Length of original string\&.
.br
\fIdest\fP Destination string\&.
.RE
.PP
\fBReturns\fP
.RS 4
length of quoted copy in dest\&.
.RE
.PP
.SS "apr_size_t apreq_quote_once (char * dest, const char * src, const apr_size_t slen)"
Same as \fBapreq_quote()\fP except when src begins and ends in quote marks\&. In that case it assumes src is quoted correctly, and just copies src to dest\&.
.PP
\fBParameters\fP
.RS 4
\fIdest\fP Location of quoted copy\&. Must be large enough to hold the copy and trailing null byte\&.
.br
\fIsrc\fP Original string\&.
.br
\fIslen\fP Length of original string\&.
.br
\fIdest\fP Destination string\&.
.RE
.PP
\fBReturns\fP
.RS 4
length of quoted copy in dest\&.
.RE
.PP
.SS "static APR_INLINE apr_ssize_t apreq_unescape (char * str)\fC [static]\fP"
An \fIin-situ\fP url-decoder\&.
.PP
\fBParameters\fP
.RS 4
\fIstr\fP The string to decode
.RE
.PP
\fBReturns\fP
.RS 4
Length of decoded string, or < 0 on error\&.
.RE
.PP
.SH "Author"
.PP
Generated automatically by Doxygen for libapreq2 from the source code\&.