This is a quick HOWTO for writing user-space TUX modules.  It is not hard
to program TUX user-space modules -- sample code can be found in demo.c.


Module versions
---------------

The interface between user-space TUX modules and the kernel-space TUX
subsystem is versioned.  Modules can see/check the current TUX version
via the TUX_MAJOR_VERSION, TUX_MINOR_VERSION and TUX_PATCHLEVEL_VERSION
constants.


Supported HTTP versions
-----------------------

Supported HTTP versions are 1.0 and 1.1:

	typedef enum http_versions {
	        HTTP_1_0,
	        HTTP_1_1
	} http_version_t;

The version of the client can be found in req->http_version.



HTTP methods
------------

The HTTP method used by the client can be found in req->http_method:

	typedef enum http_methods {
	        METHOD_NONE,
	        METHOD_GET,
	        METHOD_HEAD,
	        METHOD_POST,
	        METHOD_PUT
	} http_method_t;


TUX actions
-----------

The following 'actions' can be taken by the TUX subsystem:

	enum user_req {
		TUX_ACTION_STARTUP = 1,
		TUX_ACTION_SHUTDOWN = 2,
		TUX_ACTION_STARTTHREAD = 3,
		TUX_ACTION_STOPTHREAD = 4,
		TUX_ACTION_EVENTLOOP = 5,
		TUX_ACTION_GET_OBJECT = 6,
		TUX_ACTION_SEND_OBJECT = 7,
		TUX_ACTION_READ_OBJECT = 8,
		TUX_ACTION_FINISH_REQ = 9,
		TUX_ACTION_REGISTER_MODULE = 10,
		TUX_ACTION_UNREGISTER_MODULE = 11,
		TUX_ACTION_CURRENT_DATE = 12,
		MAX_TUX_ACTION
	};

TUX_ACTION_STARTUP (1):

  - The TUX subsystem is started up.  A valid req->thread_nr should be
    provided, preferably 0.  Startup succeeds only if TUX is not started
    up already.

TUX_ACTION_SHUTDOWN (2):

  - The TUX subsystem is being stopped.  A valid req->thread_nr should
    be provided, preferably 0.  A shutdown can only happen if all threads
    have stopped already.


TUX_ACTION_STARTTHREAD (3):

  - The current process is used as a new TUX thread.  A valid and unique
    req->thread_nr should be provided.


TUX_ACTION_STOPTHREAD (4):

  - The current process is being deregistered as a TUX thread.


TUX_ACTION_EVENTLOOP (5):

  - The module instructs the TUX subsystem to enter the event-loop.
    The TUX subsystem will wait for incoming requests or nonblocked
    signals, and will execute no user-space code meanwhile.


TUX_ACTION_GET_OBJECT (6):

  - Access a TUX object identified by the req->objectname string.  This
    is usually a file.  Note that if the file is not available in the
    TUX object cache, TUX might decide to reschedule another request.

    A TUX object is a data stream that is accessed via a URL and is
    directly associated with a file pointed to by that URL.  (In the
    future, we may extend the concept of a TUX object.)


TUX_ACTION_SEND_OBJECT (7):

  - Send an object to the client as-is.  The object must first be fetched
    via TUX_ACTION_GET_OBJECT.


TUX_ACTION_READ_OBJECT (8):

  - Read an object into the user-space buffer identified by
    req->object_addr.


TUX_ACTION_FINISH_REQ (9):

  - Signal to the TUX subsystem that the module is done processing this
    request.


TUX_ACTION_REGISTER_MODULE (10):

  - Register a user-space module identified by the req->modulename string.
    One VFS name can be registered only once.

    req->version_major, req->version_minor and req->version_patch have to
    be set appropriately from TUX_MAJOR_VERSION, TUX_MINOR_VERSION, and
    TUX_PATCHLEVEL_VERSION, respectively; the kernel will sanity-check
    binary compatibility of the module.


TUX_ACTION_UNREGISTER_MODULE (11):

  - Unregister a user-space module identified by the req->modulename
    string.  Only registered modules can be unregistered.


TUX_ACTION_CURRENT_DATE (12):

  - Set a new day/time string used by the TUX subsystem via
    req->new_date.


TUX kernel-space subsystem return codes
---------------------------------------

When a user-space TUX module calls the kernel-space TUX subsystem,
either a non-negative or a negative integer value is returned.  A
negative return value means the apropriate error code.

A non-negative integer return code should be interpreted by the
module as:

	enum http_ret {
		TUX_RETURN_USERSPACE_REQUEST = 0,
		TUX_RETURN_EXIT = 1,
		TUX_RETURN_SIGNAL = 2,
	};

TUX_RETURN_USERSPACE_REQUEST:

  - A new user-space request is provided by the kernel-space
    TUX subsystem.


TUX_RETURN_EXIT:

  - The TUX kernel-space subsystem has exited.


TUX_RETURN_SIGNAL:

  - A signal has been received, no new request is scheduled.


Constants 
---------

	#define MAX_MODULENAME_LEN 16

Maximum user-space module name length.

	#define MAX_URI_LEN 256

Maximum URI name length supported.

	#define MAX_POST_DATA 1024

Maximum incoming data buffer length.

	#define MAX_COOKIE_LEN 128

Maximum cookie length.

	#define DATE_LEN 30


The request structure
---------------------

The user-space request structure is the main communication structure
towards the kernel-space TUX subsystem.

typedef struct user_req_s {
	int version_major;
	int version_minor;
	int version_patch;

	int http_version;
	int http_method;
	int sock;
	int bytes_sent;
	int http_status;
	unsigned int client_host;
	unsigned int objectlen;
	char query[MAX_URI_LEN];
	char *object_addr;
	char objectname[MAX_URI_LEN];
	int module_index;
	char modulename[MAX_MODULENAME_LEN];
	char post_data[MAX_POST_DATA];
	char new_date[DATE_LEN];

	int cookies_len;
	char cookies[MAX_COOKIE_LEN];

	int event;
	int thread_nr;
	void *id;
	void *private;

} user_req_t;

Copyright 2000 Red Hat, Inc.