KUTIL_URLENCODE(3)

NAME
kutil_urlabs, kutil_urlpart, kutil_urlpartx, kutil_urlencode, kutil_urldecode, kutil_urldecode_inplace - URL formatting for kcgi

LIBRARY
libkcgi

SYNOPSIS
#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
char *
kutil_urlabs(enum kscheme scheme, const char *host, uint16_t port, const char *path);
char *
kutil_urlpart(struct kreq *req, const char *path, const char *suffix, const char *page, ...);
char *
kutil_urlpartx(struct kreq *req, const char *path, const char *suffix, const char *page, ...);
char *
kutil_urlencode(const char *cp);
enum kcgi_err
kutil_urldecode(const char *src, char **dst);
enum kcgi_err
kutil_urldecode_inplace(char *cp);

DESCRIPTION
These functions format or manipulate various parts of a URL.

The kutil_urlpart() and kutil_urlpartx() functions format the path/page.suffix part of an HTTP URL, appending a variable number of query string key-value pairs. If page is NULL, these return NULL. If path is NULL, the URL will be relative to page; otherwise, path will be followed by a path separator. The last argument must be NULL. If the suffix is NULL, it is omitted from the URL. The page, the keys, and the values are URL-encoded, but the path and the suffix are not.

kutil_urlpart() accepts a variable number of pairs of char * arguments. In each pair, the first argument is the key and the second one the corresponding value.

kutil_urlpartx() accepts a variable number of groups of three arguments each. In each group, the first argument is a char * giving the key. The second argument is an enum kattrx specifying the type of the third argument: KATTRX_STRING followed by a char * string, KATTRX_INT followed by an int64_t signed integer, or KATTRX_DOUBLE followed by a double floating-point number. If all types are KATTRX_STRING, the invocation can be shortened to kutil_urlpart().

The kutil_urlencode() function encodes a string for embedding in a URL.

The kutil_urldecode() function decodes the given string src and stores the result in the allocated string dst. If the return code is not KCGI_OK, the result is set to NULL.

The kutil_urldecode_inplace() function decodes the given string in-place. If the string is malformed, the string may be only partially decoded.

The kutil_urlabs() function assembles the URL schema://host:portpath. Unless the path is an empty string, it needs to begin with a slash. None of this is URL-encoded, so make sure to use kutil_urlpart(), kutil_urlpartx(), or just kutil_urlencode() for the sensitive parts.

RETURN VALUES
The kutil_urlabs(), kutil_urlpart(), kutil_urlpartx() and kutil_urlencode() functions return newly-allocated strings that must be freed with free(3). They return NULL if allocation fails. The kutil_urlencode() function also returns NULL if cp is NULL.

Additionally the kutil_urldecode() and kutil_urldecode_inplace() functions return an error code:

KCGI_OK
    Success (not an error).

KCGI_ENOMEM
    Memory failure (only kutil_urldecode()).

KCGI_FORM
    Malformed or NULL input data.

AUTHORS
These functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.

BUGS
The kutil_urlabs() function accepts scheme arguments that aren't valid in URLs.

The req argument is not used and should be removed.