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