ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2020 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\"
5
.\" Permission to use, copy, modify, and distribute this software for any
6
.\" purpose with or without fee is hereby granted, provided that the above
7
.\" copyright notice and this permission notice appear in all copies.
8
.\"
9
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
.\"
17
.Dd $Mdocdate$
18
.Dt KHTML_ATTR 3
19
.Os
20
.Sh NAME
21
.Nm khtml_attr ,
22
.Nm khtml_attrx
23
.Nd open an element scope for kcgihtml
24
.Sh LIBRARY
25
.Lb libkcgihtml
26
.Sh SYNOPSIS
27
.In sys/types.h
28
.In stdarg.h
29
.In stdint.h
30
.In kcgi.h
31
.In kcgihtml.h
32
.Ft enum kcgi_err
33
.Fo khtml_attr
34
.Fa "struct khtmlreq *req"
35
.Fa "enum kelem elem"
36
.Fa "..."
37
.Fc
38
.Ft enum kcgi_err
39
.Fo khtml_attrx
40
.Fa "struct khtmlreq *req"
41
.Fa "enum kelem elem"
42
.Fa "..."
43
.Fc
44
.Sh DESCRIPTION
45
Open a new scope of element
46
.Fa elem
47
on the current element stack of
48
.Fa req ,
49
initialised with
50
.Xr khtml_open 3 .
51
Scopes are closed with
52
.Xr khtml_closeelem 3 ,
53
.Xr khtml_closeto 3 ,
54
or
55
.Xr khtml_close 3 .
56
If
57
.Fa elem
58
is a
59
.Qq void
60
eleemnt
61
.Pq self-closing, like Dv KELEM_LINK
62
or
63
.Dv KELEM_DOCTYPE ,
64
the scope is immediately closed so no new scope is opened.
65
.Pp
66
For
67
.Fn khtml_attr ,
68
variable arguments are in pairs, with the first of a pair being a
69
.Vt "enum attr"
70
of the attribute type and the second being a
71
.Pf non- Dv NULL
72
string.
73
.Pp
74
For
75
.Fn khtml_attrx ,
76
variable arguments are in triplets: the first is a
77
.Vt "enum attr"
78
of the attribute type, the second is a
79
.Vt "enum attrx"
80
describing the data format of the third type, and the third type is
81
either an
82
.Vt int64_t ,
83
.Vt char * ,
84
or
85
.Vt double
86
for
87
.Dv KATTRX_INT ,
88
.Dv KATTRX_STRING ,
89
or
90
.Dv KATTRX_DOUBLE ,
91
respectively.
92
.Pp
93
In both cases, string content is HTML escaped, for example, the
94
double-quote character is rendered as
95
.Qq &quot; .
96
This prevents arguments from
97
.Qq breaking
98
the attribute string context.
99
.Pp
100
The variable arguments terminated with a singular
101
.Dv KATTR__MAX .
102
.Sh RETURN VALUES
103
Returns an
104
.Ft enum kcgi_err
105
indicating the error state.
106
.Bl -tag -width -Ds
107
.It Dv KCGI_OK
108
Success (not an error).
109
.It Dv KCGI_ENOMEM
110
Internal memory allocation failure, including reaching the maximum
111
number of possible HTML scopes.
112
.It Dv KCGI_HUP
113
The output connection has been terminated.
114
For FastCGI connections, the current connection should be released with
115
.Xr khttp_free 3
116
and parse loop reentered.
117
.It Dv KCGI_FORM
118
The connection is still expecting headers with
119
.Xr khttp_head 3 .
120
Indicates that
121
.Xr khttp_body 3
122
did not return with success or was not invoked.
123
For FastCGI connections, the current connection should be released with
124
.Xr khttp_free 3
125
and parse loop reentered.
126
.It Dv KCGI_SYSTEM
127
Internal system error writing to the output stream.
128
.El
129
.Sh EXAMPLES
130
The following outputs a simple HTML page.
131
It assumes
132
.Va r
133
is a
134
.Vt struct kreq
135
pointer.
136
For brevity, it does not do any error checking.
137
.Bd -literal -offset indent
138
khttp_head(r, kresps[KRESP_STATUS],
139
  "%s", khttps[KHTTP_200]);
140
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
141
  "%s", kmimetypes[KMIME_TEXT_HTML]);
142
khttp_body(r);
143
khtml_open(&req, r, 0);
144
khtml_elem(&req, KELEM_DOCTYPE);
145
khtml_elem(&req, KELEM_HTML);
146
khtml_elem(&req, KELEM_HEAD);
147
khtml_attr(req, KELEM_META,
148
  KATTR_CHARSET, "utf-8", KATTR__MAX);
149
khtml_attrx(req, KELEM_LINK,
150
  KATTR_REL, KATTRX_STRING, "stylesheet",
151
  KATTR_HREF, KATTRX_STRING, "style.css",
152
  KATTR__MAX);
153
khtml_close(&req);
154
.Ed
155
.Pp
156
The latter invocation could just as easily use
157
.Fn khtml_attr .
158
.Sh SEE ALSO
159
.Xr kcgihtml 3
160
.Sh STANDARDS
161
The referenced HTML5 standard is
162
.Lk https://www.w3.org/TR/html52 HTML5.2 .
163
.Sh AUTHORS
164
Written by
165
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
166