Data Structures
struct	onion_t
	Webserver info.This is information about onion implementation of the generic server. It contains the listening descriptors, the SSL parameters if SSL is enabled... More...
struct	onion_poller_slot_t
	Data about a poller element: timeout, function to call shutdown function.

Enumerations
enum	onion_mode_e { O_ONE = 1, O_ONE_LOOP = 3, O_THREADED = 4, O_DETACH_LISTEN = 8, O_SYSTEMD = 0x010, O_POLL = 0x020, O_POOL = 0x024, O_NO_SIGPIPE = 0x040, O_NO_SIGTERM = 0x080, O_SSL_AVAILABLE = 0x0100, O_SSL_ENABLED = 0x0200, O_THREADS_AVAILABLE = 0x0400, O_THREADS_ENABLED = 0x0800, O_DETACHED = 0x01000, O_LISTENING = 0x02000 }

Functions
onion *	onion_new (int flags)
	Creates the onion structure to fill with the server data, and later do the onion_listen()Creates an onion structure that can be used to set the server, port, SSL and similar parameters. It works over the onion structure, which is the main structure to control the listening of new connections throught TCP/IP.
void	onion_free (onion *onion)
	Removes the allocated data.
int	onion_listen (onion *o)
	Performs the listening with the given modeThis is the main loop for the onion server.
void	onion_set_root_handler (onion onion, onion_handler handler)
	Sets the root handler.
onion_handler *	onion_get_root_handler (onion *server)
	Returns current root handler.For example when changing root handler, the old one is not deleted (as oposed that when deleting the onion* object it is). So user may use onion_handler_free(onion_get_root_handler(o));.
void	onion_set_internal_error_handler (onion server, onion_handler handler)
	Sets the internal error handler.
int	onion_add_listen_point (onion server, const char hostname, const char port, onion_listen_point protocol)
	Sets the port to listen to.Default listen point is HTTP at localhost:8080.
void	onion_set_timeout (onion *onion, int timeout)
	Sets the timeout, in millisecondsThe default timeout is 5000 milliseconds.
void	onion_set_max_threads (onion *onion, int max_threads)
	Sets the maximum number of threads to use for requests. default 16.Can only be tweaked before listen.
int	onion_flags (onion *onion)
	Returns the current flags.
void	onion_set_user (onion server, const char username)
	User to which drop priviledges when listeningDrops the priviledges of current program as soon as it starts listening.
onion_url *	onion_root_url (onion *server)
	If no root handler is set, creates an url handler and returns it.It can also check if the current root handler is a url handler, and if it is, returns it. Else returns NULL.
void	onion_set_client_data (onion server, void data, onion_client_data_free_sig *data_free)
	set a client data in the onion, freeing the previous one if it exists. Thread-safe.
void *	onion_client_data (onion *server)
	Retrieve the client data in the onion server. Thread-safe.
void	onion_listen_stop (onion *server)
	Stops the listening.
void	onion_set_port (onion server, const char port)
	Sets the port to listen.
void	onion_set_hostname (onion server, const char hostname)
	Sets the hostname on which to listen.
int	onion_set_certificate (onion onion, onion_ssl_certificate_type type, const char filename,...)
	Set a certificate for use in the connection.
int	onion_set_certificate_va (onion onion, onion_ssl_certificate_type type, const char filename, va_list va)
	Set a certificate for use in the connection. va_list version.
onion_listen_point *	onion_get_listen_point (onion *server, int nlisten_point)
	Gets a single listen point, or NULL if not that many.
onion_poller *	onion_get_poller (onion *server)
	If on poller mode, returns the poller, if not, returns NULL.
void	onion_set_max_post_size (onion *server, size_t max_size)
	Set the maximum post size.
void	onion_set_max_file_size (onion *server, size_t max_size)
	Set the maximum post FILE size.
void	onion_set_session_backend (onion server, onion_sessions sessions_backend)
	Set a new session backend.

Detailed Description

Creates the onion structure to fill with the server data, and later do the onion_listen()

Enumeration Type Documentation

enum onion_mode_e

Flags for the mode of operation of the onion server.

Enumerator:

