.\" -*-nroff-*-
-.TH conn 3mLib "23 May 1999" mLib
+.TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @conn_fd
+.\" @conn_init
+.\" @conn_kill
.SH NAME
conn \- selector for nonblocking connections
.SH SYNOPSIS
.nf
-.B "#include <mLib/conn.h>
+.B "#include <mLib/conn.h>"
-.BI "void conn_init(conn *" c ", sel_state *" s ", int " fd ,
-.BI " struct sockaddr *" dst ", int " dsz ,
-.BI " void (*" func ")(int " fd ", void *" p ),
-.BI " void *" p );
+.BI "int conn_fd(conn *" c ", sel_state *" s ", int " fd ,
+.BI " void (*" func ")(int " fd ", void *" p ),
+.BI " void *" p );
+
+.BI "int conn_init(conn *" c ", sel_state *" s ", int " fd ,
+.BI " struct sockaddr *" dst ", int " dsz ,
+.BI " void (*" func ")(int " fd ", void *" p ),
+.BI " void *" p );
.BI "void conn_kill(conn *" c );
.fi
.B conn_init
with a fairly large number of arguments:
.TP
-.I c
+.BI "conn *" c
Pointer to
.B conn
object which needs to be initialized.
.TP
-.I s
+.BI "sel_state *" s
Pointer to a multiplexor object (type
.BR sel_state )
to which this selector should be attached. See
-.BR sel (3mLib)
+.BR sel (3)
for more details about multiplexors, and how this whole system works.
.TP
-.I fd
+.BI "int " fd
File descriptor for the socket you want to connect. This becomes the
`property' of the
.B conn
selector until the connection attempt finishes. For example, if there's
an error, the descriptor will be closed.
.TP
-.I dst
+.BI "struct sockaddr *" dst
Pointer to destination socket address for the connection. Make sure
that the address has the right family.
.TP
-.I dsz
+.BI "int " dsz
Size of the destination socket address.
.TP
-.I func
+.BI "void (*" func ")(int " fd ", void *" p )
A function to call when the connection is complete. It is passed the
file descriptor of the connected socket, and the pointer passed
to
.B conn_init
as the
.I p
-argument. If the connection failed, a file descriptor value of \-1 is
-passed, and the global
-.B errno
-value is set appropriately.
+argument.
.TP
-.I p
+.BI "void *" p
An arbitrary pointer whose value is passed to the handler function when
the connection finishes.
.PP
+A few words are in order about
+.BR conn_init 's
+detailed behaviour and return value. If it returns \-1, the connection
+attempt has failed immediately, an error code is stored in the global
+variable
+.BR errno ,
+the file descriptor has been
+.IR closed ,
+and the connection function will
+.I not
+be called. If it returns zero, then there has been no immediate
+failure; the connection function
+.I might
+have been called, if the connection succeeded immediately, but it will
+certainly be called some time, unless the connector is killed (see
+.B conn_kill
+below). When the connection function is called, it will either be
+passed the file descriptor of the new-connected socket (to indicate
+success) or the value \-1 for failure; in the latter case, an
+appropriate error code is stored in
+.BR errno .
+.PP
+Alternatively, if you have a socket with a pending connection (i.e., a
+call to
+.BR connect
+returned \-1 and set
+.B errno
+to
+.BR EINPROGRESS ),
+you can call
+.BR conn_fd.
+Its arguments are the same as for
+.BR conn_init ,
+except that since the socket knows its a peer address the
+.I dst
+and
+.I dsz
+arguments are not given, and it can't fail.
+.PP
If you want to cancel the connection attempt before it finishes, call
.B conn_kill
with the address of the selector. The file descriptor is closed, and
the selector becomes safe to be discarded.
+.SH "SEE ALSO"
+.BR connect (2),
+.BR sel (3),
+.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blobdiff