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