O_ONE	Perform just one petition.
O_ONE_LOOP	Perform one petition at a time; lineal processing.
O_THREADED	Threaded processing, process many petitions at a time. Needs pthread support.
O_DETACH_LISTEN	When calling onion_listen, it returns inmediatly and do the listening on another thread. Only if threading is available.
O_SYSTEMD	Allow to start as systemd service. It try to start as if from systemd, but if not, start normally, so its "transparent".
O_POLL	Use polling for request read, then as other flags say. O_POLL must be used with other method, O_ONE_LOOP or O_THREAD, and it will poll for requests until the request is ready. On that moment it will or just launch the request, which should not block, or a new thread for this request. If on O_ONE_LOOP mode the request themselves can hook to the onion_poller object, and be called when ready. (TODO).Use epoll for request read, then as other flags say.
O_POOL	Create some threads, and make them listen for ready file descriptors. It is O_POLL\|O_THREADED.
O_NO_SIGPIPE	Since 0.7 by default onion ignores SIGPIPE signals, as they were a normal cause for program termination in undesired conditions.
O_NO_SIGTERM	Since 0.7 by default onion connect SIGTERM/SIGINT to onion_listen_stop, sice normally thats what user needs. Double Crtl-C do an abort.
O_SSL_AVAILABLE	This is set by the library when creating the onion object, if SSL support is available.
O_SSL_ENABLED	This is set by the library when setting the certificates, if SSL is available.
O_THREADS_AVAILABLE	Threads are available on this onion build.
O_THREADS_ENABLED	Threads are enabled on this onion object. It difers from O_THREADED as this is set by the library, so it states a real status, not a desired one.
O_DETACHED	Currently listening on another thread.
O_LISTENING	Currently listening

Function Documentation

int onion_add_listen_point	(	onion *	server,
		const char *	hostname,
		const char *	port,
		onion_listen_point *	protocol
	)

Sets the port to listen to.Default listen point is HTTP at localhost:8080.

Adds a listen point, a listening address and port with a given protocol.

Parameters

server	The onion server to act on.
port	The number of port to listen to, or service name, as string always.

References onion_listen_point_t::hostname, onion_t::listen_points, ONION_DEBUG, ONION_ERROR, onion_low_malloc(), onion_low_realloc(), onion_low_strdup(), onion_listen_point_t::port, and onion_listen_point_t::server.

Referenced by onion_listen(), onion_set_certificate_va(), onion_set_hostname(), and onion_set_port().

void* onion_client_data ( onion * server )

Retrieve the client data in the onion server. Thread-safe.

References onion_t::client_data, pthread_mutex_lock, and pthread_mutex_unlock.

int onion_flags ( onion * onion )

Returns the current flags.

Gets the current flags, for example to check SSL support.

See Also: onion_mode_e

References onion_t::flags.

void onion_free ( onion * onion )

Removes the allocated data.

Removes the allocated data (also free the client data, if one was given).

References onion_t::client_data, onion_t::client_data_free, onion_t::flags, onion_t::internal_error_handler, onion_t::listen_points, O_LISTENING, O_NO_SIGTERM, ONION_DEBUG, onion_handler_t::onion_handler_free(), onion_listen_point_t::onion_listen_point_free(), onion_listen_stop(), onion_low_free(), onion_mime_set(), onion_poller_t::onion_poller_free(), onion_sessions_t::onion_sessions_free(), onion_t::poller, pthread_mutex_lock, pthread_mutex_unlock, onion_t::root_handler, onion_t::sessions, and onion_t::username.

onion_listen_point* onion_get_listen_point	(	onion *	server,
		int	nlisten_point
	)

Gets a single listen point, or NULL if not that many.

Parameters

server	The onion server
nlisten_point	Listen point index.

Returns: The listen point, or NULL if not that many listen points.

References onion_t::listen_points.

onion_poller* onion_get_poller ( onion * server )

If on poller mode, returns the poller, if not, returns NULL.

References onion_t::poller.

Referenced by onion_request_process().

onion_handler * onion_get_root_handler ( onion * server )

