From 973d839386c4ee067be9af0276df2dcb397fb3dd Mon Sep 17 00:00:00 2001 From: Alejandro Colomar Date: Fri, 28 Apr 2023 22:23:39 +0200 Subject: man3/: Add pages Signed-off-by: Alejandro Colomar --- man3/nxt_unit_ctx_alloc.3 | 132 ++++++++++++++++++++++++ man3/nxt_unit_done.3 | 54 ++++++++++ man3/nxt_unit_init.3 | 166 ++++++++++++++++++++++++++++++ man3/nxt_unit_log.3 | 91 ++++++++++++++++ man3/nxt_unit_malloc.3 | 70 +++++++++++++ man3/nxt_unit_req_log.3 | 76 ++++++++++++++ man3/nxt_unit_request_read.3 | 142 +++++++++++++++++++++++++ man3/nxt_unit_response_add_content.3 | 91 ++++++++++++++++ man3/nxt_unit_response_add_field.3 | 162 +++++++++++++++++++++++++++++ man3/nxt_unit_response_buf_alloc.3 | 194 +++++++++++++++++++++++++++++++++++ man3/nxt_unit_response_init.3 | 85 +++++++++++++++ man3/nxt_unit_response_send.3 | 88 ++++++++++++++++ man3/nxt_unit_response_write.3 | 84 +++++++++++++++ man3/nxt_unit_run.3 | 98 ++++++++++++++++++ man3/nxt_unit_sptr_get.3 | 91 ++++++++++++++++ scripts/LinuxManBook/LMBfront.roff | 12 +-- 16 files changed, 1630 insertions(+), 6 deletions(-) create mode 100644 man3/nxt_unit_ctx_alloc.3 create mode 100644 man3/nxt_unit_done.3 create mode 100644 man3/nxt_unit_init.3 create mode 100644 man3/nxt_unit_log.3 create mode 100644 man3/nxt_unit_malloc.3 create mode 100644 man3/nxt_unit_req_log.3 create mode 100644 man3/nxt_unit_request_read.3 create mode 100644 man3/nxt_unit_response_add_content.3 create mode 100644 man3/nxt_unit_response_add_field.3 create mode 100644 man3/nxt_unit_response_buf_alloc.3 create mode 100644 man3/nxt_unit_response_init.3 create mode 100644 man3/nxt_unit_response_send.3 create mode 100644 man3/nxt_unit_response_write.3 create mode 100644 man3/nxt_unit_run.3 create mode 100644 man3/nxt_unit_sptr_get.3 diff --git a/man3/nxt_unit_ctx_alloc.3 b/man3/nxt_unit_ctx_alloc.3 new file mode 100644 index 000000000..d00db9e6d --- /dev/null +++ b/man3/nxt_unit_ctx_alloc.3 @@ -0,0 +1,132 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_ctx_alloc 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_ctx_alloc \- create context object for Unit app thread +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.B [[gnu::malloc(nxt_unit_done)]] +.BI "nxt_unit_ctx_t *_Nullable nxt_unit_ctx_alloc(nxt_unit_ctx_t *" ctx , +.BI " void *_Nullable " data ); +.fi +.SH Arguments +.TP +.I ctx +Main context object for the application. +It should have been created with +.MR nxt_unit_init 3 . +.TP +.I data +XXX +.SH Description +.MR nxt_unit_ctx_alloc 3 +creates a context object that will be used for a worker thread. +.PP +The next step after creating a thread context object +is running the application thread; +for that, see +.MR nxt_unit_run 3 . +.PP +The context object created by this function should be +destroyed by passing it to +.MR nxt_unit_done 3 . +.SH Return value +A pointer to a context object on success, +or NULL on error. +.SH Errors +Errors will be reported in the Unit debug log. +.IP \[bu] 3 +.MR pthread_mutex_init 3 +failed. +.PD 0 +.IP \[bu] +.MR socketpair 2 +failed. +.IP \[bu] +.MR setsockopt 2 +failed. +.IP \[bu] +.MR memfd_create 2 +failed. +.IP \[bu] +.MR shm_open 2 +failed. +.IP \[bu] +.MR ftruncate 2 +failed. +.IP \[bu] +.MR mmap 2 +failed. +.IP \[bu] +.MR sendmsg 2 +failed. +.IP \[bu] +.MR nxt_unit_malloc 3 +failed. +.IP \[bu] +.I nxt_unit_init_t::callbacks.port_send +failed. +.IP \[bu] +Internal hash table failure. +.PD +.SH Examples +See +.MR nxt_unit_init 3 +for an example where this +.IR worker () +function is used. +.PP +.EX +#include +#include +#include +\& +#include +\& +void * +worker(void *main_ctx) +{ + int rc; + nxt_unit_ctx_t *ctx; +\& + ctx = nxt_unit_ctx_alloc(main_ctx, NULL); + if (ctx == NULL) { + pthread_exit(NULL); + } +\& + nxt_unit_debug(ctx, "start worker"); + rc = nxt_unit_run(ctx); + nxt_unit_debug(ctx, "worker finished with %d code", rc); +\& + nxt_unit_done(ctx); +\& + pthread_exit((void *) (intptr_t) rc); +} +.EE +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR nxt_unit_done 3 , +.MR nxt_unit_run 3 , +.MR pthread_create 3 , +.MR pthread_exit 3 , +.MR unitd 8 +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/mailman/listinfo/unit +.UE +.PP +GitHub +.UR https://github.com/nginx/unit +.UE diff --git a/man3/nxt_unit_done.3 b/man3/nxt_unit_done.3 new file mode 100644 index 000000000..31fd1b620 --- /dev/null +++ b/man3/nxt_unit_done.3 @@ -0,0 +1,54 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_done 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_done \- destroy context object in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "void nxt_unit_done(nxt_unit_ctx_t *" ctx ); +.fi +.SH Arguments +.TP +.I ctx +Context object to be destroyed. +It should have been created with +.MR nxt_unit_init 3 +or +.MR nxt_unit_ctx_alloc 3 . +.SH Description +.MR nxt_unit_done 3 +destroys a context object in a Unit application. +.SH Return value +None. +.SH Errors +None. +.SH Examples +See +.MR nxt_unit_init 3 +and +.MR nxt_unit_ctx_alloc 3 . +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR nxt_unit_ctx_alloc 3 , +.MR nxt_unit_init 3 , +.MR unitd 8 +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/mailman/listinfo/unit +.UE +.PP +GitHub +.UR https://github.com/nginx/unit +.UE diff --git a/man3/nxt_unit_init.3 b/man3/nxt_unit_init.3 new file mode 100644 index 000000000..8b192cb31 --- /dev/null +++ b/man3/nxt_unit_init.3 @@ -0,0 +1,166 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_init 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_init \- initialize Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.B [[gnu::malloc(nxt_unit_done)]] +.BI "nxt_unit_ctx_t *_Nullable nxt_unit_init(nxt_unit_init_t *" init ); +.fi +.SH Arguments +.TP +.I init +Object that specifies how the application should work. +.SH Description +.MR nxt_unit_init 3 +initializes a Unit application. +.PP +It creates a main context object that +is necessary for most other libunit functions. +.PP +The next step after initializing the application is running it; +for that, see +.MR nxt_unit_run 3 . +.PP +The context object created by this function should be +destroyed by passing it to +.MR nxt_unit_done 3 . +.SH Return value +A pointer to a context object on success, +or NULL on error. +.SH Errors +Errors will be reported in the Unit debug log. +.IP \[bu] 3 +.MR pthread_mutex_init 3 +failed. +.PD 0 +.IP \[bu] +.MR nxt_unit_malloc 3 +failed. +.IP \[bu] +.I init->callbacks.request_handler +is NULL. +.PD +.SH Examples +.EX +#include +#include +#include +#include +#include +#include +\& +#include +\& +// See \c +.MR nxt_unit_response_add_field 3 . +void request_handler(nxt_unit_request_info_t *req); +\& +// See \c +.MR nxt_unit_ctx_alloc 3 . +void *worker(void *main_ctx); +\& +static int ready_handler(nxt_unit_ctx_t *main_ctx); +\& +static ssize_t nthreads; +static pthread_t *threads; +\& +int +main(int argc, char **argv) +{ + int err; + void *ret; + nxt_unit_ctx_t *ctx; + nxt_unit_init_t init; +\& + if (argc == 3 && strcmp(argv[1], "\-t") == 0) { + nthreads = atoi(argv[2]); + } +\& + bzero(&init, sizeof(nxt_unit_init_t)); + init.callbacks.request_handler = &request_handler; + init.callbacks.ready_handler = &ready_handler; +\& + ctx = nxt_unit_init(&init); + if (ctx == NULL) { + exit(EXIT_FAILURE); + } +\& + err = nxt_unit_run(ctx); + nxt_unit_debug(ctx, "main worker finished with %d code", err); +\& + for (ssize_t i = 0; i < nthreads; i++) { + err = pthread_join(threads[i], &ret); +\& + if (err != 0) { + nxt_unit_alert(ctx, "pthread_join(#%zd) failed: %s (%d)", + i, strerror(err), err); + } else { + nxt_unit_debug(ctx, "pthread_join(#%zd) retval: %"PRIdPTR, + i, (intptr_t) ret); + } + } +\& + nxt_unit_free(ctx, threads); +\& + nxt_unit_done(ctx); + nxt_unit_debug(NULL, "main worker done"); +\& + exit(EXIT_SUCCESS); +} +\& +static int +ready_handler(nxt_unit_ctx_t *ctx) +{ + int err; +\& + nxt_unit_debug(ctx, "ready"); +\& + if (nthreads <= 1) { + return NXT_UNIT_OK; + } +\& + threads = nxt_unit_malloc(ctx, sizeof(pthread_t) * (nthreads \- 1)); + if (threads == NULL) { + return NXT_UNIT_ERROR; + } +\& + // See \c +.MR nxt_unit_ctx_alloc 3 . + for (ssize_t i = 0; i < nthreads \- 1; i++) { + err = pthread_create(&threads[i], NULL, &worker, ctx); + if (err != 0) { + return NXT_UNIT_ERROR; + } + } +\& + return NXT_UNIT_OK; +} +.EE +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR nxt_unit_ctx_alloc 3 , +.MR nxt_unit_run 3 , +.MR nxt_unit_done 3 , +.MR unitd 8 +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/mailman/listinfo/unit +.UE +.PP +GitHub +.UR https://github.com/nginx/unit +.UE diff --git a/man3/nxt_unit_log.3 b/man3/nxt_unit_log.3 new file mode 100644 index 000000000..8c310d358 --- /dev/null +++ b/man3/nxt_unit_log.3 @@ -0,0 +1,91 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_log 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_log, nxt_unit_alert, nxt_unit_error, nxt_unit_warn, nxt_unit_debug +\- print messages to the debug log +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.B enum { +.B " NXT_UNIT_LOG_ALERT," +.B " NXT_UNIT_LOG_ERR," +.B " NXT_UNIT_LOG_WARN," +.B " NXT_UNIT_LOG_NOTICE," +.B " NXT_UNIT_LOG_INFO," +.B " NXT_UNIT_LOG_DEBUG," +.B }; +.PP +.B [[gnu::format(printf, 3, 4)]] +.BI "void nxt_unit_log(nxt_unit_ctx_t *_Nullable " ctx ", int " level , +.BI " const char *" fmt ", ...);" +.PP +.BI "#define nxt_unit_alert(" ctx ", " fmt ", ...) \fR/* ... */\fP" +.BI "#define nxt_unit_error(" ctx ", " fmt ", ...) \fR/* ... */\fP" +.BI "#define nxt_unit_warn(" ctx ", " fmt ", ...) \fR/* ... */\fP" +.BI "#define nxt_unit_debug(" ctx ", " fmt ", ...) \fR/* ... */\fP" +.fi +.SH Arguments +.TP +.I ctx +Thread or main context object. +See +.MR nxt_unit_init 3 +and +.MR nxt_unit_ctx_alloc 3 . +If NULL is passed, +the output will be printed to standard error. +.TP +.I level +Log level (see the +.IR enum ). +.TP +.I fmt +See +.MR snprintf 3 . +.SH Description +.MR nxt_unit_log 3 +writes a formatted string into the Unit debug log, +prefixed with information about the application, +and appended by a new-line character. +.PP +The macros are just wrappers around +.MR nxt_unit_log 3 +that pass a specific log level. +.SH Return value +None. +.SH Errors +If these functions fail to write to the Unit debug log, +they will fall back to standard error. +.SH Files +.TP +.I /usr/local/var/log/unit/unit.log +Unit debug log. +See +.MR unitd 8 . +.SH Examples +See +.MR nxt_unit_init 3 . +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR nxt_unit_req_log 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 diff --git a/man3/nxt_unit_malloc.3 b/man3/nxt_unit_malloc.3 new file mode 100644 index 000000000..752fd4183 --- /dev/null +++ b/man3/nxt_unit_malloc.3 @@ -0,0 +1,70 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_malloc 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_malloc \- +.MR malloc 3 +wrapper with logging +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.B [[gnu::malloc(nxt_unit_free)]] +.BI "void *_Nullable nxt_unit_malloc(nxt_unit_ctx_t *_Nullable " ctx , +.BI " size_t " size ); +.BI "void nxt_unit_free(nxt_unit_ctx_t *_Nullable " ctx ", void *_Nullable " ptr ); +.fi +.SH Arguments +.TP +.I ctx +See +.MR nxt_unit_log 3 . +.TP +.I size +See +.MR malloc 3 . +.TP +.I ptr +See +.MR free 3 . +.SH Description +.MR nxt_unit_malloc 3 +and +.MR nxt_unit_free 3 +are equivalent to +.MR malloc 3 +and +.MR free 3 , +but log in the Unit debug log. +.SH Return value +See +.MR malloc 3 . +.SH Errors +Errors will be reported in the Unit debug log. +.IP \[bu] 3 +.MR malloc 3 +failed. +.SH Examples +See +.MR nxt_unit_init 3 . +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR malloc 3 . +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/mailman/listinfo/unit +.UE +.PP +GitHub +.UR https://github.com/nginx/unit +.UE diff --git a/man3/nxt_unit_req_log.3 b/man3/nxt_unit_req_log.3 new file mode 100644 index 000000000..b1a665b49 --- /dev/null +++ b/man3/nxt_unit_req_log.3 @@ -0,0 +1,76 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_log 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_req_log, +nxt_unit_req_alert, +nxt_unit_req_error, +nxt_unit_req_warn, +nxt_unit_req_debug +\- +print messages to the debug log related to a request in a Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.B [[gnu::format(printf, 3, 4)]] +.BI "void nxt_unit_req_log(nxt_unit_request_info_t *_Nullable " req , +.BI " int " level ", const char *" fmt ", ...);" +.PP +.BI "#define nxt_unit_req_alert(" req ", " fmt ", ...) \fR/* ... */\fP" +.BI "#define nxt_unit_req_error(" req ", " fmt ", ...) \fR/* ... */\fP" +.BI "#define nxt_unit_req_warn(" req ", " fmt ", ...) \fR/* ... */\fP" +.BI "#define nxt_unit_req_debug(" req ", " fmt ", ...) \fR/* ... */\fP" +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I level +Log level +.TP +.I fmt +See +.MR snprintf 3 . +.SH Description +.MR nxt_unit_req_log 3 +is similar to +.MR nxt_unit_log 3 , +but it associates the log to a specific request. +.SH Return value +None. +.SH Errors +If these functions fail to write to the Unit debug log, +they will fall back to standard error. +.SH Files +.TP +.I /usr/local/var/log/unit/unit.log +Unit debug log. +See +.MR unitd 8 . +.SH Examples +See +.MR nxt_unit_response_add_field 3 . +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +.MR nxt_unit_log 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 diff --git a/man3/nxt_unit_request_read.3 b/man3/nxt_unit_request_read.3 new file mode 100644 index 000000000..ba07b4744 --- /dev/null +++ b/man3/nxt_unit_request_read.3 @@ -0,0 +1,142 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_request_read 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_request_read +\- +read content of a response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "ssize_t nxt_unit_request_read(nxt_unit_request_info_t *" req , +.BI " void " dst [. size "], size_t " size ); +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I dst +Buffer where the request message body will be written. +It's a buffer of +.I size +bytes. +.SH Description +.MR nxt_unit_request_read 3 +copies the client request message body into a buffer. +.PP +This function does not read +the header fields nor the request line, +which are available in +.IR req\->request . +.SH Return value +The number of bytes read on success, +or \-1 on error. +.SH Errors +Errors will be reported in the Unit debug log. +.TP +.B NXT_UNIT_ERROR +.RS +.PD 0 +.IP \[bu] 3 +Failed to read content. +.PD +.RE +.SH Examples +Below is a request and response pair, +and the source code to produce it. +It implements an echo web application. +.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]foo\enbar\[aq] | curl \-\-data\-binary @\- localhost;" +foo +bar +.EE +.SS C code +.EX +#define _GNU_SOURCE +#include +\& +#include +\& +void +request_handler(nxt_unit_request_info_t *req) +{ + int rc; + ssize_t res; + nxt_unit_buf_t *buf; +\& + rc = nxt_unit_response_init(req, 200, 1, strlen("Content\-Type") + + strlen("text/plain")); + 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_send(req); + if (rc != 0) { + goto fail; + } +\& + while (req\->content_length) { + buf = nxt_unit_response_buf_alloc(req, req\->content_length); + if (buf == NULL) { + rc = NXT_UNIT_ERROR; + goto fail; + } +\& + res = nxt_unit_request_read(req, buf\->free, + buf\->end \- buf\->free); + if (res == \-1) { + goto fail; + } +\& + buf\->free += res; +\& + rc = nxt_unit_buf_send(buf); + 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 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 diff --git a/man3/nxt_unit_response_add_content.3 b/man3/nxt_unit_response_add_content.3 new file mode 100644 index 000000000..037cec783 --- /dev/null +++ b/man3/nxt_unit_response_add_content.3 @@ -0,0 +1,91 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_response_add_content 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_response_add_content \- add content to HTTP response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "int nxt_unit_response_add_content(nxt_unit_request_info_t *" req , +.BI " const void " content [. size ], +.BI " uint32_t " size ); +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I content +Content of the response. +It's a buffer of +.I size +bytes. +.SH Description +.MR nxt_unit_response_add_content 3 +adds content to an HTTP response. +.PP +The response should have been initialized previously with +.MR nxt_unit_response_init 3 . +.PP +The response should have enough remaining buffer size available. +If there's not enough, +more buffer can be allocated with +.MR nxt_unit_response_buff_alloc 3 . +.PP +This function can be called several times, +and all contents will be merged into the (chunked) response. +After content is added to the response, +it should be sent with +.MR nxt_unit_response_send 3 . +.SH Return value +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 +Response not initialized. +.IP \[bu] +Response already sent. +.IP \[bu] +Content is longer than the response buffer. +.PD +.RE +.SH Examples +See +.MR nxt_unit_response_add_field 3 . +.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_add_field 3 , +.MR nxt_unit_response_buf_alloc 3 , +.MR nxt_unit_response_send 3 , +.MR nxt_unit_request_done 3 , +.MR unitd 8 +.PP +.UR https://www.rfc-editor.org/\:rfc/\:rfc9112\:#section-5 +RFC 9112, section 5: Field Syntax +.UE +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/\:mailman/\:listinfo/\:unit +.UE +.PP +GitHub +.UR https://github.com/\:nginx/\:unit +.UE diff --git a/man3/nxt_unit_response_add_field.3 b/man3/nxt_unit_response_add_field.3 new file mode 100644 index 000000000..b47e37c3f --- /dev/null +++ b/man3/nxt_unit_response_add_field.3 @@ -0,0 +1,162 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_response_add_field 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_response_add_field \- add field to HTTP response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "int nxt_unit_response_add_field(nxt_unit_request_info_t *" req , +.BI " const char " name [. nlen "], uint8_t " nlen , +.BI " const char " value [. vlen "], uint32_t " vlen ); +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I name +Name of the field. +It is a character sequence of length +.IR nlen . +.TP +.I value +Value of the field. +It is a character sequence of length +.IR vlen . +.SH Description +.MR nxt_unit_response_add_field 3 +adds a field to the header of an HTTP response. +.PP +The response should have been initialized previously with +.MR nxt_unit_response_init 3 . +.PP +If the +.B \%Content\-Length +header field is not sent, +Unit will send a +.B \%Transfer-Encoding:\ chunked +response, +and will produce the header if necessary. +.SH Return value +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 +Response not initialized. +.IP \[bu] +Too many response fields. +.IP \[bu] +Field is longer than the response buffer. +.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 +Content\-Length: 42 +Server: Unit/1.30.0 +Date: Sat, 22 May 2023 20:45:50 GMT +\& +Hello world! +.EE +.SS C code +.EX +#include +\& +#include +\& +void +request_handler(nxt_unit_request_info_t *req) +{ + int rc; +\& + rc = nxt_unit_response_init(req, 200, 2, strlen("Content\-Type") + + strlen("text/plain") + + strlen("Content\-Length") + + strlen("42") + + 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_field(req, "Content\-Length", + strlen("Content\-Length"), + "42", + strlen("42")); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_response_add_content(req, "Hello", strlen("Hello")); + if (rc != 0) { + goto fail; + } + rc = nxt_unit_response_add_content(req, " world!\en", + strlen(" world!\en")); + if (rc != 0) { + goto fail; + } +\& + rc = nxt_unit_response_send(req); +\& + nxt_unit_req_debug(req, "Response sent."); +\& +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_add_content 3 , +.MR nxt_unit_response_send 3 , +.MR nxt_unit_request_done 3 , +.MR unitd 8 +.PP +.UR https://www.rfc-editor.org/\:rfc/\:rfc9112\:#section-5 +RFC 9112, section 5: Field Syntax +.UE +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/\:mailman/\:listinfo/\:unit +.UE +.PP +GitHub +.UR https://github.com/\:nginx/\:unit +.UE 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 +.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 +\& +#include +\& +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 diff --git a/man3/nxt_unit_response_init.3 b/man3/nxt_unit_response_init.3 new file mode 100644 index 000000000..0b32559e6 --- /dev/null +++ b/man3/nxt_unit_response_init.3 @@ -0,0 +1,85 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_response_init 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_response_init \- initialize response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "int nxt_unit_response_init(nxt_unit_request_info_t *" req ", uint16_t " status , +.BI " uint32_t " max_fields , +.BI " uint32_t " max_fields_size ); +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I status +HTTP status code. +.TP +.I max_fields +Maximum number of HTTP header fields that will be added to the response. +.TP +.I max_fields_size +Size of the buffer that will be used for the HTTP header fields. +See +.MR nxt_unit_response_add_field 3 . +.SH Description +.MR nxt_unit_response_init 3 +initializes a response to a request. +.PP +It sets the response status, +and allocates the buffer necessary for the header fields. +Any fields will need to fit in that buffer. +The response content can also be fitted in that buffer, +but extra buffers can be allocated for it later with +.MR nxt_unit_response_buf_alloc 3 . +.SH Return value +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 +Response already initialized. +.IP \[bu] +Response already sent. +.IP \[bu] +.MR nxt_unit_malloc 3 +failed. +.PD +.RE +.SH Examples +See +.MR nxt_unit_response_add_field 3 . +.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_add_field 3 , +.MR nxt_unit_response_add_content 3 , +.MR nxt_unit_response_send 3 , +.MR nxt_unit_response_buf_alloc 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 diff --git a/man3/nxt_unit_response_send.3 b/man3/nxt_unit_response_send.3 new file mode 100644 index 000000000..56788644b --- /dev/null +++ b/man3/nxt_unit_response_send.3 @@ -0,0 +1,88 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_response_send 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_response_send \- send response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "int nxt_unit_response_send(nxt_unit_request_info_t *" req ); +.fi +.SH Arguments +.TP +.I req +Request object. +.SH Description +.MR nxt_unit_response_send 3 +sends a response to a request. +The response should have been previously crafted with +.MR nxt_unit_response_add_field 3 +and +.MR nxt_unit_response_add_content 3 . +.PP +If the +.B Content-length +header field is not present in the response, +Unit will automatically add a +.B Transfer-Encoding: chunked +header. +In that case, +it is possible to call this function several times, +and Unit will use chunks as appropriate for the contents. +.PP +This function tells +.MR unitd 8 +that the response is ready to be sent, +and puts it in the send queue. +It doesn't really send it, +and it may merge several response chunks into a single one +if they accumulate in the buffer. +.PP +When the response has been completely sent, +.MR nxt_unit_response_done 3 +should be called. +.SH Return value +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 +Response not initialized yet. +.IP \[bu] +Response already sent. +.PD +.RE +.SH Examples +See +.MR nxt_unit_response_add_field 3 . +.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_add_field 3 , +.MR nxt_unit_response_add_content 3 , +.MR nxt_unit_response_buf_alloc 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 diff --git a/man3/nxt_unit_response_write.3 b/man3/nxt_unit_response_write.3 new file mode 100644 index 000000000..a9ca392b8 --- /dev/null +++ b/man3/nxt_unit_response_write.3 @@ -0,0 +1,84 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_response_write 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_response_write +\- +write content of a response in Unit app +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "int nxt_unit_response_write(nxt_unit_request_info_t *" req , +.BI " const void " content [. size "], uint32_t " size ); +.fi +.SH Arguments +.TP +.I req +Request object. +.TP +.I content +Content of the response. +It's a buffer of +.I size +bytes. +.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 +See +.MR nxt_unit_response_buf_alloc 3 . +.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 diff --git a/man3/nxt_unit_run.3 b/man3/nxt_unit_run.3 new file mode 100644 index 000000000..2de7d10a0 --- /dev/null +++ b/man3/nxt_unit_run.3 @@ -0,0 +1,98 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_run 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_run \- run Unit app or app thread +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.B enum { +.B " NXT_UNIT_OK," +.B " NXT_UNIT_ERROR," +.B " NXT_UNIT_AGAIN," +.B }; +.PP +.BI "int nxt_unit_run(nxt_unit_ctx_t *" ctx ); +.fi +.SH Arguments +.TP +.I ctx +Thread or main context object for the application. +See +.MR nxt_unit_init 3 +and +.MR nxt_unit_ctx_alloc 3 . +.SH Description +.MR nxt_unit_run 3 +runs the application or application thread, +and puts it to work. +.SH Return value +0 on success, +or an 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 +.MR recvmsg 2 +failed. +.IP \[bu] +.MR sendmsg 2 +failed. +.IP \[bu] +.MR poll 2 +failed. +.IP \[bu] +.MR dup2 2 +failed. +.IP \[bu] +.MR nxt_unit_malloc 3 +failed. +.IP \[bu] +.I nxt_unit_init_t::callbacks.port_recv() +failed. +.IP \[bu] +.I nxt_unit_init_t::callbacks.port_send() +failed. +.IP \[bu] +Internal communication failure. +.IP \[bu] +Internal hash table failure. +.PD +.RE +.TP +.B NXT_UNIT_AGAIN +Some resource was busy; +try again. +.SH Examples +See +.MR nxt_unit_init 3 +and +.MR nxt_unit_ctx_alloc 3 . +.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_ctx_alloc 3 , +.MR nxt_unit_done 3 , +.MR unitd 8 +.PP +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/mailman/listinfo/unit +.UE +.PP +GitHub +.UR https://github.com/nginx/unit +.UE diff --git a/man3/nxt_unit_sptr_get.3 b/man3/nxt_unit_sptr_get.3 new file mode 100644 index 000000000..2666d6e8b --- /dev/null +++ b/man3/nxt_unit_sptr_get.3 @@ -0,0 +1,91 @@ +.\" (C) 2023, NGINX, Inc. +.\" +.TH nxt_unit_sptr_get 3 (date) "NGINX Unit (unreleased)" +.SH Name +nxt_unit_sptr_set, nxt_unit_sptr_get \- +serialized pointer; offset to self +.SH Library +NGINX Unit library +.RI ( libunit ", " -lunit ) +.SH Synopsis +.nf +.B #include +.PP +.BI "void nxt_unit_sptr_set(nxt_unit_sptr_t *" sptr ", void *" ptr ); +.BI "void *nxt_unit_sptr_get(nxt_unit_sptr_t *" sptr ); +.PP +.B "typedef union nxt_unit_sptr_u nxt_unit_sptr_t;" +.fi +.PP +.EX +.B union nxt_unit_sptr_u { +.B " uint8_t base[1];" +.B " uint32_t offset;" +.B } +.EE +.SH Arguments +.TP +.I sptr +Serialized pointer. +It represents a memory address as +an offset to the address of the offset itself. +.TP +.I ptr +Pointer to be serialized. +.SH Description +This type and helper functions are useful for +having dynamically structured data +in a single buffer. +.TP +.I nxt_unit_sptr_t +The +.I base +array is used for representing the base to which the offset applies. +It's not really used for reinterpreting the data in the union. +The base is the address of the first element in the array, +which is the same as the address of the union, +and thus is also the same as the address of the offset. +.IP +The +.I offset +is really the only field actually accessed in this union. +It points to the start of the data. +.\".IP +.\"This type could have been defined as a single offset integer, +.\"without using unions or arrays, +.\"but then it wouldn't be so clear that the offset points to +.\"some data later in the same container structure. +.TP +.MR nxt_unit_sptr_set 3 +Set the offset in the serialized pointer +to point to the data pointed to by +.IR ptr . +.TP +.MR nxt_unit_sptr_get 3 +Get a pointer to the data referenced by the serialized pointer +.IR sptr . +.PP +It is necessary to store pointers as offsets +when sharing a buffer via inter-process communication. +.SH Return value +.MR nxt_unit_sptr_get 3 +returns a pointer to the data previously set by +.MR nxt_unit_sptr_set 3 . +.SH Errors +None. +.SH Copyright +(C) 2017-2023, NGINX, Inc. +.PP +SPDX-License-Identifier: Apache-2.0 +.SH See also +Website +.UR https://unit.nginx.org +.UE +.PP +Mailing list +.UR https://mailman.nginx.org/mailman/listinfo/unit +.UE +.PP +GitHub +.UR https://github.com/nginx/unit +.UE diff --git a/scripts/LinuxManBook/LMBfront.roff b/scripts/LinuxManBook/LMBfront.roff index fdf1a9820..9451ea5e9 100644 --- a/scripts/LinuxManBook/LMBfront.roff +++ b/scripts/LinuxManBook/LMBfront.roff @@ -14,20 +14,20 @@ .sp .6i .ad r .ps 52 -\m[maroon]GNU/Linux\m[] +\m[maroon]NGINX Unit\m[] .sp 18p .ps 16 \f[BMB]THE MAN-PAGES BOOK\fP .sp 6i .ps 12 -\f[HB]Maintainers:\fP +\f[HB]Programmers:\fP .sp 2p .ps 10 -\f[HB]Alejandro Colomar 2020 - present (5.09 - HEAD) +\f[HB]Valentin V. Bartenev 2020 - present (5.09 - HEAD) .brp -Michael Kerrisk 2004 - 2021 (2.00 - 5.13) +Andrei Zeliankou <@.> 2004 - 2021 (2.00 - 5.13) .brp -Andries Brouwer 1995 - 2004 (1.6 - 1.70) +Max Romanov <@.> 1995 - 2004 (1.6 - 1.70) .brp -Rik Faith 1993 - 1995 \0(1.0 - 1.5)\fP +Igor Sysoev 1993 - 1995 \0(1.0 - 1.5)\fP .bp -- cgit v1.2.3