.TH HANDLER_LOOP 3 2024-08-22 0.4.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-2024 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.