NAME

NAL_SELECTOR_new, NAL_SELECTOR_free, NAL_SELECTOR_reset, NAL_SELECTOR_select - libnal selector functions

SYNOPSIS

 #include <libnal/nal.h>

 NAL_SELECTOR *NAL_SELECTOR_new(void);
 void NAL_SELECTOR_free(NAL_SELECTOR *sel);
 void NAL_SELECTOR_reset(NAL_SELECTOR *sel);
 int NAL_SELECTOR_select(NAL_SELECTOR *sel, unsigned long usec_timeout,
                         int use_timeout);

DESCRIPTION

NAL_SELECTOR_new() allocates and initialises a new NAL_SELECTOR object.

NAL_SELECTOR_free() destroys a NAL_SELECTOR object.

NAL_SELECTOR_reset() will, if necessary, cleanup any prior state in sel. The resulting object will be in the same state returned from NAL_SELECTOR_new().

NAL_SELECTOR_select() blocks until the selector sel receives notification of network events for which it has registered interest. This function blocks indefinitely until receipt of a network event, interruption by the system, or if use_timeout is non-zero, then the function will break if more than usec_timeout microseconds have passed. See "NOTES".

RETURN VALUES

NAL_SELECTOR_new() returns a valid NAL_SELECTOR object on success, NULL otherwise.

NAL_SELECTOR_free() has no return value.

NAL_SELECTOR_select() returns negative for an error, otherwise it returns the number of connections and/or listeners that the selector has detected have network events waiting (which can be zero).

NOTES

The NAL_SELECTOR allows the caller to register NAL_CONNECTION and NAL_LISTENER objects for any events appropriate to them and then block execution with NAL_SELECTOR_select() until there are events that need processing. The exact semantics NAL_CONNECTION_add_to_selector() and NAL_LISTENER_add_to_selector() are documented in other manual pages, see "NOTES".

The behaviour of NAL_SELECTOR_select() is what one would normally expect from a system select(2) function. On error, the return value is negative. Otherwise the return value is the number of connection and/or listener objects that have network events waiting for them. A return value of zero is possible if the function breaks before any network events have arrived, eg. if use_timeout was specified, or if a unblocked signal arrived. In such cases, subsequent calls to NAL_CONNECTION_io() and NAL_LISTENER_accept() will trivially return without performing any actions as the selector has no events registered for processing. As such, if NAL_SELECTOR_select() returns zero, it is generally advised to add the connections and listeners back to the selector object and call NAL_SELECTOR_select() again.

As with other libnal functions, `errno' is not touched so that any errors in the system's underlying implementations can be investigated directly by the calling application.

AUTHOR

This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances Incorporated. Since the project was released into open source, it has a home page and a project environment where development, mailing lists, and releases are organised. For problems with the software or this man page please check for new releases at the project web-site below, mail the users mailing list described there, or contact the author at geoff@geoffthorpe.net.