chiark - git - mdw - mLib/blob - sel/conn.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for asynchronous connection
   4 .\"
   5 .\" (c) 1999, 2001--2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH conn 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @conn_fd
  33 .\" @conn_init
  34 .\" @conn_kill
  35 .
  36 .\"--------------------------------------------------------------------------
  37 .SH NAME
  38 conn \- selector for nonblocking connections
  39 .
  40 .\"--------------------------------------------------------------------------
  41 .SH SYNOPSIS
  42 .
  43 .nf
  44 .B "#include <mLib/conn.h>"
  45 .PP
  46 .B "typedef struct { ...\& } conn;"
  47 .PP
  48 .ta \w'\fBint conn_fd('u
  49 .BI "int conn_fd(conn *" c ", sel_state *" s ", int " fd ,
  50 .BI "   void (*" func ")(int " fd ", void *" p ),
  51 .BI "   void *" p );
  52 .PP
  53 .ta \w'\fBint conn_init('u
  54 .BI "int conn_init(conn *" c ", sel_state *" s ", int " fd ,
  55 .BI "   struct sockaddr *" dst ", int " dsz ,
  56 .BI "   void (*" func ")(int " fd ", void *" p ),
  57 .BI "   void *" p );
  58 .PP
  59 .BI "void conn_kill(conn *" c );
  60 .fi
  61 .
  62 .\"--------------------------------------------------------------------------
  63 .SH DESCRIPTION
  64 .
  65 The
  66 .B conn
  67 selector manages a nonblocking connection to a remote socket.  The
  68 selector's state is maintained in an object of type
  69 .BR conn .
  70 .PP
  71 Before use, a
  72 .B conn
  73 selector must be initialized.  This requires a call to
  74 .B conn_init
  75 with a fairly large number of arguments:
  76 .TP
  77 .BI "conn *" c
  78 Pointer to
  79 .B conn
  80 object which needs to be initialized.
  81 .TP
  82 .BI "sel_state *" s
  83 Pointer to a multiplexor object (type
  84 .BR sel_state )
  85 to which this selector should be attached.  See
  86 .BR sel (3)
  87 for more details about multiplexors, and how this whole system works.
  88 .TP
  89 .BI "int " fd
  90 File descriptor for the socket you want to connect.  This becomes the
  91 `property' of the
  92 .B conn
  93 selector until the connection attempt finishes.  For example, if there's
  94 an error, the descriptor will be closed.
  95 .TP
  96 .BI "struct sockaddr *" dst
  97 Pointer to destination socket address for the connection.  Make sure
  98 that the address has the right family.
  99 .TP
 100 .BI "int " dsz
 101 Size of the destination socket address.
 102 .TP
 103 .BI "void (*" func ")(int " fd ", void *" p )
 104 A function to call when the connection is complete.  It is passed the
 105 file descriptor of the connected socket, and the pointer passed
 106 to
 107 .B conn_init
 108 as the
 109 .I p
 110 argument.
 111 .TP
 112 .BI "void *" p
 113 An arbitrary pointer whose value is passed to the handler function when
 114 the connection finishes.
 115 .PP
 116 A few words are in order about
 117 .BR conn_init 's
 118 detailed behaviour and return value.  If it returns \-1, the connection
 119 attempt has failed immediately, an error code is stored in the global
 120 variable
 121 .BR errno ,
 122 the file descriptor has been
 123 .IR closed ,
 124 and the connection function will
 125 .I not
 126 be called.  If it returns zero, then there has been no immediate
 127 failure; the connection function
 128 .I might
 129 have been called, if the connection succeeded immediately, but it will
 130 certainly be called some time, unless the connector is killed (see
 131 .B conn_kill
 132 below).  When the connection function is called, it will either be
 133 passed the file descriptor of the new-connected socket (to indicate
 134 success) or the value \-1 for failure; in the latter case, an
 135 appropriate error code is stored in
 136 .BR errno .
 137 .PP
 138 Alternatively, if you have a socket with a pending connection (i.e., a
 139 call to
 140 .BR connect
 141 returned \-1 and set
 142 .B errno
 143 to
 144 .BR EINPROGRESS ),
 145 you can call
 146 .BR conn_fd.
 147 Its arguments are the same as for
 148 .BR conn_init ,
 149 except that since the socket knows its a peer address the
 150 .I dst
 151 and
 152 .I dsz
 153 arguments are not given, and it can't fail.
 154 .PP
 155 If you want to cancel the connection attempt before it finishes, call
 156 .B conn_kill
 157 with the address of the selector.  The file descriptor is closed, and
 158 the selector becomes safe to be discarded.
 159 .
 160 .\"--------------------------------------------------------------------------
 161 .SH "SEE ALSO"
 162 .
 163 .BR connect (2),
 164 .BR sel (3),
 165 .BR mLib (3).
 166 .
 167 .\"--------------------------------------------------------------------------
 168 .SH AUTHOR
 169 .
 170 Mark Wooding, <mdw@distorted.org.uk>
 171 .
 172 .\"----- That's all, folks --------------------------------------------------