From 5934f1eea5364e8a62b40f09fc41c1fbdf024868 Mon Sep 17 00:00:00 2001
Message-Id: <5934f1eea5364e8a62b40f09fc41c1fbdf024868.1715066721.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Sat, 29 Nov 2003 19:10:53 +0000
Subject: [PATCH] Declare and document @conn_fd@.
Organization: Straylight/Edgeware

From: mdw <mdw>

---
 conn.h     | 23 ++++++++++++++++++++++-
 man/conn.3 | 30 ++++++++++++++++++++++++++----
 2 files changed, 48 insertions(+), 5 deletions(-)

diff --git a/conn.h b/conn.h
index d520a6f..d381850 100644
--- 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
diff --git a/man/conn.3 b/man/conn.3
index 3ecc43f..74a4604 100644
--- a/man/conn.3
+++ b/man/conn.3
@@ -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
-- 
[mdw]