Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTTP_SERVER(3)	       FreeBSD Library Functions Manual		HTTP_SERVER(3)

     http_server -- threaded server for	HTTP and HTTPS

     PDEL Library (libpdel, -lpdel)

     #include <sys/types.h>
     #include <stdio.h>
     #include <netinet/in.h>
     #include <openssl/ssl.h>
     #include <pdel/http/http_defs.h>
     #include <pdel/http/http_server.h>

     struct http_server	*
     http_server_start(struct pevent_ctx *ctx, struct in_addr ip,
	 u_int16_t port, const struct http_server_ssl *ssl,
	 const char *server_name, http_logger_t	*logger);

     http_server_stop(struct http_server **serverp);

     http_server_register_servlet(struct http_server *serv,
	 struct	http_servlet *servlet, const char *vhost, const	char *urlpat,
	 int order);

     http_server_destroy_servlet(struct	http_servlet **servletp);

     http_server_set_proxy_handler(struct http_server *serv,
	 http_proxy_t *handler,	void *arg);

     These functions implement a threaded HTTP server supporting SSL and user-
     definable "servlets".

     http_server_start() starts	a new server listening on IP address ip	and
     port port.	 If ip is then the server listens on all configured IP
     addresses.	 If port is zero then the default port (either 80 or 443 de-
     pending on	whether	SSL is enabled)	is used.  SSL is enabled by supplying
     a non-NULL	pointer	ssl to this structure:

	struct http_server_ssl {
	    const char	 *cert_path;	 /* path to certificate	file */
	    const char	 *pkey_path;	 /* path to private key	file */
	    const char	 *pkey_password; /* private key	password, if needed */

     ctx is a pevent(3)	event context with which the server registers to ac-
     cept incoming connections.	 New connections are allocated individual
     threads in	which to execute.  The server enforces a hard limit of at most
     1024 simultaneous connections, refusing to	accept any new connections un-
     til one or	more existing connections terminate.

     The server_name string is used for	the "Server:" HTTP header and typi-
     cally includes the	name and version number	of the software, e.g.,

     The logger, if not	NULL, specifies	a callback for logging:

	typedef	void  http_logger_t(int	sev, const char	*fmt, ...);

     Here sev is a syslog(3) severity level.

     http_server_stop()	stops a	server.	 All registered	servlets are destroyed
     (see http_server_destroy_servlet()	below).	 Upon return, all connection
     threads are guaranteed to have exited and *serverp	will be	set to NULL.
     If	*serverp is already NULL when http_server_stop() is invoked, nothing

     Invoking http_server_stop() from within a servlet is not supported	and
     will give undefined results.

     For anything interesting to happen, one or	more servlets must be regis-
     tered (see	http_servlet(3)).  Servlets are	registered by invoking

     The vhost parameter may be	used for virtual hosting.  If vhost is not
     NULL, it defines a	virtual	host for the server, and the servlet will only
     be	invoked	for requests whose Host: header	matches	vhost.	If vhost is
     NULL, the servlet will only be invoked for	requests with no Host: header
     or	whose host does	not match any other virtual host defined for the
     server (i.e., a NULL vhost	indicates the default virtual host).

     The servlet will be invoked for queries matching urlpat, which is an ex-
     tended regular expression (see re_format(7)).

     The request URI is	URL-decoded before matching begins and only the	rela-
     tive part is matched.  For	example, a servlet registered to match the
     regular expression	"^/foo bar$" would match "http://server/foo%20bar" and
     "http://server/foo%20bar?field=value" but not "http://server/foo%20bar/".

     If	two or more servlets match the same request, the servlet that was reg-
     istered with the lowest order is chosen.  If two servlets match and have
     the same order, the last one registered is	chosen.

     The order in which	servlets are registered	is important, especially with
     authorization servlets, because incoming requests may arrive at any time.
     I.e., authorization servlets should be registered before the servlet(s)
     that they protect.

     http_server_destroy_servlet() destroys a servlet, unregistering it	as
     necessary.	 If any	instances of the servlet are executing,	this function
     will block	until they exit.  Upon return, *servletp is set	to NULL. If
     *servletp is already NULL when http_server_destroy_servlet() is invoked,
     nothing happens.

   Proxy support
     Primitive proxy support is	provided by http_server_set_proxy_handler().
     The handler is a pointer to a function of this type:

	typedef	void http_proxy_t(void *arg, struct http_request *req,
			 struct	http_response *resp);

     The handler is invoked with the same arg whenever an HTTP proxy request
     is	received.  To disable proxy support, invoke
     http_server_set_proxy_handler() with both arguments equal to NULL.

     Upon error, http_server_start() and http_server_register_servlet()	return
     NULL or -1, respectively, and set errno to	an appropriate value.

     http_client(3), http_mime(3), http_request(3), http_response(3),
     http_servlet(3), http_xml(3), libpdel(3), pevent(3), syslog(3),

     R.	Fielding, J. Gettys, J.	Mogul, H. Frystyk, L. Masinter,	P. Leach, and
     T.	Berners-Lee, Hypertext Transfer	Protocol -- HTTP/1.1, RFC 2616.

     The PDEL library was developed at Packet Design, LLC.

     Archie Cobbs <>

     Creating a	new thread for each request is somewhat	expensive.  The	server
     should keep a pool	of idle	threads	for faster dispatch of incoming	con-

     The maximum number	of connections should be configurable.

     The server	is probably not	fully compliant	to the HTTP specification.

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help