Returns current root handler.For example when changing root handler, the old one is not deleted (as oposed that when deleting the onion* object it is). So user may use onion_handler_free(onion_get_root_handler(o));.

Sets the root handler.

Parameters

server The onion server

Returns: onion_handler currently at root.

References onion_t::root_handler.

int onion_listen ( onion * o )

Performs the listening with the given modeThis is the main loop for the onion server.

Performs the listening with the given mode.

It initiates the listening on all the selected ports and addresses.

Returns: !=0 if there is any error. It returns actualy errno from the network operations. See socket for more information.

Start listening

References onion_request_t::connection, onion_t::flags, onion_request_t::listen_point, onion_t::listen_points, onion_listen_point_t::listenfd, O_DETACH_LISTEN, O_DETACHED, O_LISTENING, O_ONE, O_ONE_LOOP, O_POLL_ALL, O_THREADED, onion_add_listen_point(), ONION_DEBUG, ONION_ERROR, onion_http_t::onion_http_new(), onion_listen_point_t::onion_listen_point_accept(), onion_listen_point_t::onion_listen_point_listen(), onion_low_malloc(), onion_poller_t::onion_poller_add(), onion_poller_t::onion_poller_poll(), onion_poller_t::onion_poller_remove(), onion_poller_slot_t::onion_poller_slot_new(), onion_poller_slot_set_type(), onion_request_t::onion_request_free(), onion_request_t::onion_request_new(), onion_request_t::onion_request_set_no_keep_alive(), ONION_WARNING, onion_t::poller, and onion_listen_point_t::read_ready.

void onion_listen_stop ( onion * server )

Stops the listening.

The listener is advised to stop listening. After this call no listening is still open, and listen could be called again, or the onion server freed.

If there is any pending connection, it can finish if onion not freed before.

Not listening

Stop listening

References onion_t::flags, onion_t::listen_points, O_DETACHED, O_LISTENING, ONION_DEBUG, onion_listen_point_t::onion_listen_point_listen_stop(), onion_poller_t::onion_poller_stop(), and onion_t::poller.

Referenced by onion_free().

onion * onion_new ( int flags )

Creates the onion structure to fill with the server data, and later do the onion_listen()Creates an onion structure that can be used to set the server, port, SSL and similar parameters. It works over the onion structure, which is the main structure to control the listening of new connections throught TCP/IP.

A normal usage would be like this:

onion *o=onion_new(O_THREADED);
onion_set_root_handler(o, onion_handler_directory("."));
onion_listen(o);

Parameters

flags Or'ed flags to use at the listening daemon. Normally one of O_ONE, O_ONE_LOOP or O_THREADED.

Returns: The onion structure.

See Also: onion_mode_e onion_t

References onion_t::flags, onion_t::internal_error_handler, onion_t::max_file_size, onion_t::max_post_size, O_NO_SIGPIPE, O_NO_SIGTERM, O_SSL_AVAILABLE, O_THREADED, O_THREADS_AVAILABLE, O_THREADS_ENABLED, ONION_DEBUG, ONION_DEBUG0, onion_handler_t::onion_handler_new(), onion_low_calloc(), onion_low_free(), onion_poller_t::onion_poller_new(), onion_sessions_t::onion_sessions_new(), ONION_WARNING, onion_t::poller, pthread_mutex_init, onion_t::sessions, SOCK_CLOEXEC, and onion_t::timeout.

onion_url * onion_root_url ( onion * server )

If no root handler is set, creates an url handler and returns it.It can also check if the current root handler is a url handler, and if it is, returns it. Else returns NULL.

If no root handler is set, creates an url handler and returns it.

References ONION_DEBUG, onion_url_free_data(), onion_url_new(), ONION_WARNING, onion_handler_t::priv_data_free, and onion_t::root_handler.

int onion_set_certificate	(	onion *	onion,
		onion_ssl_certificate_type	type,
		const char *	filename,
			...
	)

Set a certificate for use in the connection.

References onion_set_certificate_va().

int onion_set_certificate_va	(	onion *	onion,
		onion_ssl_certificate_type	type,
		const char *	filename,
		va_list	va
	)

Set a certificate for use in the connection. va_list version.

