mdw@git.distorted.org.uk Git - mLib/blob - man/conn.3

   1 .\" -*-nroff-*-
   2 .TH conn 3mLib "23 May 1999" mLib
   3 .SH NAME
   4 conn \- selector for nonblocking connections
   5 .SH SYNOPSIS
   6 .nf
   7 .B "#include <mLib/conn.h>
   8
   9 .BI "void conn_init(conn *" c ", sel_state *" s ", int " fd ,
  10 .BI "               struct sockaddr *" dst ", int " dsz ,
  11 .BI "               void (*" func ")(int " fd ", void *" p ),
  12 .BI "               void *" p );
  13
  14 .BI "void conn_kill(conn *" c );
  15 .fi
  16 .SH DESCRIPTION
  17 The
  18 .B conn
  19 selector manages a nonblocking connection to a remote socket.  The
  20 selector's state is maintained in an object of type
  21 .BR conn .
  22 .PP
  23 Before use, a
  24 .B conn
  25 selector must be initialized.  This requires a call to
  26 .B conn_init
  27 with a fairly large number of arguments:
  28 .TP
  29 .I c
  30 Pointer to
  31 .B conn
  32 object which needs to be initialized.
  33 .TP
  34 .I s
  35 Pointer to a multiplexor object (type
  36 .BR sel_state )
  37 to which this selector should be attached.  See
  38 .BR sel (3mLib)
  39 for more details about multiplexors, and how this whole system works.
  40 .TP
  41 .I fd
  42 File descriptor for the socket you want to connect.  This becomes the
  43 `property' of the
  44 .B conn
  45 selector until the connection attempt finishes.  For example, if there's
  46 an error, the descriptor will be closed.
  47 .TP
  48 .I dst
  49 Pointer to destination socket address for the connection.  Make sure
  50 that the address has the right family.
  51 .TP
  52 .I dsz
  53 Size of the destination socket address.
  54 .TP
  55 .I func
  56 A function to call when the connection is complete.  It is passed the
  57 file descriptor of the connected socket, and the pointer passed
  58 to
  59 .B conn_init
  60 as the
  61 .I p
  62 argument.  If the connection failed, a file descriptor value of \-1 is
  63 passed, and the global
  64 .B errno
  65 value is set appropriately.
  66 .TP
  67 .I p
  68 An arbitrary pointer whose value is passed to the handler function when
  69 the connection finishes.
  70 .PP
  71 If you want to cancel the connection attempt before it finishes, call
  72 .B conn_kill
  73 with the address of the selector.  The file descriptor is closed, and
  74 the selector becomes safe to be discarded.
  75 .SH AUTHOR
  76 Mark Wooding, <mdw@nsict.org>