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_PUTDOUBLE 3
19
.Os
20
.Sh NAME
21
.Nm kjson_putdouble ,
22
.Nm kjson_putdoublep ,
23
.Nm kjson_string_putdouble
24
.Nd put floating point content for kcgijson
25
.Sh LIBRARY
26
.Lb libkcgijson
27
.Sh SYNOPSIS
28
.In sys/types.h
29
.In stdarg.h
30
.In stdint.h
31
.In kcgi.h
32
.In kcgijson.h
33
.Ft enum kcgi_err
34
.Fo kjson_putdouble
35
.Fa "struct kjsonreq *req"
36
.Fa "double v"
37
.Fc
38
.Ft enum kcgi_err
39
.Fo kjson_putdoublep
40
.Fa "struct kjsonreq *req"
41
.Fa "const char *name"
42
.Fa "double v"
43
.Fc
44
.Ft enum kcgi_err
45
.Fo kjson_string_putdouble
46
.Fa "struct kjsonreq *req"
47
.Fa "double v"
48
.Fc
49
.Sh DESCRIPTION
50
Write a double-precision floating point
51
.Fa v
52
to a context
53
.Fa req
54
initialised with
55
.Xr khtml_open 3 .
56
This formats the value using the
57
.Qq g
58
format character of
59
.Xr printf 3 .
60
If
61
.Fa v
62
does not classify as normal, subnormal, or zero, it is output as
63
.Dv null .
64
.Pp
65
The
66
.Fn kjson_putdouble
67
form is for array scopes,
68
.Fn kjson_putdoublep
69
is for objects, and
70
.Fn kjson_string_putdouble
71
for open strings.
72
.Pp
73
Passing a
74
.Dv NULL
75
value to
76
.Fa name
77
for
78
.Fn kjson_putdoublep ,
79
is equivalent to calling
80
.Fn kjson_putdouble .
81
.Sh RETURN VALUES
82
Returns an
83
.Ft enum kcgi_err
84
indicating the error state.
85
.Bl -tag -width -Ds
86
.It Dv KCGI_OK
87
Success (not an error).
88
.It Dv KCGI_ENOMEM
89
Internal memory allocation failure.
90
.It Dv KCGI_HUP
91
The output connection has been terminated.
92
For FastCGI connections, the current connection should be released with
93
.Xr khttp_free 3
94
and parse loop reentered.
95
.It Dv KCGI_FORM
96
The connection is still expecting headers with
97
.Xr khttp_head 3 .
98
Indicates that
99
.Xr khttp_body 3
100
did not return with success or was not invoked.
101
For FastCGI connections, the current connection should be released with
102
.Xr khttp_free 3
103
and parse loop reentered.
104
.It Dv KCGI_SYSTEM
105
Internal system error writing to the output stream.
106
.It Dv KCGI_WRITER
107
The incorrect form was used for the current scope, for example, an
108
array-type write within an object.
109
.El
110
.Sh EXAMPLES
111
The following outputs a simple JSON document.
112
It assumes
113
.Va r
114
is a
115
.Vt struct kreq
116
pointer.
117
For brevity, it does not do any error checking.
118
.Bd -literal -offset indent
119
khttp_head(r, kresps[KRESP_STATUS],
120
  "%s", khttps[KHTTP_200]);
121
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
122
  "%s", kmimetypes[KMIME_APP_JSON]);
123
khttp_body(r);
124
kjson_open(&req, r);
125
kjson_obj_open(&req);
126
kjson_putdoublep(&req, "bar", 0.12345);
127
kjson_arrayp_open(&req, "baz");
128
kjson_putdouble(&req, (1.0 / 0.0)); /* null */
129
kjson_close(&req);
130
.Ed
131
.Sh SEE ALSO
132
.Xr kcgijson 3
133
.Sh AUTHORS
134
Written by
135
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
136