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