ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2014, 2017 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
5
.\"
6
.\" Permission to use, copy, modify, and distribute this software for any
7
.\" purpose with or without fee is hereby granted, provided that the above
8
.\" copyright notice and this permission notice appear in all copies.
9
.\"
10
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17
.\"
18
.Dd $Mdocdate$
19
.Dt KHTTP_URLABS 3
20
.Os
21
.Sh NAME
22
.Nm khttp_urlabs ,
23
.Nm khttp_vurlabs
24
.Nd URL formatting for kcgi
25
.Sh LIBRARY
26
.Lb libkcgi
27
.Sh SYNOPSIS
28
.In sys/types.h
29
.In stdarg.h
30
.In stdint.h
31
.In kcgi.h
32
.Ft "char *"
33
.Fo khttp_urlabs
34
.Fa "enum kscheme scheme"
35
.Fa "const char *host"
36
.Fa "uint16_t port"
37
.Fa "const char *path"
38
.Fa "..."
39
.Fc
40
.Ft "char *"
41
.Fo khttp_vurlabs
42
.Fa "enum kscheme scheme"
43
.Fa "const char *host"
44
.Fa "uint16_t port"
45
.Fa "const char *path"
46
.Fa "va_list ap"
47
.Fc
48
.Sh DESCRIPTION
49
Format an absolute (full) URL.
50
The
51
.Fa host
52
is in some standards called the
53
.Qq authority .
54
.Pp
55
.Dl Fa scheme Ns :// Ns Fa host : Ns Fa port Ns / Ns Fa path Ns ?key=val
56
.Dl Fa scheme Ns :// Ns Fa host : Ns Fa port Ns / Ns Fa path
57
.Dl Fa scheme : Ns Fa path
58
.Pp
59
Passing a
60
.Dv NULL
61
or empty
62
.Fa host
63
will omit the
64
.Qq // ,
65
.Fa host ,
66
.Fa port
67
component.
68
.Pp
69
If the
70
.Fa host
71
is non-empty and not
72
.Dv NULL
73
and the
74
.Fa path
75
is also non-empty and not
76
.Dv NULL ,
77
the
78
.Fa path
79
is prepended with a mandatory slash.
80
.Pp
81
If the
82
.Fa port
83
is zero, it is omitted.
84
The
85
.Fa port
86
is only used if
87
.Fa host
88
is non-empty and not
89
.Dv NULL .
90
.Pp
91
The variable arguments are arranged in pairs terminated by a single
92
.Dv NULL .
93
The first of each pair is the query string key, the second is the value.
94
Both are
95
.Vt "char *" .
96
A
97
.Dv NULL
98
query string value is rendered as an empty string.
99
.Pp
100
Only the query string pairs are URL-encoded, so the caller must make
101
sure that the characters in
102
.Fa host
103
and
104
.Fa path
105
are valid.
106
.Pp
107
The deprecated form of these functions,
108
.Fn kutil_urlabs ,
109
should no longer be used.
110
.Sh RETURN VALUES
111
Return newly-allocated strings that must be freed with
112
.Xr free 3
113
or
114
.Dv NULL
115
if allocation fails.
116
.Sh EXAMPLES
117
To print a full URL:
118
.Pp
119
.Dl khttp_urlabs(KSCHEME_HTTPS, "foo.com", 80, "b", "c", "d", NULL);
120
.Pp
121
This assigns
122
.Li https://foo.com:80/b?c=d .
123
.Pp
124
Setting the port to zero eliminates the port:
125
.Pp
126
.Dl khttp_urlabs(KSCHEME_HTTPS, "foo.com", 0, "b", "c", "d", NULL);
127
.Pp
128
This assigns
129
.Li https://foo.com/b?c=d .
130
.Pp
131
An empty path component ends with the domain (or query string).
132
.Pp
133
.Dl khttp_urlabs(KSCHEME_HTTPS, "foo.com", 0, "", "c", "d", NULL);
134
.Pp
135
This assigns
136
.Li https://foo.com?c=d .
137
.Pp
138
To use a host-less scheme, specify a
139
.Dv NULL
140
or empty host:
141
.Pp
142
.Dl khttp_urlabs(KSCHEME_MAILTO, NULL, 0, "k@b.com", NULL);
143
.Pp
144
This assigns
145
.Li mailto:k@b.com .
146
.Sh AUTHORS
147
Written by
148
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
149
.Sh CAVEATS
150
These functions can currently be used to create semantically invalid
151
URLs such as
152
.Li https:?foo=bar
153
by omitting components required for the scheme.
154
Semantically-correct URLs are the responsibility of the caller.
155
This behaviour may be verified for correctness in later versions of the
156
software.
157