.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NAL_SELECTOR_NEW 2"
.TH NAL_SELECTOR_NEW 2 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
NAL_SELECTOR_new, NAL_SELECTOR_free, NAL_SELECTOR_select \- libnal selector functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <libnal/nal.h>
.Ve
.PP
.Vb 4
\& NAL_SELECTOR *NAL_SELECTOR_new(void);
\& void NAL_SELECTOR_free(NAL_SELECTOR *sel);
\& int NAL_SELECTOR_select(NAL_SELECTOR *sel, unsigned long usec_timeout,
\&                         int use_timeout);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINAL_SELECTOR_new()\fR allocates and initialises a new \fB\s-1NAL_SELECTOR\s0\fR object.
.PP
\&\fINAL_SELECTOR_free()\fR destroys a \fB\s-1NAL_SELECTOR\s0\fR object.
.PP
\&\fINAL_SELECTOR_select()\fR blocks until the selector \fBsel\fR 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 \fBuse_timeout\fR is non\-zero, then the function will break if more than
\&\fBusec_timeout\fR microseconds have passed. See \*(L"\s-1NOTES\s0\*(R".
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fINAL_SELECTOR_new()\fR returns a valid \fB\s-1NAL_SELECTOR\s0\fR object on success, \s-1NULL\s0
otherwise.
.PP
\&\fINAL_SELECTOR_free()\fR has no return value.
.PP
\&\fINAL_SELECTOR_select()\fR 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).
.SH "NOTES"
.IX Header "NOTES"
The \fB\s-1NAL_SELECTOR\s0\fR allows the caller to register \fB\s-1NAL_CONNECTION\s0\fR and
\&\fB\s-1NAL_LISTENER\s0\fR objects for any events appropriate to them and then block
execution with \fINAL_SELECTOR_select()\fR until there are events that need
processing. The exact semantics \fINAL_CONNECTION_add_to_selector()\fR and
\&\fINAL_LISTENER_add_to_selector()\fR are documented in other manual pages, see
\&\*(L"\s-1NOTES\s0\*(R".
.PP
The behaviour of \fINAL_SELECTOR_select()\fR is what one would normally expect from a
system \fIselect\fR\|(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 \fBuse_timeout\fR
was specified, or if a unblocked signal arrived. In such cases, subsequent
calls to \fINAL_CONNECTION_io()\fR and \fINAL_LISTENER_accept()\fR will trivially return
without performing any actions as the selector has no events registered for
processing. As such, if \fINAL_SELECTOR_select()\fR returns zero, it is generally
advised to add the connections and listeners back to the selector object and
call \fINAL_SELECTOR_select()\fR again.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fINAL_ADDRESS_new\fR\|(2) \- Functions for the \s-1NAL_ADDRESS\s0 type.
.PP
\&\fINAL_CONNECTION_new\fR\|(2) \- Functions for the \s-1NAL_CONNECTION\s0 type.
.PP
\&\fINAL_LISTENER_new\fR\|(2) \- Functions for the \s-1NAL_LISTENER\s0 type.
.PP
\&\fINAL_BUFFER_new\fR\|(2) \- Functions for the \s-1NAL_BUFFER\s0 type.
.PP
\&\fIdistcache\fR\|(8) \- Overview of the distcache architecture.
.PP
\&\fIhttp://www.distcache.org/\fR \- Distcache home page.
.SH "AUTHOR"
.IX Header "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 \fIgeoff@geoffthorpe.net\fR.
.PP
Home Page: \fIhttp://www.distcache.org\fR