KHTTP_URLABS(3) Library Functions Manual KHTTP_URLABS(3)

NAME

khttp_urlabs, khttp_vurlabsURL 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.
April 10, 2020 OpenBSD 6.7