1TUX(2) System calls TUX(2)
2
6 tux - interact with the TUX kernel subsystem
7
9 #include <sys/tuxmodule.h>
10 int tux (unsigned int action, user_req_t * req);
12
14 The tux() system call calls the kernel to perform an action on behalf
15 of the currently executing user-space TUX module.
16 action can be one of:
18 enum tux_actions {
19 TUX_ACTION_STARTUP = 1,
20 TUX_ACTION_SHUTDOWN = 2,
21 TUX_ACTION_STARTTHREAD = 3,
22 TUX_ACTION_STOPTHREAD = 4,
23 TUX_ACTION_EVENTLOOP = 5,
24 TUX_ACTION_GET_OBJECT = 6,
25 TUX_ACTION_SEND_OBJECT = 7,
26 TUX_ACTION_READ_OBJECT = 8,
27 TUX_ACTION_FINISH_REQ = 9,
28 TUX_ACTION_FINISH_CLOSE_REQ = 10,
29 TUX_ACTION_REGISTER_MODULE = 11,
30 TUX_ACTION_UNREGISTER_MODULE = 12,
31 TUX_ACTION_CURRENT_DATE = 13,
32 TUX_ACTION_REGISTER_MIMETYPE = 14,
33 TUX_ACTION_READ_HEADERS = 15,
34 TUX_ACTION_POSTPONE_REQ = 16,
35 TUX_ACTION_CONTINUE_REQ = 17,
36 TUX_ACTION_REDIRECT_REQ = 18,
37 TUX_ACTION_READ_POST_DATA = 19,
38 TUX_ACTION_SEND_BUFFER = 20,
39 TUX_ACTION_WATCH_PROXY_SOCKET = 21,
40 TUX_ACTION_WAIT_PROXY_SOCKET = 22,
41 TUX_ACTION_QUERY_VERSION = 23,
42 MAX_TUX_ACTION
43 };
44 The first action values listed below are administrative and are nor‐
46 mally used only in the tux program.
47 TUX_ACTION_STARTUP starts the tux subsystem, and takes a NULL req.
49 TODO: Only root can use TUX_ACTION_STARTUP.
50 TUX_ACTION_SHUTDOWN stops the tux subsystem, and takes any req, even a
52 zero-filled req.
53 TUX_ACTION_STARTTHREAD is called once per thread with a req->thread_nr
55 element monotonically increasing from 0.
56 TUX_ACTION_STOPTHREAD is not currently used by the tux daemon because
58 all threads are automatically stopped on TUX_ACTION_SHUTDOWN. It
59 remains available because it may be useful in circumstances that the
60 tux daemon does not yet handle.
61 TUX_ACTION_REGISTER_MODULE Register a user-space module identified by
63 the req->modulename string. One VFS name can be registered only once.
64 req->version_major, req->version_minor, and req->version_patch have to
66 be set appropriately from TUX_MAJOR_VERSION, TUX_MINOR_VERSION, and
67 TUX_PATCHLEVEL_VERSION, respectively; the kernel will sanity-check
68 binary compatibility of the module.
69 TUX_ACTION_UNREGISTER_MODULE Unregister a user-space module identified
71 by the req->modulename string. Only registered modules can be unregis‐
72 tered.
73 TUX_ACTION_CURRENT_DATE Set the current date string to req->new_date.
75 The date string must be RFC 1123-compliant and increase monotonically.
76 The tux daemon normally calls this once per second.
77 TUX_ACTION_REGISTER_MIMETYPE Sets the extension req->objectname to map
79 to mimetype req->object_addr. The tux daemon normally registers the
80 mime types in /etc/tux.mime.types, but modules could conceivably create
81 their own mimetype mappings.
82 TUX_ACTION_QUERY_VERSION Return the major version, minor version, and
84 patchlevel of the kernel TUX subsystem, encoded in the return value as
85 (TUX_MAJOR_VERSION << 24) | (TUX_MINOR_VERSION << 16) |
86 TUX_PATCHLEVEL_VERSION
87 If the system call sets errno to EINVAL, assume major version 2, minor
88 version 1.
89 The rest of the action values are used to respond to TUX events. The
92 general architecture is that TUX's event loop is invoked to catch HTTP
93 events, and then responses are generated in response to those events.
94 TUX_ACTION_EVENTLOOP invokes the TUX event loop—the TUX subsystem will
96 either immediately return with a new request req, or will wait for new
97 requests to arrive.
98 TUX_ACTION_GET_OBJECT issues a request for the URL object named in
100 req->objectname. If the object is not immediately available then the
101 currently handled request is suspended, and a new request is returned,
102 or the TUX subsystem waits for new requests.
103 A URL object is a data stream that is accessed via a URL and is
105 directly associated with a file pointed to by that URL. (In the
106 future, we may extend the concept of a URL object.)
107 TUX_ACTION_SEND_OBJECT sends the current URL object to the client.
110 TUX_ACTION_READ_OBJECT reads the current URL object into the address
112 specified by req->object_addr. TUX_ACTION_READ_OBJECT must not be
113 called unless req->objectlen >= 0.
114 TUX_ACTION_READ_HEADERS reads a non-zero-delimited string into
116 req->object_addr, with the length of the string kept in req->objectlen.
117 This is a workaround used to read fields that tux does not currently
118 parse; if you need it, report it as a bug so that more fields can be
119 added to user_req (unless your use is so specialized that it will be of
120 no general utility).
121 TUX_ACTION_POSTPONE_REQ postpones the request, meaning that no tux sys‐
123 tem calls will return data for this request until TUX_ACTION_CON‐
124 TINUE_REQ is called.
125 TUX_ACTION_CONTINUE_REQ continues a postponed request. Unlike a normal
127 TUX_ACTION, it takes as its argument the socket descriptor (this allows
128 it to be called from a program that is unrelated to the program that
129 called TUX_ACTION_POSTPONE_REQ if necessary). It is called like this:
130 ret = tux(TUX_ACTION_CONTINUE_REQ, (user_req_t *)socket);
131 TUX_ACTION_READ_POST_DATA is an atomic action (it will always return
133 with the same request, no need to handle a new request) that puts the
134 non-zero-delimited POST data, up to the maximum set in req->objectlen
135 (and limited by /proc/sys/net/tux/max_header_len), into
136 req->object_addr, ands resets req->objectlen to the length.
137 TUX_ACTION_REDIRECT_REQ causes the request to be redirected to the sec‐
139 ondary server. (No need to call TUX_ACTION_FINISH_REQ.)
140 TUX_ACTION_FINISH_REQ finishes and logs the request.
142 TUX_ACTION_FINISH_CLOSE_REQ is like TUX_ACTION_FINISH_REQ except that
144 it also closes HTTP 1.1 keepalive connections.
145 TUX_ACTION_SEND_BUFFER is like TUX_ACTION_SEND_OBJECT except that it
147 sends whatever is in the req->object_addr buffer. This can be used as
148 a generic output buffer.
149 TUX_ACTION_WATCH_PROXY_SOCKET sets up a non-TUX socket to be used with
151 TUX_ACTION_WAIT_PROXY_SOCKET. The socket must be a network socket. The
152 function is atomic. Repeated calls to this action will replace the pre‐
153 vious proxy socket, so there is no need to deinitialize it. The socket
154 file descriptor must be put into req->object_addr.
155 TUX_ACTION_WAIT_PROXY_SOCKET postpones the current request until there
157 are input packets on the socket that was set up via
158 TUX_ACTION_WATCH_PROXY_SOCKET. The proxy socket has a keepalive timer
159 running. The request will be resumed once there is input activity on
160 the socket - the module can use nonblocking recv() on the socket to
161 process input packets.
162 user_req_t req is the request returned by the TUX subsystem. Defined
164 fields depend on the version. For major version 2, they are:
165 typedef struct user_req_s {
166 int version_major;
167 int version_minor;
168 int version_patch;
169 int http_version;
171 int http_method;
172 int sock;
174 int event;
175 int thread_nr;
176 void *id;
177 void *priv;
178 int http_status;
180 int bytes_sent;
181 char *object_addr;
182 int module_index;
183 char modulename[MAX_MODULENAME_LEN];
184 unsigned int client_host;
186 unsigned int objectlen;
187 char query[MAX_URI_LEN];
188 char objectname[MAX_URI_LEN];
189 unsigned int cookies_len;
191 char cookies[MAX_COOKIE_LEN];
192 char content_type[MAX_FIELD_LEN];
194 char user_agent[MAX_FIELD_LEN];
195 char accept[MAX_FIELD_LEN];
196 char accept_charset[MAX_FIELD_LEN];
197 char accept_encoding[MAX_FIELD_LEN];
198 char accept_language[MAX_FIELD_LEN];
199 char cache_control[MAX_FIELD_LEN];
200 char if_modified_since[MAX_FIELD_LEN];
201 char negotiate[MAX_FIELD_LEN];
202 char pragma[MAX_FIELD_LEN];
203 char referer[MAX_FIELD_LEN];
204 char *post_data;
206 char new_date[DATE_LEN];
207 int keep_alive;
208 } user_req_t;
209 For major version 3, they are:
210 typedef struct user_req_s {
211 uint32_t version_major;
212 uint32_t version_minor;
213 uint32_t version_patch;
214 uint32_t http_version;
215 uint32_t http_method;
216 uint32_t http_status;
217 uint32_t sock;
219 uint32_t event;
220 uint32_t error;
221 uint32_t thread_nr;
222 uint32_t bytes_sent;
223 uint32_t client_host;
224 uint32_t objectlen;
225 uint32_t module_index;
226 uint32_t keep_alive;
227 uint32_t cookies_len;
228 uint64_t id;
230 uint64_t priv;
231 uint64_t object_addr;
232 uint8_t query[MAX_URI_LEN];
234 uint8_t objectname[MAX_URI_LEN];
235 uint8_t cookies[MAX_COOKIE_LEN];
236 uint8_t content_type[MAX_FIELD_LEN];
237 uint8_t user_agent[MAX_FIELD_LEN];
238 uint8_t accept[MAX_FIELD_LEN];
239 uint8_t accept_charset[MAX_FIELD_LEN];
240 uint8_t accept_encoding[MAX_FIELD_LEN];
241 uint8_t accept_language[MAX_FIELD_LEN];
242 uint8_t cache_control[MAX_FIELD_LEN];
243 uint8_t if_modified_since[MAX_FIELD_LEN];
244 uint8_t negotiate[MAX_FIELD_LEN];
245 uint8_t pragma[MAX_FIELD_LEN];
246 uint8_t referer[MAX_FIELD_LEN];
247 uint8_t new_date[DATE_LEN];
248 } user_req_t;
249 version_major
251 Always set to TUX_MAJOR_VERSION, used to flag binary incompati‐
252 bility.
253 version_minor
255 Always set to TUX_MINOR_VERSION, used to flag binary incompati‐
256 bility.
257 version_patch
259 Always set to TUX_PATCHLEVEL_VERSION, used to flag binary incom‐
260 patibility.
261 http_version
263 One of HTTP_1_0 or HTTP_1_1
264 http_method
266 One of METHOD_NONE, METHOD_GET, METHOD_HEAD, METHOD_POST, or
267 METHOD_PUT
268 sock Socket file descriptor; writing to this will send data to the
270 connected client associated with this request. Do not read from
271 this socket file descriptor; you could potentially confuse the
272 HTTP engine.
273 event Private, per-request state for use in tux modules. The system
275 will preserve this value as long as a request is active.
276 thread_nr
278 Thread index; see discussion of TUX_ACTION_STARTTHREAD.
279 id A tux-daemon-internal value that is used to multiplex requests
281 to the correct modules.
282 priv Works just like event, except that it is a pointer to private
284 data instead of an integer.
285 http_status
287 Set the error status as an integer for error reporting. The
288 status is good by default, so it should not be modified except
289 to report errors.
290 bytes_sent
292 When you write to sock, you must set bytes_sent to the total
293 number of bytes sent since the last tux() operation on this req,
294 or the log entry's bytes sent counter will be incorrect. (This
295 may change or disappear in future versions of tux.)
296 object_addr
298 Set to an address for a buffer of at least req->objectlen size
299 into which to read an object from the URL cache with the
300 TUX_ACTION_READ_OBJECT action. TUX_ACTION_READ_OBJECT must not
301 be called unless req->objectlen >= 0, and TUX implicitly relies
302 on req->object_addr being at least req->objectlen in size.
303 module_index
305 Used by the tux(8) daemon to determine which loadable module to
306 associate with a req.
307 modulename
309 The name of the module as set by TUX_ACTION_REGISTER_MODULE;
310 private data to the tux daemon.
311 client_host
313 The IP address of the host to which sock is connected.
314 objectlen
316 The size of a file that satisfies the current request and which
317 is currently living in the URL cache. This is set if a request
318 returns after TUX_ACTION_GET_OBJECT. A module should make sure
319 that the buffer at req->object_addr is at least req->objectlen
320 in size before calling TUX_ACTION_READ_OBJECT.
321 query The full query string sent from the client.
323 objectname
325 Specifies the name of a URL to get with the
326 TUX_ACTION_GET_OBJECT action. If the URL is not immediately
327 available (that is, is not in the URL cache), the request is
328 queued and the tux subsystem may go on to other ready requests
329 while waiting.
330 cookies_len
332 If cookies are in the request header, cookies_len contains the
333 length of the cookies string
334 cookies
336 If cookies are in the request header, cookies is the string in
337 which the cookies are passed to the module.
338 content_type
340 The Content-Type header value for the request
341 user_agent
343 The User-Agent header value for the request
344 accept The Accept header value for the request
346 accept_charset
348 The Accept-Charset header value for the request
349 accept_encoding
351 The Accept-Encoding header value for the request
352 accept_language
354 The Accept-Language header value for the request
355 cache_control
357 The Cache-Control header value for the request
358 if_modified_since
360 The If-Modified-Since header value for the request
361 negotiate
363 The Negotiate header value for the request
364 pragma The Pragma header value for the request
366 referer
368 The Referer header value for the request
369 post_data
371 For POST requests, the incoming data is placed in post_data.
372 new_date
374 Returns the current date/time
375 keep_alive
377 The KeepAlive header value for the request
378
381 tux() returns the following values:
382 enum tux_reactions {
383 TUX_RETURN_USERSPACE_REQUEST = 0,
384 TUX_RETURN_EXIT = 1,
385 TUX_RETURN_SIGNAL = 2,
386 };
387 TUX_RETURN_USERSPACE_REQUEST means that the kernel has put a new
389 request into req; the request must be responded to with one of
390 TUX_ACTION_GET_OBJECT, TUX_ACTION_SEND_OBJECT, TUX_ACTION_READ_OBJECT,
391 or TUX_ACTION_FINISH_REQ.
392 TUX_RETURN_EXIT means that TUX has been stopped.
394 TUX_RETURN_SIGNAL means that a signal has occured. No new request is
396 scheduled.
397
400 Any negative value (such as -EFAULT, -EINVAL) is an indication of an
401 error.
402
405 This man page is incomplete.
406Linux 8 May 2003 TUX(2)