kcgi/man/kjson_putint.3

.\"	$Id$
.\"
.\" Copyright (c) 2020 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt KJSON_PUTINT 3
.Os
.Sh NAME
.Nm kjson_putint ,
.Nm kjson_putintp ,
.Nm kjson_putintstr ,
.Nm kjson_putintstrp ,
.Nm kjson_string_putint
.Nd put integer content for kcgijson
.Sh LIBRARY
.Lb libkcgijson
.Sh SYNOPSIS
.In sys/types.h
.In stdarg.h
.In stdint.h
.In kcgi.h
.In kcgijson.h
.Ft enum kcgi_err
.Fo kjson_putint
.Fa "struct kjsonreq *req"
.Fa "int64_t v"
.Fc
.Ft enum kcgi_err
.Fo kjson_putintp
.Fa "struct kjsonreq *req"
.Fa "const char *name"
.Fa "int64_t v"
.Fc
.Ft enum kcgi_err
.Fo kjson_string_putint
.Fa "struct kjsonreq *req"
.Fa "int64_t v"
.Fc
.Ft enum kcgi_err
.Fo kjson_putintstr
.Fa "struct kjsonreq *r"
.Fa "int64_t v"
.Fc
.Ft enum kcgi_err
.Fo kjson_putintstrp
.Fa "struct kjsonreq *r"
.Fa "const char *name"
.Fa "int64_t v"
.Fc
.Sh DESCRIPTION
Write a 64-bit integer
.Fa v
to a context
.Fa req
initialised with
.Xr khtml_open 3 .
This formats the value as
.Li [-]?[0-9]+ .
.Pp
The
.Fn kjson_putint
and
.Fn kjson_putintstr
forms are for array scopes,
.Fn kjson_putintp
and
.Fn kjson_putintstrp
for objects, and
.Fn kjson_string_putint
for open strings.
.Pp
Since JavaScript is limited to 53 bits, it's possible that integers may
be truncated with
.Fn kjson_putint
and family.
The alternative forms,
.Fn kjson_putintstr
and
.Fn kjson_putintstrp ,
emit the value within a string.
This allows the JavaScript to parse the integer and handle overflow and
underflow explicitly.
.Pp
Passing a
.Dv NULL
value to
.Fa name
for
.Fn kjson_putintp
or
.Fn kjson_putintstrp
is equivalent to calling
.Fn kjson_putint
or
.Fn kjson_putintstr ,
respectively.
.Sh RETURN VALUES
Returns an
.Ft enum kcgi_err
indicating the error state.
.Bl -tag -width -Ds
.It Dv KCGI_OK
Success (not an error).
.It Dv KCGI_ENOMEM
Internal memory allocation failure.
.It Dv KCGI_HUP
The output connection has been terminated.
For FastCGI connections, the current connection should be released with
.Xr khttp_free 3
and parse loop reentered.
.It Dv KCGI_FORM
The connection is still expecting headers with
.Xr khttp_head 3 .
Indicates that
.Xr khttp_body 3
did not return with success or was not invoked.
For FastCGI connections, the current connection should be released with
.Xr khttp_free 3
and parse loop reentered.
.It Dv KCGI_SYSTEM
Internal system error writing to the output stream.
.It Dv KCGI_WRITER
The incorrect form was used for the current scope, for example, an
array-type write within an object.
.El
.Sh EXAMPLES
The following outputs a simple JSON document.
It assumes
.Va r
is a
.Vt struct kreq
pointer.
For brevity, it does not do any error checking.
.Bd -literal -offset indent
khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_APP_JSON]);
khttp_body(r);
kjson_open(&req, r);
kjson_obj_open(&req);
kjson_putintp(&req, "bar", 12345);
kjson_arrayp_open(&req, "baz");
kjson_putint(&req, 1)); /* 1 */
kjson_putintstr(&req, 1)); /* "1" */
kjson_close(&req);
.Ed
.Sh SEE ALSO
.Xr kcgijson 3
.Sh AUTHORS
Written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .