74 lines
1.7 KiB
Groff
74 lines
1.7 KiB
Groff
.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.
|