References onion_listen_point_t::hostname, onion_t::listen_points, onion_add_listen_point(), ONION_DEBUG, ONION_ERROR, onion_http_t::onion_http_write(), onion_https_t::onion_https_new(), onion_https_t::onion_https_set_certificate_argv(), onion_https_t::onion_https_write(), onion_listen_point_t::onion_listen_point_free(), onion_low_strdup(), onion_listen_point_t::port, onion_listen_point_t::server, and onion_listen_point_t::write.

Referenced by onion_set_certificate().

void onion_set_client_data	(	onion *	server,
		void *	data,
		onion_client_data_free_sig *	data_free
	)

set a client data in the onion, freeing the previous one if it exists. Thread-safe.

References onion_t::client_data, onion_t::client_data_free, pthread_mutex_lock, and pthread_mutex_unlock.

void onion_set_hostname	(	onion *	server,
		const char *	hostname
	)

Sets the hostname on which to listen.

References onion_listen_point_t::hostname, onion_t::listen_points, onion_add_listen_point(), onion_http_t::onion_http_new(), onion_low_free(), and onion_low_strdup().

void onion_set_internal_error_handler	(	onion *	server,
		onion_handler *	handler
	)

Sets the internal error handler.

Sets the root handler.

References onion_t::internal_error_handler.

void onion_set_max_file_size	(	onion *	server,
		size_t	max_size
	)

Set the maximum post FILE size.

By default its 1GB of file data. This files are stored in /tmp/, and deleted when the request finishes. It can fill up your hard drive if not choosen carefully.

Internally its stored as a file_t size, so SIZE_MAX size limit applies, which may depend on your architecture. (2^32-1, 2^64-1...).

Parameters

server	The onion server
max_size	The maximum desired size in bytes, by default 1GB.

References onion_t::max_file_size.

void onion_set_max_post_size	(	onion *	server,
		size_t	max_size
	)

Set the maximum post size.

By default its 1MB of post data. This data has to be chossen carefully as this data is stored in memory, and can be abused.

Parameters

server	The onion server
max_size	The maximum desired size in bytes, by default 1MB.

References onion_t::max_post_size.

void onion_set_max_threads	(	onion *	onion,
		int	max_threads
	)

Sets the maximum number of threads to use for requests. default 16.Can only be tweaked before listen.

Sets the maximum number of threads to use for requests. default 16.

If its modified after listen, the behaviour can be unexpected, on the sense that it may server an undetermined number of request on the range [new_max_threads, current max_threads + new_max_threads]

void onion_set_port	(	onion *	server,
		const char *	port
	)

Sets the port to listen.

References onion_t::listen_points, onion_add_listen_point(), onion_http_t::onion_http_new(), onion_low_free(), onion_low_strdup(), and onion_listen_point_t::port.

void onion_set_root_handler	(	onion *	onion,
		onion_handler *	handler
	)

Sets the root handler.

References onion_t::root_handler.

void onion_set_session_backend	(	onion *	server,
		onion_sessions *	sessions_backend
	)

Set a new session backend.

By default it uses in mem sessions, but it can be set to use sqlite sessions.

Example:

onion_set_session_backend(server, onion_sessions_sqlite3_new("sessions.sqlite"));

Parameters

server	The onion server
sessions_backend	The new backend

References onion_sessions_t::onion_sessions_free(), and onion_t::sessions.

void onion_set_timeout	(	onion *	onion,
		int	timeout
	)

Sets the timeout, in millisecondsThe default timeout is 5000 milliseconds.

Sets the timeout, in milliseconds, 0 dont wait for incomming data (too strict maybe), -1 forever, clients closes connection.

Parameters

timeout 0 dont wait for incomming data (too strict maybe), -1 forever, clients closes connection

References onion_t::timeout.

void onion_set_user	(	onion *	server,
		const char *	username
	)

User to which drop priviledges when listeningDrops the priviledges of current program as soon as it starts listening.

Sets this user as soon as listen starts.

This is the easiest way to allow low ports and other sensitive info to be used, but the proper way should be use capabilities and/or SELinux.

References onion_low_strdup(), and onion_t::username.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation