'\"macro stdmacro
.if n .pH g3n.t_listen @(#)t_listen	40.6 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} t_listen 3N "Networking Support Utilities" "\&"
.if \nX=1 .ds x} t_listen 3N "Networking Support Utilities"
.if \nX=2 .ds x} t_listen 3N "" "\&"
.if \nX=3 .ds x} t_listen "" "" "\&"
.if \nX=4 .ds x} t_listen "NS_LIB" "EXTENSION" " "
.TH \*(x}
.SH NAME
\f4t_listen\f1 \- listen for a connect request
.SH SYNOPSIS
\f4#include <tiuser.h>\f1
.PP
\f4int t_listen(fd, call)\f1
.br
\f4int fd;\f1
.br
\f4struct t_call \(**call;\f1
.SH DESCRIPTION
This function listens for a
connect request from a calling transport user.
\f4fd\fP
identifies the local transport endpoint where connect
indications arrive,
and on return,
\f4call\fP
contains information describing the connect indication.
\f4call\f1
points to a \f4t_call\f1 structure, which contains the following members:
.PP
.RS
\f4struct netbuf addr;\fP
.br
\f4truct netbuf opt;\fP
.br
\f4struct netbuf udata;\fP
.br
\f4int sequence;\fP
.RE
.PP
\f4netbuf\f1 is described in \f4intro\fP(3).
In
\f4call\fP,
\f4addr\fP
returns the protocol address of the calling transport user,
\f4opt\fP
returns protocol-specific parameters
associated with the connect request,
\f4udata\fP
returns any user data sent by the caller on the connect request, and
\f4sequence\fP
is a number that uniquely identifies the returned connect
indication.
The value of
\f4sequence\fP
enables the user to listen for multiple connect indications
before responding to any of them.
.PP
Since this function returns values for the
\f4addr\fP,
\f4opt\fP,
and
\f4udata\fP
fields of
\f4call\fP,
the
\f4maxlen\fP
[see \f4netbuf\f1 in \f4intro\fP(3)] field of each must be set before
issuing \f4t_listen\fP
to indicate the maximum size of the buffer for each.
.PP
By default,
\f4t_listen\fP
executes in synchronous mode and
waits for a connect indication to arrive before returning to the user.
However, if
\f4O_NDELAY\fP
or
\f4O_NONBLOCK\fP
is set (via
\f4t_open\fP
or
\f4fcntl\fP),
\f4t_listen\fP
executes asynchronously, reducing
to a poll for existing connect indications.
If none are available, it returns \-1 and sets
\f4t_errno
to \f4TNODATA\fP.
.P
On failure, \f4t_errno\f1 may be set to one of the following:
.TP 20
\f4[TBADF]\fP
The specified file descriptor does not refer to a transport endpoint.
.TP
\f4[TBUFOVFLW]\fP
The number of bytes allocated for an incoming argument is not
sufficient to store the value of that argument.
The provider's state, as seen by the user, changes to
\f4T_INCON\fP, and
the connect indication information to be returned in
\f4call\fP
is discarded.
.TP
\f4[TNODATA]\fP
\f4O_NDELAY\fP or \f4O_NONBLOCK\fP was set, but no connect indications
had been queued.
.TP
\f4[TLOOK]\fP
An asynchronous event has occurred on this transport endpoint and requires
immediate attention.
.TP
\f4[TNOTSUPPORT]\fP
This function is not supported by the underlying transport
provider.
.TP
\f4[TSYSERR]\fP
A system error has occurred during execution of this function.
.SH CAVEATS
If a user issues \f4t_listen\fP
in synchronous mode on a transport endpoint that was not
bound for listening (i.e., \f4qlen\f1 was zero on
\f4t_bind\fP), the call will wait forever because
no connect indications will arrive on that endpoint.
.SH SEE ALSO
.na
\f4intro\fP(3), \f4t_accept\fP(3N),
\f4t_bind\fP(3N),
\f4t_connect\fP(3N),
\f4t_open\fP(3N),
\f4t_rcvconnect\fP(3N).
.sp .2
\f2UNIX System V Network Programmer's Guide\f1.
.ad
.SH DIAGNOSTICS
\f4t_listen\fP returns 0 on success and \-1 on failure and
\f4t_errno\f1 is set to indicate the error.
.Ee
