.\" 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 "DC_PLUG_NEW 2"
.TH DC_PLUG_NEW 2 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
DC_PLUG_new, DC_PLUG_free, DC_PLUG_to_select, DC_PLUG_io \- basic DC_PLUG functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <distcache/dc_plug.h>
.Ve
.PP
.Vb 4
\& DC_PLUG *DC_PLUG_new(NAL_CONNECTION *conn, unsigned int flags);
\& int DC_PLUG_free(DC_PLUG *plug);
\& void DC_PLUG_to_select(DC_PLUG *plug, NAL_SELECTOR *sel);
\& int DC_PLUG_io(DC_PLUG *plug, NAL_SELECTOR *sel);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIDC_PLUG_new()\fR allocates and initialises a \fB\s-1DC_PLUG\s0\fR structure encapsulating the
specified connection. The \fBflags\fR parameter is zero or a bitmask combining one or
more of the following flags;
.PP
.Vb 2
\& #define DC_PLUG_FLAG_TO_SERVER         (unsigned int)0x0001
\& #define DC_PLUG_FLAG_NOFREE_CONN       (unsigned int)0x0002
.Ve
.PP
If the \fI\s-1DC_PLUG_FLAG_TO_SERVER\s0\fR flag is specified, the plug object will expect
to be sending ``request'' messages and receiving ``response'' messages,
otherwise will default to the opposite sense.
.PP
\&\fIDC_PLUG_free()\fR frees the \fB\s-1DC_PLUG\s0\fR structure and, unless it had been created
with the \fI\s-1DC_PLUG_FLAG_NOFREE_CONN\s0\fR flag, will also destroy the connection
object it encapsulates.
.PP
\&\fIDC_PLUG_to_select()\fR is used to add a plug object to the \fBsel\fR selector so that
it can be tested for network events it is waiting on. This will automatically
handle selection of flags depending on the plug object's state. Ie. it will
select for writability on its underlying connection only if there is data
waiting to be sent, and likewise will select for readability only if it is
ready to receive any data that may have arrived.
.PP
\&\fIDC_PLUG_io()\fR is used to allow network I/O to be performed on a plug object's
underlying connection depending on the results of the last select operation on
\&\fBsel\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDC_PLUG_new()\fR returns the new plug object on success, otherwise \fB\s-1NULL\s0\fR for
failure.
.PP
\&\fIDC_PLUG_free()\fR should never fail and should only return non-zero results.
.PP
\&\fIDC_PLUG_to_select()\fR has no return value.
.PP
\&\fIDC_PLUG_io()\fR return zero on an error, otherwise non\-zero.
.PP
None of the \fB\s-1DC_PLUG\s0\fR functions sets (or clears) \fBerrno\fR because it is
implemented on top of the \fIlibnal\fR library which in turn is an abstraction
layer for the system's networking interfaces. As such, any \fBerrno\fR codes set
by failure in system libraries will not be overwritten by these functions.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIDC_PLUG_read\fR\|(2) \- Provides documentation for other \fB\s-1DC_PLUG\s0\fR
functions also.
.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