Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  HTTP_SERVER (3)


http_server - threaded server for HTTP and HTTPS


Return Values
See Also


PDEL Library (libpdel, -lpdel)


.In sys/types.h
.In stdio.h
.In netinet/in.h
.In openssl/ssl.h
.In pdel/http/http_defs.h
.In 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 void http_server_stop struct http_server **serverp int http_server_register_servlet struct http_server *serv struct http_servlet *servlet const char *vhost const char *urlpat int order void http_server_destroy_servlet struct http_servlet **servletp void 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 depending 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 accept 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 until one or more existing connections terminate.

The server_name string is used for the "Server:" HTTP header and typically includes the name and version number of the software, e.g., "MyServer/1.0".

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 happens.

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 registered (see http_servlet(3)). Servlets are registered by invoking http_server_register_servlet.

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 extended regular expression (see re_format(7)).

The request URI is URL-decoded before matching begins and only the relative 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 registered 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), re_format(7)
.Rs Hypertext Transfer Protocol -- HTTP/1.1


The PDEL library was developed at Packet Design, LLC.


.An Archie Cobbs Aq


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

The maximum number of connections should be configurable.

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

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.