Add global unihash table; use universal hashing instead of CRC.

[mLib] / man / conn.3

diff --git a/man/conn.3 b/man/conn.3
index 60c951008b45c3763608ba5d0d27d4dbce87f1ad..74a4604b3824fc2a66f61481d54a041d3f0abbf6 100644 (file)
--- a/man/conn.3
+++ b/man/conn.3
@@ -1,15 +1,22 @@
 .\" -*-nroff-*-
 .\" -*-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
 .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
 
 .BI "void conn_kill(conn *" c );
 .fi


@@ -26,51 +33,91 @@ selector must be initialized.  This requires a call to
 .B conn_init
 with a fairly large number of arguments:
 .TP
 .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
 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
 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
 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
 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
 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
 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
 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
 .TP

-.I p
+.BI "void *" p

 An arbitrary pointer whose value is passed to the handler function when
 the connection finishes.
 .PP
 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.
 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>
 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>