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

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