chiark / gitweb /
Declare and document @conn_fd@.
authormdw <mdw>
Sat, 29 Nov 2003 19:10:53 +0000 (19:10 +0000)
committermdw <mdw>
Sat, 29 Nov 2003 19:10:53 +0000 (19:10 +0000)
conn.h
man/conn.3

diff --git a/conn.h b/conn.h
index d520a6f..d381850 100644 (file)
--- a/conn.h
+++ b/conn.h
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: conn.h,v 1.6 2001/06/22 19:35:20 mdw Exp $
+ * $Id: conn.h,v 1.7 2003/11/29 19:10:53 mdw Exp $
  *
  * Nonblocking connect handling
  *
@@ -30,6 +30,9 @@
 /*----- Revision history --------------------------------------------------* 
  *
  * $Log: conn.h,v $
+ * Revision 1.7  2003/11/29 19:10:53  mdw
+ * Declare and document @conn_fd@.
+ *
  * Revision 1.6  2001/06/22 19:35:20  mdw
  * Interface change to @conn_init@ -- return error rather than calling the
  * function.  This reduces the number of different environments the
@@ -83,6 +86,24 @@ typedef struct conn {
 
 /*----- Functions provided ------------------------------------------------*/
 
+/* --- @conn_fd@ --- *
+ *
+ * Arguments:  @conn *c@ = pointer to connection block
+ *             @sel_state *s@ = pointer to select state to attach to
+ *             @int fd@ = file descriptor of socket
+ *             @void (*func)(int fd, void *p) = handler function
+ *             @void *p@ = argument for the handler function
+ *
+ * Returns:    ---
+ *
+ * Use:                Sets up a nonblocking connect job.  The socket should have a
+ *             connect pending for it already.
+ */
+
+void conn_fd(conn */*c*/, sel_state */*s*/, int /*fd*/,
+            void (*/*func*/)(int /*fd*/, void */*p*/),
+            void */*p*/);
+
 /* --- @conn_init@ --- *
  *
  * Arguments:  @conn *c@ = pointer to connection block
index 3ecc43f..74a4604 100644 (file)
@@ -1,5 +1,6 @@
 .\" -*-nroff-*-
 .TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @conn_fd
 .\" @conn_init
 .\" @conn_kill
 .SH NAME
@@ -8,6 +9,10 @@ conn \- selector for nonblocking connections
 .nf
 .B "#include <mLib/conn.h>"
 
+.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 ),
@@ -69,10 +74,10 @@ 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 ),
+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
@@ -89,6 +94,23 @@ 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