Commit | Line | Data |
---|---|---|
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 | |
2b1924c2 MW |
12 | .ds mT \fBint conn_fd( |
13 | .BI "\*(mTconn *" c ", sel_state *" s ", int " fd , | |
14 | .BI "\h'\w'\*(mT'u'void (*" func ")(int " fd ", void *" p ), | |
15 | .BI "\h'\w'\*(mT'u'void *" p ); | |
5934f1ee | 16 | |
2b1924c2 MW |
17 | .ds mT \fBint conn_init( |
18 | .BI "\*(mTconn *" c ", sel_state *" s ", int " fd , | |
19 | .BI "\h'\w'\*(mT'u'struct sockaddr *" dst ", int " dsz , | |
20 | .BI "\h'\w'\*(mT'u'void (*" func ")(int " fd ", void *" p ), | |
21 | .BI "\h'\w'\*(mT'u'void *" p ); | |
b6b9d458 | 22 | |
23 | .BI "void conn_kill(conn *" c ); | |
24 | .fi | |
25 | .SH DESCRIPTION | |
26 | The | |
27 | .B conn | |
28 | selector manages a nonblocking connection to a remote socket. The | |
29 | selector's state is maintained in an object of type | |
30 | .BR conn . | |
31 | .PP | |
32 | Before use, a | |
33 | .B conn | |
34 | selector must be initialized. This requires a call to | |
35 | .B conn_init | |
36 | with a fairly large number of arguments: | |
37 | .TP | |
ff76c38f | 38 | .BI "conn *" c |
b6b9d458 | 39 | Pointer to |
40 | .B conn | |
41 | object which needs to be initialized. | |
42 | .TP | |
ff76c38f | 43 | .BI "sel_state *" s |
b6b9d458 | 44 | Pointer to a multiplexor object (type |
45 | .BR sel_state ) | |
46 | to which this selector should be attached. See | |
08da152e | 47 | .BR sel (3) |
b6b9d458 | 48 | for more details about multiplexors, and how this whole system works. |
49 | .TP | |
ff76c38f | 50 | .BI "int " fd |
b6b9d458 | 51 | File descriptor for the socket you want to connect. This becomes the |
52 | `property' of the | |
53 | .B conn | |
54 | selector until the connection attempt finishes. For example, if there's | |
55 | an error, the descriptor will be closed. | |
56 | .TP | |
ff76c38f | 57 | .BI "struct sockaddr *" dst |
b6b9d458 | 58 | Pointer to destination socket address for the connection. Make sure |
59 | that the address has the right family. | |
60 | .TP | |
d4efbcd9 | 61 | .BI "int " dsz |
b6b9d458 | 62 | Size of the destination socket address. |
63 | .TP | |
ff76c38f | 64 | .BI "void (*" func ")(int " fd ", void *" p ) |
b6b9d458 | 65 | A function to call when the connection is complete. It is passed the |
66 | file descriptor of the connected socket, and the pointer passed | |
67 | to | |
68 | .B conn_init | |
69 | as the | |
70 | .I p | |
99c850b2 | 71 | argument. |
b6b9d458 | 72 | .TP |
ff76c38f | 73 | .BI "void *" p |
b6b9d458 | 74 | An arbitrary pointer whose value is passed to the handler function when |
75 | the connection finishes. | |
76 | .PP | |
99c850b2 | 77 | A few words are in order about |
78 | .BR conn_init 's | |
5934f1ee | 79 | detailed behaviour and return value. If it returns \-1, the connection |
80 | attempt has failed immediately, an error code is stored in the global | |
81 | variable | |
82 | .BR errno , | |
99c850b2 | 83 | the file descriptor has been |
84 | .IR closed , | |
85 | and the connection function will | |
86 | .I not | |
87 | be called. If it returns zero, then there has been no immediate | |
88 | failure; the connection function | |
89 | .I might | |
90 | have been called, if the connection succeeded immediately, but it will | |
91 | certainly be called some time, unless the connector is killed (see | |
92 | .B conn_kill | |
93 | below). When the connection function is called, it will either be | |
94 | passed the file descriptor of the new-connected socket (to indicate | |
95 | success) or the value \-1 for failure; in the latter case, an | |
96 | appropriate error code is stored in | |
97 | .BR errno . | |
98 | .PP | |
5934f1ee | 99 | Alternatively, if you have a socket with a pending connection (i.e., a |
100 | call to | |
101 | .BR connect | |
d4efbcd9 | 102 | returned \-1 and set |
5934f1ee | 103 | .B errno |
104 | to | |
d4efbcd9 | 105 | .BR EINPROGRESS ), |
5934f1ee | 106 | you can call |
107 | .BR conn_fd. | |
108 | Its arguments are the same as for | |
109 | .BR conn_init , | |
110 | except that since the socket knows its a peer address the | |
111 | .I dst | |
112 | and | |
113 | .I dsz | |
114 | arguments are not given, and it can't fail. | |
115 | .PP | |
b6b9d458 | 116 | If you want to cancel the connection attempt before it finishes, call |
117 | .B conn_kill | |
118 | with the address of the selector. The file descriptor is closed, and | |
119 | the selector becomes safe to be discarded. | |
08da152e | 120 | .SH "SEE ALSO" |
121 | .BR connect (2), | |
122 | .BR sel (3), | |
123 | .BR mLib (3). | |
b6b9d458 | 124 | .SH AUTHOR |
9b5ac6ff | 125 | Mark Wooding, <mdw@distorted.org.uk> |