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

   1 .\" -*-nroff-*-
   2 .TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .\" @conn_fd
   4 .\" @conn_init
   5 .\" @conn_kill
   6 .SH NAME
   7 conn \- selector for nonblocking connections
   8 .SH SYNOPSIS
   9 .nf
  10 .B "#include <mLib/conn.h>"
  11 .PP
  12 .B "typedef struct { ...\& } conn;"
  13 .PP
  14 .ta \w'\fBint conn_fd('u
  15 .BI "int conn_fd(conn *" c ", sel_state *" s ", int " fd ,
  16 .BI "   void (*" func ")(int " fd ", void *" p ),
  17 .BI "   void *" p );
  18 .PP
  19 .ta \w'\fBint conn_init('u
  20 .BI "int conn_init(conn *" c ", sel_state *" s ", int " fd ,
  21 .BI "   struct sockaddr *" dst ", int " dsz ,
  22 .BI "   void (*" func ")(int " fd ", void *" p ),
  23 .BI "   void *" p );
  24 .PP
  25 .BI "void conn_kill(conn *" c );
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .B conn
  30 selector manages a nonblocking connection to a remote socket.  The
  31 selector's state is maintained in an object of type
  32 .BR conn .
  33 .PP
  34 Before use, a
  35 .B conn
  36 selector must be initialized.  This requires a call to
  37 .B conn_init
  38 with a fairly large number of arguments:
  39 .TP
  40 .BI "conn *" c
  41 Pointer to
  42 .B conn
  43 object which needs to be initialized.
  44 .TP
  45 .BI "sel_state *" s
  46 Pointer to a multiplexor object (type
  47 .BR sel_state )
  48 to which this selector should be attached.  See
  49 .BR sel (3)
  50 for more details about multiplexors, and how this whole system works.
  51 .TP
  52 .BI "int " fd
  53 File descriptor for the socket you want to connect.  This becomes the
  54 `property' of the
  55 .B conn
  56 selector until the connection attempt finishes.  For example, if there's
  57 an error, the descriptor will be closed.
  58 .TP
  59 .BI "struct sockaddr *" dst
  60 Pointer to destination socket address for the connection.  Make sure
  61 that the address has the right family.
  62 .TP
  63 .BI "int " dsz
  64 Size of the destination socket address.
  65 .TP
  66 .BI "void (*" func ")(int " fd ", void *" p )
  67 A function to call when the connection is complete.  It is passed the
  68 file descriptor of the connected socket, and the pointer passed
  69 to
  70 .B conn_init
  71 as the
  72 .I p
  73 argument.
  74 .TP
  75 .BI "void *" p
  76 An arbitrary pointer whose value is passed to the handler function when
  77 the connection finishes.
  78 .PP
  79 A few words are in order about
  80 .BR conn_init 's
  81 detailed behaviour and return value.  If it returns \-1, the connection
  82 attempt has failed immediately, an error code is stored in the global
  83 variable
  84 .BR errno ,
  85 the file descriptor has been
  86 .IR closed ,
  87 and the connection function will
  88 .I not
  89 be called.  If it returns zero, then there has been no immediate
  90 failure; the connection function
  91 .I might
  92 have been called, if the connection succeeded immediately, but it will
  93 certainly be called some time, unless the connector is killed (see
  94 .B conn_kill
  95 below).  When the connection function is called, it will either be
  96 passed the file descriptor of the new-connected socket (to indicate
  97 success) or the value \-1 for failure; in the latter case, an
  98 appropriate error code is stored in
  99 .BR errno .
 100 .PP
 101 Alternatively, if you have a socket with a pending connection (i.e., a
 102 call to
 103 .BR connect
 104 returned \-1 and set
 105 .B errno
 106 to
 107 .BR EINPROGRESS ),
 108 you can call
 109 .BR conn_fd.
 110 Its arguments are the same as for
 111 .BR conn_init ,
 112 except that since the socket knows its a peer address the
 113 .I dst
 114 and
 115 .I dsz
 116 arguments are not given, and it can't fail.
 117 .PP
 118 If you want to cancel the connection attempt before it finishes, call
 119 .B conn_kill
 120 with the address of the selector.  The file descriptor is closed, and
 121 the selector becomes safe to be discarded.
 122 .SH "SEE ALSO"
 123 .BR connect (2),
 124 .BR sel (3),
 125 .BR mLib (3).
 126 .SH AUTHOR
 127 Mark Wooding, <mdw@distorted.org.uk>