@@@ much mess, mostly manpages

[mLib] / sel / conn.3.in

.\" -*-nroff-*-
.\"
.\" Manual for asynchronous connection
.\"
.\" (c) 1999, 2001--2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH conn 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @conn_fd
.\" @conn_init
.\" @conn_kill
.
.\"--------------------------------------------------------------------------
.SH NAME
conn \- selector for nonblocking connections
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/conn.h>"
.PP
.B "typedef struct { ...\& } conn;"
.PP
.ta \w'\fBint conn_fd('u
.BI "int conn_fd(conn *" c ", sel_state *" s ", int " fd ,
.BI "	void (*" func ")(int " fd ", void *" p ),
.BI "	void *" p );
.PP
.ta \w'\fBint conn_init('u
.BI "int 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 );
.PP
.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
.BI "conn *" c
Pointer to
.B conn
object which needs to be initialized.
.TP
.BI "sel_state *" 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
.BI "int " 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
.BI "struct sockaddr *" dst
Pointer to destination socket address for the connection.  Make sure
that the address has the right family.
.TP
.BI "int " dsz
Size of the destination socket address.
.TP
.BI "void (*" func ")(int " fd ", void *" p )
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.
.TP
.BI "void *" p
An arbitrary pointer whose value is passed to the handler function when
the connection finishes.
.PP
A few words are in order about
.BR conn_init 's
detailed behaviour and return value.  If it returns \-1, the connection
attempt has failed immediately, an error code is stored in the global
variable
.BR errno ,
the file descriptor has been
.IR closed ,
and the connection function will
.I not
be called.  If it returns zero, then there has been no immediate
failure; the connection function
.I might
have been called, if the connection succeeded immediately, but it will
certainly be called some time, unless the connector is killed (see
.B conn_kill
below).  When the connection function is called, it will either be
passed the file descriptor of the new-connected socket (to indicate
success) or the value \-1 for failure; in the latter case, an
appropriate error code is stored in
.BR errno .
.PP
Alternatively, if you have a socket with a pending connection (i.e., a
call to
.BR connect
returned \-1 and set
.B errno
to
.BR EINPROGRESS ),
you can call
.BR conn_fd.
Its arguments are the same as for
.BR conn_init ,
except that since the socket knows its a peer address the
.I dst
and
.I dsz
arguments are not given, and it can't fail.
.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@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------