chiark / gitweb /
Various stuff.
[mLib] / man / conn.3
b6b9d458 1.\" -*-nroff-*-
fbf20b5b 2.TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
08da152e 3.\" @conn_init
4.\" @conn_kill
b6b9d458 5.SH NAME
6conn \- selector for nonblocking connections
d2a91066 9.B "#include <mLib/conn.h>"
b6b9d458 10
99c850b2 11.BI "int 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 );
b6b9d458 15
16.BI "void conn_kill(conn *" c );
20.B conn
21selector manages a nonblocking connection to a remote socket. The
22selector's state is maintained in an object of type
23.BR conn .
25Before use, a
26.B conn
27selector must be initialized. This requires a call to
28.B conn_init
29with a fairly large number of arguments:
ff76c38f 31.BI "conn *" c
b6b9d458 32Pointer to
33.B conn
34object which needs to be initialized.
ff76c38f 36.BI "sel_state *" s
b6b9d458 37Pointer to a multiplexor object (type
38.BR sel_state )
39to which this selector should be attached. See
08da152e 40.BR sel (3)
b6b9d458 41for more details about multiplexors, and how this whole system works.
ff76c38f 43.BI "int " fd
b6b9d458 44File descriptor for the socket you want to connect. This becomes the
45`property' of the
46.B conn
47selector until the connection attempt finishes. For example, if there's
48an error, the descriptor will be closed.
ff76c38f 50.BI "struct sockaddr *" dst
b6b9d458 51Pointer to destination socket address for the connection. Make sure
52that the address has the right family.
ff76c38f 54.BI "int " dsz
b6b9d458 55Size of the destination socket address.
ff76c38f 57.BI "void (*" func ")(int " fd ", void *" p )
b6b9d458 58A function to call when the connection is complete. It is passed the
59file descriptor of the connected socket, and the pointer passed
61.B conn_init
62as the
63.I p
99c850b2 64argument.
b6b9d458 65.TP
ff76c38f 66.BI "void *" p
b6b9d458 67An arbitrary pointer whose value is passed to the handler function when
68the connection finishes.
99c850b2 70A few words are in order about
71.BR conn_init 's
72detailed behaviour and return value. If the it returns \-1, the
73connection attempt has failed immediately (an error code is stored in
74the global variable
75.BR errno ),
76the file descriptor has been
77.IR closed ,
78and the connection function will
79.I not
80be called. If it returns zero, then there has been no immediate
81failure; the connection function
82.I might
83have been called, if the connection succeeded immediately, but it will
84certainly be called some time, unless the connector is killed (see
85.B conn_kill
86below). When the connection function is called, it will either be
87passed the file descriptor of the new-connected socket (to indicate
88success) or the value \-1 for failure; in the latter case, an
89appropriate error code is stored in
90.BR errno .
b6b9d458 92If you want to cancel the connection attempt before it finishes, call
93.B conn_kill
94with the address of the selector. The file descriptor is closed, and
95the selector becomes safe to be discarded.
08da152e 96.SH "SEE ALSO"
97.BR connect (2),
98.BR sel (3),
99.BR mLib (3).
b6b9d458 100.SH AUTHOR
101Mark Wooding, <>