b6b9d458 |
1 | .\" -*-nroff-*- |
fbf20b5b |
2 | .TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library" |
5934f1ee |
3 | .\" @conn_fd |
08da152e |
4 | .\" @conn_init |
5 | .\" @conn_kill |
b6b9d458 |
6 | .SH NAME |
7 | conn \- selector for nonblocking connections |
8 | .SH SYNOPSIS |
9 | .nf |
d2a91066 |
10 | .B "#include <mLib/conn.h>" |
b6b9d458 |
11 | |
5934f1ee |
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 | |
99c850b2 |
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 ); |
b6b9d458 |
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 |
ff76c38f |
36 | .BI "conn *" c |
b6b9d458 |
37 | Pointer to |
38 | .B conn |
39 | object which needs to be initialized. |
40 | .TP |
ff76c38f |
41 | .BI "sel_state *" s |
b6b9d458 |
42 | Pointer to a multiplexor object (type |
43 | .BR sel_state ) |
44 | to which this selector should be attached. See |
08da152e |
45 | .BR sel (3) |
b6b9d458 |
46 | for more details about multiplexors, and how this whole system works. |
47 | .TP |
ff76c38f |
48 | .BI "int " fd |
b6b9d458 |
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 |
ff76c38f |
55 | .BI "struct sockaddr *" dst |
b6b9d458 |
56 | Pointer to destination socket address for the connection. Make sure |
57 | that the address has the right family. |
58 | .TP |
d4efbcd9 |
59 | .BI "int " dsz |
b6b9d458 |
60 | Size of the destination socket address. |
61 | .TP |
ff76c38f |
62 | .BI "void (*" func ")(int " fd ", void *" p ) |
b6b9d458 |
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 |
99c850b2 |
69 | argument. |
b6b9d458 |
70 | .TP |
ff76c38f |
71 | .BI "void *" p |
b6b9d458 |
72 | An arbitrary pointer whose value is passed to the handler function when |
73 | the connection finishes. |
74 | .PP |
99c850b2 |
75 | A few words are in order about |
76 | .BR conn_init 's |
5934f1ee |
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 , |
99c850b2 |
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 |
5934f1ee |
97 | Alternatively, if you have a socket with a pending connection (i.e., a |
98 | call to |
99 | .BR connect |
d4efbcd9 |
100 | returned \-1 and set |
5934f1ee |
101 | .B errno |
102 | to |
d4efbcd9 |
103 | .BR EINPROGRESS ), |
5934f1ee |
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 |
b6b9d458 |
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. |
08da152e |
118 | .SH "SEE ALSO" |
119 | .BR connect (2), |
120 | .BR sel (3), |
121 | .BR mLib (3). |
b6b9d458 |
122 | .SH AUTHOR |
9b5ac6ff |
123 | Mark Wooding, <mdw@distorted.org.uk> |