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 KJSON_PUTINT 3
19
.Os
20
.Sh NAME
21
.Nm kjson_putint ,
22
.Nm kjson_putintp ,
23
.Nm kjson_putintstr ,
24
.Nm kjson_putintstrp ,
25
.Nm kjson_string_putint
26
.Nd put integer content for kcgijson
27
.Sh LIBRARY
28
.Lb libkcgijson
29
.Sh SYNOPSIS
30
.In sys/types.h
31
.In stdarg.h
32
.In stdint.h
33
.In kcgi.h
34
.In kcgijson.h
35
.Ft enum kcgi_err
36
.Fo kjson_putint
37
.Fa "struct kjsonreq *req"
38
.Fa "int64_t v"
39
.Fc
40
.Ft enum kcgi_err
41
.Fo kjson_putintp
42
.Fa "struct kjsonreq *req"
43
.Fa "const char *name"
44
.Fa "int64_t v"
45
.Fc
46
.Ft enum kcgi_err
47
.Fo kjson_string_putint
48
.Fa "struct kjsonreq *req"
49
.Fa "int64_t v"
50
.Fc
51
.Ft enum kcgi_err
52
.Fo kjson_putintstr
53
.Fa "struct kjsonreq *r"
54
.Fa "int64_t v"
55
.Fc
56
.Ft enum kcgi_err
57
.Fo kjson_putintstrp
58
.Fa "struct kjsonreq *r"
59
.Fa "const char *name"
60
.Fa "int64_t v"
61
.Fc
62
.Sh DESCRIPTION
63
Write a 64-bit integer
64
.Fa v
65
to a context
66
.Fa req
67
initialised with
68
.Xr khtml_open 3 .
69
This formats the value as
70
.Li [-]?[0-9]+ .
71
.Pp
72
The
73
.Fn kjson_putint
74
and
75
.Fn kjson_putintstr
76
forms are for array scopes,
77
.Fn kjson_putintp
78
and
79
.Fn kjson_putintstrp
80
for objects, and
81
.Fn kjson_string_putint
82
for open strings.
83
.Pp
84
Since JavaScript is limited to 53 bits, it's possible that integers may
85
be truncated with
86
.Fn kjson_putint
87
and family.
88
The alternative forms,
89
.Fn kjson_putintstr
90
and
91
.Fn kjson_putintstrp ,
92
emit the value within a string.
93
This allows the JavaScript to parse the integer and handle overflow and
94
underflow explicitly.
95
.Pp
96
Passing a
97
.Dv NULL
98
value to
99
.Fa name
100
for
101
.Fn kjson_putintp
102
or
103
.Fn kjson_putintstrp
104
is equivalent to calling
105
.Fn kjson_putint
106
or
107
.Fn kjson_putintstr ,
108
respectively.
109
.Sh RETURN VALUES
110
Returns an
111
.Ft enum kcgi_err
112
indicating the error state.
113
.Bl -tag -width -Ds
114
.It Dv KCGI_OK
115
Success (not an error).
116
.It Dv KCGI_ENOMEM
117
Internal memory allocation failure.
118
.It Dv KCGI_HUP
119
The output connection has been terminated.
120
For FastCGI connections, the current connection should be released with
121
.Xr khttp_free 3
122
and parse loop reentered.
123
.It Dv KCGI_FORM
124
The connection is still expecting headers with
125
.Xr khttp_head 3 .
126
Indicates that
127
.Xr khttp_body 3
128
did not return with success or was not invoked.
129
For FastCGI connections, the current connection should be released with
130
.Xr khttp_free 3
131
and parse loop reentered.
132
.It Dv KCGI_SYSTEM
133
Internal system error writing to the output stream.
134
.It Dv KCGI_WRITER
135
The incorrect form was used for the current scope, for example, an
136
array-type write within an object.
137
.El
138
.Sh EXAMPLES
139
The following outputs a simple JSON document.
140
It assumes
141
.Va r
142
is a
143
.Vt struct kreq
144
pointer.
145
For brevity, it does not do any error checking.
146
.Bd -literal -offset indent
147
khttp_head(r, kresps[KRESP_STATUS],
148
  "%s", khttps[KHTTP_200]);
149
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
150
  "%s", kmimetypes[KMIME_APP_JSON]);
151
khttp_body(r);
152
kjson_open(&req, r);
153
kjson_obj_open(&req);
154
kjson_putintp(&req, "bar", 12345);
155
kjson_arrayp_open(&req, "baz");
156
kjson_putint(&req, 1)); /* 1 */
157
kjson_putintstr(&req, 1)); /* "1" */
158
kjson_close(&req);
159
.Ed
160
.Sh SEE ALSO
161
.Xr kcgijson 3
162
.Sh AUTHORS
163
Written by
164
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
165