.nf
.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_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
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
.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 the 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
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