b6b9d458 |
1 | .\" -*-nroff-*- |
08da152e |
2 | .TH conn 3 "23 May 1999" mLib |
3 | .\" @conn_init |
4 | .\" @conn_kill |
b6b9d458 |
5 | .SH NAME |
6 | conn \- selector for nonblocking connections |
7 | .SH SYNOPSIS |
8 | .nf |
d2a91066 |
9 | .B "#include <mLib/conn.h>" |
b6b9d458 |
10 | |
11 | .BI "void 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 |
ff76c38f |
31 | .BI "conn *" c |
b6b9d458 |
32 | Pointer to |
33 | .B conn |
34 | object which needs to be initialized. |
35 | .TP |
ff76c38f |
36 | .BI "sel_state *" s |
b6b9d458 |
37 | Pointer to a multiplexor object (type |
38 | .BR sel_state ) |
39 | to which this selector should be attached. See |
08da152e |
40 | .BR sel (3) |
b6b9d458 |
41 | for more details about multiplexors, and how this whole system works. |
42 | .TP |
ff76c38f |
43 | .BI "int " fd |
b6b9d458 |
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 |
ff76c38f |
50 | .BI "struct sockaddr *" dst |
b6b9d458 |
51 | Pointer to destination socket address for the connection. Make sure |
52 | that the address has the right family. |
53 | .TP |
ff76c38f |
54 | .BI "int " dsz |
b6b9d458 |
55 | Size of the destination socket address. |
56 | .TP |
ff76c38f |
57 | .BI "void (*" func ")(int " fd ", void *" p ) |
b6b9d458 |
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. If the connection failed, a file descriptor value of \-1 is |
65 | passed, and the global |
66 | .B errno |
67 | value is set appropriately. |
68 | .TP |
ff76c38f |
69 | .BI "void *" p |
b6b9d458 |
70 | An arbitrary pointer whose value is passed to the handler function when |
71 | the connection finishes. |
72 | .PP |
73 | If you want to cancel the connection attempt before it finishes, call |
74 | .B conn_kill |
75 | with the address of the selector. The file descriptor is closed, and |
76 | the selector becomes safe to be discarded. |
08da152e |
77 | .SH "SEE ALSO" |
78 | .BR connect (2), |
79 | .BR sel (3), |
80 | .BR mLib (3). |
b6b9d458 |
81 | .SH AUTHOR |
82 | Mark Wooding, <mdw@nsict.org> |