doc: Update handler_{loop,listen}

1 files changed, 75 insertions, 0 deletions

diff --git a/doc/man3/handler_loop.3 b/doc/man3/handler_loop.3
new file mode 100644
index 0000000..d442e41
--- /dev/null
+++ b/doc/man3/handler_loop.3
@@ -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.