NAME
khttp_urlabs
,
khttp_vurlabs
—
URL formatting for kcgi
LIBRARY
library “libkcgi”
SYNOPSIS
#include
<sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
char *
khttp_urlabs
(enum kscheme
scheme, const char *host,
uint16_t port, const char *path,
...);
char *
khttp_vurlabs
(enum kscheme
scheme, const char *host,
uint16_t port, const char *path,
va_list ap);
DESCRIPTION
Format an absolute (full) URL. The host is in some standards called the "authority".
scheme://host:port/path?key=val
scheme://host:port/path
scheme:path
Passing a NULL
or empty
host will omit the "//",
host, port component.
If the host is non-empty and not
NULL
and the path is also
non-empty and not NULL
, the
path is prepended with a mandatory slash.
If the port is zero, it is omitted. The
port is only used if host is
non-empty and not NULL
.
The variable arguments are arranged in pairs terminated by a
single NULL
. The first of each pair is the query
string key, the second is the value. Both are char *.
A NULL
query string value is rendered as an empty
string.
Only the query string pairs are URL-encoded, so the caller must make sure that the characters in host and path are valid.
The deprecated form of these functions,
kutil_urlabs
(),
should no longer be used.
RETURN VALUES
Return newly-allocated strings that must be freed with
free(3) or
NULL
if allocation fails.
EXAMPLES
To print a full URL:
khttp_urlabs(KSCHEME_HTTPS, foo.com,
80, b, c, d, NULL);
This assigns https://foo.com:80/b?c=d
.
Setting the port to zero eliminates the port:
khttp_urlabs(KSCHEME_HTTPS, foo.com,
0, b, c, d, NULL);
This assigns https://foo.com/b?c=d
.
An empty path component ends with the domain (or query string).
khttp_urlabs(KSCHEME_HTTPS, foo.com,
0, , c, d, NULL);
This assigns https://foo.com?c=d
.
To use a host-less scheme, specify a NULL
or empty host:
khttp_urlabs(KSCHEME_MAILTO, NULL, 0,
k@b.com, NULL);
This assigns mailto:k@b.com
.
AUTHORS
Written by Kristaps Dzonsons <kristaps@bsd.lv>.
CAVEATS
These functions can currently be used to create semantically
invalid URLs such as https:?foo=bar
by omitting
components required for the scheme. Semantically-correct URLs are the
responsibility of the caller. This behaviour may be verified for correctness
in later versions of the software.