diff options
Diffstat (limited to 'man3/nxt_unit_response_buf_alloc.3')
| -rw-r--r-- | man3/nxt_unit_response_buf_alloc.3 | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/man3/nxt_unit_response_buf_alloc.3 b/man3/nxt_unit_response_buf_alloc.3 new file mode 100644 index 000000000..2a429b270 --- /dev/null +++ b/man3/nxt_unit_response_buf_alloc.3 @@ -0,0 +1,194 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_response_buf_alloc 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_response_buf_alloc, +nxt_unit_buf_send +\- +allocate buffer for response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include <nxt_unit.h> +.PP +.B [[gnu::malloc(nxt_unit_buf_send)]] +.B nxt_unit_buf_t *_Nullable +.BI "nxt_unit_response_buf_alloc(nxt_unit_request_info_t *" req ", uint32_t " size ); +.PP +.BI "int nxt_unit_buf_send(nxt_unit_buf_t *" buf ); +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I size +Size of the buffer. +.TP +.I buf +Buffer. +.SH Description +.MR nxt_unit_response_buf_alloc 3 +allocates a buffer for a response to a request, +or for a chunk of it. +.PP +.MR nxt_unit_buf_send 3 +sends and deallocates the buffer previously allocated with +.MR nxt_unit_response_buf_alloc 3 . +.SH Return value +.TP +.MR nxt_unit_response_buf_alloc 3 +A pointer to the allocated buffer on success, +or NULL on error. +.TP +.MR nxt_unit_buf_send 3 +0 on success, +or a non-zero error code on error. +.SH Errors +Errors will be reported in the Unit debug log. +.TP +.B NXT_UNIT_ERROR +.RS +.PD 0 +.IP \[bu] 3 +.I size +was too big. +.IP \[bu] +Allocation failed. +.IP \[bu] +Failed to share the buffer with +.MR unitd 8 . +.PD +.RE +.SH Examples +Below is a request and response pair, +and the source code to produce it. +.PP +See +.MR nxt_unit_init 3 +for an example where the +.IR request_handler () +function defined below is used. +.SS Request +.EX +.RB $ " echo \-e \[aq]GET / HTTP/1.1\er\enHost: _\en\[aq] | ncat localhost 80;" +HTTP/1.1 200 OK +Content\-Type: text/plain +Server: Unit/1.30.0 +Date: Sat, 20 May 2023 19:08:22 GMT +Transfer\-Encoding: chunked +\& +22 +Hello world! +But send this first. +\& +15 +Some extra contents. +\& +e +And some more +\& +0 +\& +.EE +.SS C code +.EX +#define _GNU_SOURCE +#include <string.h> +\& +#include <nxt_unit.h> +\& +void +request_handler(nxt_unit_request_info_t *req) +{ + int rc; + nxt_unit_buf_t *buf, *buf2; +\& + rc = nxt_unit_response_init(req, 200, 1, strlen("Content\-Type") + + strlen("text/plain") + + strlen("Hello world!\en")); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_response_add_field(req, "Content\-Type", + strlen("Content\-Type"), + "text/plain", + strlen("text/plain")); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_response_add_content(req, "Hello world!\en", + strlen("Hello world!\en")); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_response_send(req); + if (rc != 0) { + goto fail; + } +\& + buf = nxt_unit_response_buf_alloc(req, + strlen("Some extra contents.\en")); + if (buf == NULL) { + rc = NXT_UNIT_ERROR; + goto fail; + } +\& + buf2 = nxt_unit_response_buf_alloc(req, + strlen("But send this first.\en")); + if (buf2 == NULL) { + rc = NXT_UNIT_ERROR; + goto fail; + } +\& + buf2\->free = mempcpy(buf2\->free, "But send this first.\en", + strlen("But send this first.\en")); + buf\->free = mempcpy(buf\->free, "Some extra contents.\en", + strlen("Some extra contents.\en")); +\& + rc = nxt_unit_buf_send(buf2); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_buf_send(buf); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_response_write(req, "And some more\en", + strlen("And some more\en")); + if (rc != 0) { + goto fail; + } +\& +fail: + nxt_unit_request_done(req, rc); +} +.EE +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR nxt_unit_init 3 , +.MR nxt_unit_response_init 3 , +.MR nxt_unit_response_write 3 , +.MR unitd 8 +.PP +.UR https://unit.nginx.org +Website +.UE +.PP +.UR https://mailman.nginx.org/mailman/listinfo/unit +Mailing list +.UE +.PP +.UR https://github.com/nginx/unit +GitHub +.UE |