KHTTP_URLPART(3)

NAME
khttp_urlpart, khttp_urlpartx, khttp_vurlpart, khttp_vurlpartx - URL formatting for kcgi

LIBRARY
libkcgi

SYNOPSIS
#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
char *
khttp_urlpart(const char *path, const char *suffix, const char *page, ...);
char *
khttp_urlpartx(const char *path, const char *suffix, const char *page, ...);
char *
khttp_vurlpart(const char *path, const char *suffix, const char *page, va_list ap);
char *
khttp_vurlpartx(const char *path, const char *suffix, const char *page, va_list ap);

DESCRIPTION
Format a URL given the components following the domain. If the variable arguments are provided, append them as query string pairs.

    path/page.suffix
    path/page.suffix?key=val...

If path is NULL, the URL will be relative to page; otherwise, path will be followed by a path separator. An empty path signifies the root directory.

If the suffix is NULL or empty, or the corresponding page is NULL or empty, the URL is formatted without a suffix.

The variable key-value arguments must be terminated with NULL. khttp_urlpart() and khttp_vurlpart() accept pairs of variable arguments, the first being the query string key, the second being the value. Both are char *. A NULL query string value is rendered as an empty string. khttp_urlpartx() and khttp_vurlpartx() accept triplets. 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 (where a NULL query string value is rendered as an empty 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 khttp_urlpart().

The page, query string keys, and query string values are URL-encoded, but the path and the suffix are not.

There are two deprecated forms of these functions: kutil_urlpart() and kutil_urlpartx(). These should no longer be used.

RETURN VALUES
Return newly-allocated strings that must be freed with free(3) or NULL if allocation fails.

EXAMPLES
The following creates a relative URL with path, page, suffix, and query string parts.

    url = khttp_urlpart("/path", "html", "page",
    	 "foo", "bar", "baz", "xyzzy", NULL);

This will assign the following URL:

    /path/page.html?foo=bar&baz=xyzzy

For typed arguments, the extended form may be used. Integer and real literals must have the int64_t and double types, respectively.

    url = khttp_urlpartx("/path", "html", "page",
    	 "foo", KATTRX_INT, (int64_t)0, NULL);

This assigns the following

    /path/page.html?foo=0

These may be made relative to the current page by omitting the leading slash or passing NULL for the path component entirely, such as:

    url1 = khttp_urlpart("rel/path", "html", "page", NULL);
    url2 = khttp_urlpart(NULL, "html", "page", NULL);

These assign the following, respectively:

    rel/path/page.html
    page.html

Lastly, pages and their suffixes may be omitted entirely:

    url3 = khttp_urlpart("", "", "", "foo", "bar", NULL);
    url4 = khttp_urlpart(NULL, "", "", "foo", "bar", NULL);

These assign the following:

    /?foo=bar
    ?foo=bar

AUTHORS
Written by Kristaps Dzonsons <kristaps@bsd.lv>.