X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/ff76c38f2d94c82b234d67e717d855b52e5d6421..4a0b387cc66628ea8bab3a5b3da1d8790d98d0ee:/man/conn.3

diff --git a/man/conn.3 b/man/conn.3
index 5a12b7a..1c91193 100644
--- a/man/conn.3
+++ b/man/conn.3
@@ -1,5 +1,6 @@
 .\" -*-nroff-*-
-.TH conn 3 "23 May 1999" mLib
+.TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @conn_fd
 .\" @conn_init
 .\" @conn_kill
 .SH NAME
@@ -8,10 +9,14 @@ conn \- selector for nonblocking connections
 .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_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
@@ -51,7 +56,7 @@ an error, the descriptor will be closed.
 Pointer to destination socket address for the connection.  Make sure
 that the address has the right family.
 .TP
-.BI "int " dsz 
+.BI "int " dsz
 Size of the destination socket address.
 .TP
 .BI "void (*" func ")(int " fd ", void *" p )
@@ -61,15 +66,51 @@ 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
 .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
@@ -79,4 +120,4 @@ the selector becomes safe to be discarded.
 .BR sel (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>