| 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> |