[mLib] / man / conn.3

.\" -*-nroff-*-
.TH conn 3 "23 May 1999" mLib
.\" @conn_init
.\" @conn_kill
.SH NAME
conn \- selector for nonblocking connections
.SH SYNOPSIS
.nf
.B "#include <mLib/conn.h>

.BI "void conn_init(conn *" c ", sel_state *" s ", int " fd ,
.BI "               struct sockaddr *" dst ", int " dsz ,
.BI "               void (*" func ")(int " fd ", void *" p ),
.BI "               void *" p );

.BI "void conn_kill(conn *" c );
.fi
.SH DESCRIPTION
The
.B conn
selector manages a nonblocking connection to a remote socket.  The
selector's state is maintained in an object of type
.BR conn .
.PP
Before use, a
.B conn
selector must be initialized.  This requires a call to
.B conn_init
with a fairly large number of arguments:
.TP
.I c
Pointer to
.B conn
object which needs to be initialized.
.TP
.I s
Pointer to a multiplexor object (type
.BR sel_state )
to which this selector should be attached.  See
.BR sel (3)
for more details about multiplexors, and how this whole system works.
.TP
.I fd
File descriptor for the socket you want to connect.  This becomes the
`property' of the
.B conn
selector until the connection attempt finishes.  For example, if there's
an error, the descriptor will be closed.
.TP
.I dst
Pointer to destination socket address for the connection.  Make sure
that the address has the right family.
.TP
.I dsz 
Size of the destination socket address.
.TP
.I func
A function to call when the connection is complete.  It is passed the
file descriptor of the connected socket, and the pointer passed
to
.B conn_init
as the
.I p
argument.  If the connection failed, a file descriptor value of \-1 is
passed, and the global
.B errno
value is set appropriately.
.TP
.I p
An arbitrary pointer whose value is passed to the handler function when
the connection finishes.
.PP
If you want to cancel the connection attempt before it finishes, call
.B conn_kill
with the address of the selector.  The file descriptor is closed, and
the selector becomes safe to be discarded.
.SH "SEE ALSO"
.BR connect (2),
.BR sel (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>
Commit	Line	Data
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
	9	.B "#include <mLib/conn.h>
	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
	31	.I c
	32	Pointer to
	33	.B conn
	34	object which needs to be initialized.
	35	.TP
	36	.I s
	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
	43	.I fd
	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
	50	.I dst
	51	Pointer to destination socket address for the connection. Make sure
	52	that the address has the right family.
	53	.TP
	54	.I dsz
	55	Size of the destination socket address.
	56	.TP
	57	.I func
	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
	69	.I p
	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
b6b9d458	82	Mark Wooding, <mdw@nsict.org>