.TH HANDLER_LISTEN 3 2023-09-14 0.1.0 "libweb Library Reference"

.SH NAME
handler_listen \- listen to and handle incoming connections on a web
server

.SH SYNOPSIS
.LP
.nf
#include <libweb/handler.h>
.P
int handler_listen(struct handler *\fIh\fP, unsigned short \fIport\fP);
.fi

.SH DESCRIPTION
The
.IR handler_listen (3)
function listens for connections on the TCP port number given by
.I port
on a
.I struct handler
object pointed to by
.IR h ,
which must be previously allocated by a call to
.IR handler_alloc (3).

Also, the
.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.

.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 libweb_handler (7),
.BR signal (7).

.SH COPYRIGHT
Copyright (C) 2023 Xavier Del Campo Romero.
.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.