SYNOPSIS

    #include "libut/ut.h"
    int UT_fd_reg(int fd, char *name, UT_fd_cb *cb, void *data, int flags, ...);

DESCRIPTION

This function registers the file descriptor fd to be monitored in the libut event loop, such that when it becomes readable and/or writable, the I/O callback cb will be invoked. (See the THE CALLBACK below).

The I/O conditions and further contextual information about the file descriptor are specified by the flags and the subsequent variable-length argument list. (See the FLAGS section below).

The name is meant to convey the purpose of the file descriptor. It is used in log messages and the output of the control port fds command.

If this function is called for a previously-registered file descriptor, it updates the registration information.

When a file descriptor that has been registered using this function is no longer needed, UT_fd_unreg(3) should be called after closing it.

FLAGS

The flags argument is a logically-OR'd combination of the following bits.

Note: It is mandatory that at least UTFD_R or UTFD_W be specified. All other bit flags are optional, and are used to enhance readability of log messages and of the output of the control port fds command.

UTFD_R: Invoke cb when file descriptor is readable.
UTFD_W: Invoke cb when file descriptor is writable.
UTFD_PIPE: The file descriptor applies to a pipe.
UTFD_SOCKET: The file descriptor applies to a socket. This bit flag can optionally be further OR'd with one of the four disposition flags UTFD_SOCKET_LISTENING, UTFD_SOCKET_ACCEPTED, UTFD_SOCKET_CONNECTING, or UTFD_SOCKET_CONNECTED. (These disposition flags can be altered later using UT_fd_cntl(3).); Two more flags that apply to sockets are UTFD_SOCKET_LOCALADDR and UTFD_SOCKET_REMOTEADDR. If either or both of these are set, the final variable-length arguments for this function consist of the localaddr and remoteaddr arguments (which must be in that order if both are present). These are both strings of the form ``ip:port'', e.g., ``127.0.0.1:8000'', specifying the IP address and port number of the local and/or remote side of the socket.
UTFD_OTHER: The file descriptor applies to neither a pipe nor socket.

THE CALLBACK

The I/O callback must have this prototype: int (UT_fd_cb)(int fd, char *name, int status, void *data);

The fd, name and data arguments are passed to the callback exactly as they were passed to UT_fd_reg(). The status argument informs the callback of the disposition of the file descriptor using the following bits:

UTFD_IS_READABLE: The file descriptor is readable. (This can also indicate EOF).
UTFD_IS_WRITABLE: The file descriptor is writable. (This is only set if the file descriptor is being monitored for writability. In most cases it is not necessary to do this; use UT_fd_write(3) and it will handle this).

The callback's return value is ignored.

RETURN VALUE

This function always returns 0.

RELATED CONTROL PORT COMMANDS

The fds control port command lists information about the registered file descriptors.

NOTES

I/O callbacks are one of the two main mechanisms by which libut-based servers do their work. (The other mechanism is timer callbacks, established using UT_tmr_set(3).) In this type of event-driven framework, callbacks should not run for too long before returning, otherwise servicing of other events may become delayed.

AUTHOR

Troy D. Hanson <thanson@users.sourceforge.net>