tux - interact with the TUX kernel subsystem
SYNOPSIS
#include <sys/tuxmodule.h>
int tux (unsigned int action, user_req_t * req);
DESCRIPTION
The tux() system call calls the kernel to perform an
action on behalf of the currently executing user-space TUX
module.
action can be one of:
enum tux_actions {
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_FINISH_CLOSE_REQ = 10,
TUX_ACTION_REGISTER_MODULE = 11,
TUX_ACTION_UNREGISTER_MODULE = 12,
TUX_ACTION_CURRENT_DATE = 13,
TUX_ACTION_REGISTER_MIMETYPE = 14,
TUX_ACTION_READ_HEADERS = 15,
TUX_ACTION_POSTPONE_REQ = 16,
TUX_ACTION_CONTINUE_REQ = 17,
TUX_ACTION_REDIRECT_REQ = 18,
TUX_ACTION_READ_POST_DATA = 19,
MAX_TUX_ACTION
};
The first action values listed below are administrative
and are normally used only in the tux program.
TUX_ACTION_STARTUP starts the tux subsystem, and takes a
NULL req. TODO: Only root can use TUX_ACTION_STARTUP.
TUX_ACTION_SHUTDOWN stops the tux subsystem, and takes any
req, even a zero-filled req.
TUX_ACTION_STARTTHREAD is called once per thread with a
req->thread_nr element monotonically increasing from 0.
TUX_ACTION_STOPTHREAD is not currently used by the tux
daemon because all threads are automatically stopped on
TUX_ACTION_SHUTDOWN. It remains available because it may
be useful in circumstances that the tux daemon does not
yet handle.
identified by the req->modulename string. One VFS name
can be registered only once.
req->version_major, req->version_minor, and req->ver
sion_patch have to be set appropriately from
TUX_MAJOR_VERSION, TUX_MINOR_VERSION, and TUX_PATCH
LEVEL_VERSION, respectively; the kernel will sanity-check
binary compatibility of the module.
TUX_ACTION_UNREGISTER_MODULE Unregister a user-space mod
ule identified by the req->modulename string. Only regis
tered modules can be unregistered.
TUX_ACTION_CURRENT_DATE Set the current date string to
req->new_date. The date string must be RFC 1123-compliant
and increase monotonically. The tux daemon normally calls
this once per second.
TUX_ACTION_REGISTER_MIMETYPE Sets the extension
req->objectname to map to mimetype req->object_addr. The
tux daemon normally registers the mime types in
/etc/tux.mime.types, but modules could conceivably create
their own mimetype mappings.
The rest of the action values are used to respond to TUX
events. The general architecture is that TUX's event loop
is invoked to catch HTTP events, and then responses are
generated in response to those events.
TUX_ACTION_EVENTLOOP invokes the TUX event loop--the TUX
subsystem will either immediately return with a new
request req, or will wait for new requests to arrive.
TUX_ACTION_GET_OBJECT issues a request for the URL object
named in req->objectname. If the object is not immediately
available then the currently handled request is suspended,
and a new request is returned, or the TUX subsystem waits
for new requests.
A URL 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 URL
object.)
TUX_ACTION_SEND_OBJECT sends the current URL object to the
client.
TUX_ACTION_READ_OBJECT reads the current URL object into
the address specified by req->object_addr.
TUX_ACTION_READ_OBJECT must not be called unless
req->objectlen >= 0.
into req->object_addr, with the length of the string kept
in req->objectlen. This is a workaround used to read
fields that tux does not currently parse; if you need it,
report it as a bug so that more fields can be added to
user_req (unless your use is so specialized that it will
be of no general utility).
TUX_ACTION_POSTPONE_REQ postpones the request, meaning
that no tux system calls will return data for this request
until TUX_ACTION_CONTINUE_REQ is called.
TUX_ACTION_CONTINUE_REQ continues a postponed request.
Unlike a normal TUX_ACTION, it takes as its argument the
socket descriptor (this allows it to be called from a pro
gram that is unrelated to the program that called
TUX_ACTION_POSTPONE_REQ if necessary). It is called like
this:
ret = tux(TUX_ACTION_CONTINUE_REQ, (user_req_t *)socket);
TUX_ACTION_READ_POST_DATA is an atomic action (it will
always return with the same request, no need to handle a
new request) that puts the non-zero-delimited POST data,
up to the maximum set in req->objectlen (and limited by
/proc/sys/net/tux/max_header_len), into req->object_addr,
ands resets req->objectlen to the length.
TUX_ACTION_REDIRECT_REQ causes the request to be redi
rected to the secondary server. (No need to call
TUX_ACTION_FINISH_REQ.)
TUX_ACTION_FINISH_REQ finishes and logs the request.
TUX_ACTION_FINISH_CLOSE_REQ is like TUX_ACTION_FINISH_REQ
except that it also closes HTTP 1.1 keepalive connections.
user_req_t req is the request returned by the TUX subsys
tem. Defined fields are:
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 post_data[MAX_POST_DATA];
int cookies_len;
char cookies[MAX_COOKIE_LEN];
int event;
int thread_nr;
void *id;
void *private;
} user_req_t;
version_major
Always set to TUX_MAJOR_VERSION,
used to flag binary incompatibility. version_minor
Always set to TUX_MINOR_VERSION, used to flag
binary incompatibility.
version_patch
Always set to TUX_PATCHLEVEL_VERSION, used to flag
binary incompatibility.
http_version
One of HTTP_1_0 or HTTP_1_1
http_method
One of METHOD_NONE, METHOD_GET, METHOD_HEAD,
METHOD_POST, or METHOD_PUT
sock Socket file descriptor; writing to this will send
data to the connected client associated with this
request. Do not read from this socket file
descriptor; you could potentially confuse the HTTP
engine.
bytes_sent
When you write to sock, you must set bytes_sent to
the total number of bytes sent since the last tux()
operation on this req, or the log entry's bytes
sent counter will be incorrect. (This may change
or disappear in future versions of tux.)
http_status
Set the error status as an integer for error
reporting. The status is good by default, so it
should not be modified except to report errors.
client_host
The IP address of the host to which sock is con
nected.
objectlen
The size of a file that satisfies the current
cache. This is set if a request returns after
TUX_ACTION_GET_OBJECT. A module should make sure
that the buffer at req->object_addr is at least
req->objectlen in size before calling
TUX_ACTION_READ_OBJECT.
query The full query string sent from the client.
object_addr
Set to an address for a buffer of at least
req->objectlen size into which to read an object
from the URL cache with the TUX_ACTION_READ_OBJECT
action. TUX_ACTION_READ_OBJECT must not be called
unless req->objectlen >= 0, and TUX implicitly
relies on req->object_addr being at least
req->objectlen in size.
objectname
Specifies the name of a URL to get with the
TUX_ACTION_GET_OBJECT action. If the URL is not
immediately available (that is, is not in the URL
cache), the request is queued and the tux subsystem
may go on to other ready requests while waiting.
module_index
Used by the tux(8) daemon to determine which load
able module to associate with a req.
modulename
The name of the module as set by TUX_ACTION_REGIS
TER_MODULE; private data to the tux daemon.
post_data
For POST requests, the incoming data is placed in
post_data.
cookies_len
If cookies are in the request header, cookies_len
contains the length of the cookies string
cookies
If cookies are in the request header, cookies is
the string in which the cookies are passed to the
module.
event Private, per-request state for use in tux modules.
The system will preserve this value as long as a
request is active.
thread_nr
Thread index; see discussion of TUX_ACTION_START
THREAD.
plex requests to the correct modules.
private
Works just like event, except that it is a pointer
to private data instead of an integer.
RETURN VALUE
tux() returns the following values:
enum tux_reactions {
TUX_RETURN_USERSPACE_REQUEST = 0,
TUX_RETURN_EXIT = 1,
TUX_RETURN_SIGNAL = 2,
};
TUX_RETURN_USERSPACE_REQUEST means that the kernel has put
a new request into req; the request must be responded to
with one of TUX_ACTION_GET_OBJECT, TUX_ACTION_SEND_OBJECT,
TUX_ACTION_READ_OBJECT, or TUX_ACTION_FINISH_REQ.
TUX_RETURN_EXIT means that TUX has been stopped.
TUX_RETURN_SIGNAL means that a signal has occured. No new
request is scheduled.
ERRORS
Any negative value (such as -EFAULT, -EINVAL) is an indi
cation of an error.
BUGS
This man page is incomplete.
Man(1) output converted with
man2html