doc: Update handler_{loop,listen}
This commit is contained in:
parent
c9edbbc4b0
commit
2561ec32fe
|
@ -9,6 +9,7 @@ OBJECTS = \
|
|||
$(DESTDIR)$(man3dir)/handler_alloc.3 \
|
||||
$(DESTDIR)$(man3dir)/handler_free.3 \
|
||||
$(DESTDIR)$(man3dir)/handler_listen.3 \
|
||||
$(DESTDIR)$(man3dir)/handler_loop.3 \
|
||||
$(DESTDIR)$(man3dir)/html_node_add_attr.3 \
|
||||
$(DESTDIR)$(man3dir)/html_node_add_child.3 \
|
||||
$(DESTDIR)$(man3dir)/html_node_add_sibling.3 \
|
||||
|
|
|
@ -77,10 +77,11 @@ for a list of possible errors.
|
|||
.BR handler_alloc (3),
|
||||
.BR handler_free (3),
|
||||
.BR handler_listen (3),
|
||||
.BR handler_loop (3),
|
||||
.BR libweb_handler (7).
|
||||
|
||||
.SH COPYRIGHT
|
||||
Copyright (C) 2023 Xavier Del Campo Romero.
|
||||
Copyright (C) 2023 libweb contributors.
|
||||
.P
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH HANDLER_ALLOC 3 2023-09-13 0.1.0 "libweb Library Reference"
|
||||
.TH HANDLER_ALLOC 3 2023-11-16 0.2.0 "libweb Library Reference"
|
||||
|
||||
.SH NAME
|
||||
handler_alloc \- allocate a web server handler object
|
||||
|
@ -48,10 +48,11 @@ for a list of possible errors.
|
|||
.BR handler_free (3),
|
||||
.BR handler_add (3),
|
||||
.BR handler_listen (3),
|
||||
.BR handler_loop (3),
|
||||
.BR libweb_handler (7).
|
||||
|
||||
.SH COPYRIGHT
|
||||
Copyright (C) 2023 Xavier Del Campo Romero.
|
||||
Copyright (C) 2023 libweb contributors.
|
||||
.P
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
|
|
|
@ -1,42 +1,37 @@
|
|||
.TH HANDLER_LISTEN 3 2023-09-14 0.1.0 "libweb Library Reference"
|
||||
.TH HANDLER_LISTEN 3 2023-11-16 0.2.0 "libweb Library Reference"
|
||||
|
||||
.SH NAME
|
||||
handler_listen \- listen to and handle incoming connections on a web
|
||||
server
|
||||
handler_listen \- initialize server to listen to a given port
|
||||
|
||||
.SH SYNOPSIS
|
||||
.LP
|
||||
.nf
|
||||
#include <libweb/handler.h>
|
||||
.P
|
||||
int handler_listen(struct handler *\fIh\fP, unsigned short \fIport\fP);
|
||||
int handler_listen(struct handler *\fIh\fP, unsigned short \fIport\fP, unsigned short *\fIoutport\fP);
|
||||
.fi
|
||||
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.IR handler_listen (3)
|
||||
function listens for connections on the TCP port number given by
|
||||
.I port
|
||||
on a
|
||||
function initializes the internal server on a
|
||||
.I struct handler
|
||||
object pointed to by
|
||||
.IR h ,
|
||||
which must be previously allocated by a call to
|
||||
.IR handler_alloc (3).
|
||||
.IR handler_alloc (3),
|
||||
to listen on the TCP port given by
|
||||
.IR port .
|
||||
|
||||
Also, the
|
||||
If
|
||||
.I outport
|
||||
is a valid pointer,
|
||||
.IR handler_listen (3)
|
||||
function validates incoming requests and calls the configured
|
||||
callbacks previously given by one or more calls to
|
||||
.IR handler_add (3).
|
||||
|
||||
The
|
||||
.IR handler_listen (3)
|
||||
function blocks until either
|
||||
.I SIGTERM
|
||||
or
|
||||
.I SIGINT
|
||||
are triggered.
|
||||
shall assign the object pointed to by
|
||||
.I outport
|
||||
to the port number the server shall listen to. This is typically meant
|
||||
for servers that listen on any port, but the caller needs to know which
|
||||
port was eventually selected by the implementation.
|
||||
|
||||
.SH RETURN VALUE
|
||||
On success, zero is returned. On error, a negative integer is returned.
|
||||
|
@ -44,28 +39,16 @@ On success, zero is returned. On error, a negative integer is returned.
|
|||
.SH ERRORS
|
||||
No errors are defined.
|
||||
|
||||
.SH FUTURE DIRECTIONS
|
||||
When no configured endpoint matches the incoming request,
|
||||
.I libweb
|
||||
shall respond with a
|
||||
.B 404 Not Found
|
||||
HTTP status code with no payload. Since some library users might want
|
||||
to provide custom pages for such error condition, future versions of
|
||||
this library shall replace the harcoded response with an additional
|
||||
callback on
|
||||
.IR "struct handler_cfg" ,
|
||||
similarly to its member
|
||||
.IR length .
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR handler_alloc (3),
|
||||
.BR handler_free (3),
|
||||
.BR handler_add (3),
|
||||
.BR handler_loop (3),
|
||||
.BR libweb_handler (7),
|
||||
.BR signal (7).
|
||||
|
||||
.SH COPYRIGHT
|
||||
Copyright (C) 2023 Xavier Del Campo Romero.
|
||||
Copyright (C) 2023 libweb contributors.
|
||||
.P
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
|
|
|
@ -0,0 +1,75 @@
|
|||
.TH HANDLER_LOOP 3 2023-11-16 0.2.0 "libweb Library Reference"
|
||||
|
||||
.SH NAME
|
||||
handler_loop \- listen to and handle incoming connections on a web
|
||||
server
|
||||
|
||||
.SH SYNOPSIS
|
||||
.LP
|
||||
.nf
|
||||
#include <libweb/handler.h>
|
||||
.P
|
||||
int handler_loop(struct handler *\fIh\fP);
|
||||
.fi
|
||||
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.IR handler_loop (3)
|
||||
function listens for connections on a
|
||||
.I struct handler
|
||||
object pointed to by
|
||||
.IR h ,
|
||||
which must be previously allocated by a call to
|
||||
.IR handler_alloc (3)
|
||||
and initialized by a call to
|
||||
.IR handler_listen (3),
|
||||
in a loop.
|
||||
|
||||
Also, the
|
||||
.IR handler_loop (3)
|
||||
function validates incoming requests and calls the configured
|
||||
callbacks previously given by one or more calls to
|
||||
.IR handler_add (3).
|
||||
|
||||
The
|
||||
.IR handler_loop (3)
|
||||
function blocks until either
|
||||
.I SIGTERM
|
||||
or
|
||||
.I SIGINT
|
||||
are triggered.
|
||||
|
||||
.SH RETURN VALUE
|
||||
On success, zero is returned. On error, a negative integer is returned.
|
||||
|
||||
.SH ERRORS
|
||||
No errors are defined.
|
||||
|
||||
.SH FUTURE DIRECTIONS
|
||||
When no configured endpoint matches the incoming request,
|
||||
.I libweb
|
||||
shall respond with a
|
||||
.B 404 Not Found
|
||||
HTTP status code with no payload. Since some library users might want
|
||||
to provide custom pages for such error condition, future versions of
|
||||
this library shall replace the harcoded response with an additional
|
||||
callback on
|
||||
.IR "struct handler_cfg" ,
|
||||
similarly to its member
|
||||
.IR length .
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR handler_alloc (3),
|
||||
.BR handler_free (3),
|
||||
.BR handler_add (3),
|
||||
.BR handler_listen (3),
|
||||
.BR libweb_handler (7),
|
||||
.BR signal (7).
|
||||
|
||||
.SH COPYRIGHT
|
||||
Copyright (C) 2023 libweb contributors.
|
||||
.P
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
|
@ -51,9 +51,15 @@ operation.
|
|||
|
||||
.IP \(bu 2
|
||||
.IR handler_listen (3):
|
||||
initializes the server on a
|
||||
.I "struct handler"
|
||||
object to listen on a given port.
|
||||
|
||||
.IP \(bu 2
|
||||
.IR handler_loop (3):
|
||||
puts a
|
||||
.I "struct handler"
|
||||
object to initialize the server and handle connections in a loop.
|
||||
object to handle connections in a loop.
|
||||
|
||||
The
|
||||
.IR handler_alloc (3)
|
||||
|
@ -200,11 +206,16 @@ int main(int argc, char *argv[])
|
|||
goto end;
|
||||
}
|
||||
|
||||
if (handler_listen(h, port))
|
||||
if (handler_listen(h, port, NULL))
|
||||
{
|
||||
fprintf(stderr, "%s: handler_listen failed\en", __func__);
|
||||
goto end;
|
||||
}
|
||||
else if (handler_loop(h))
|
||||
{
|
||||
fprintf(stderr, "%s: handler_loop failed\en", __func__);
|
||||
goto end;
|
||||
}
|
||||
|
||||
ret = EXIT_SUCCESS;
|
||||
|
||||
|
@ -220,10 +231,12 @@ end:
|
|||
.BR handler_alloc (3),
|
||||
.BR handler_add (3),
|
||||
.BR handler_free (3),
|
||||
.BR handler_listen (3),
|
||||
.BR handler_loop (3),
|
||||
.BR libweb_http (7).
|
||||
|
||||
.SH COPYRIGHT
|
||||
Copyright (C) 2023 Xavier Del Campo Romero.
|
||||
Copyright (C) 2023 libweb contributors.
|
||||
.P
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
|
|
Loading…
Reference in New Issue