'\"macro stdmacro
.if n .pH g1a.listen @(#)listen	40.5 of 1/17/90
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} listen 1M "Networking Support Utilities" "\&"
.if \nX=1 .ds x} listen 1M "Networking Support Utilities"
.if \nX=2 .ds x} listen 1M "" "\&"
.if \nX=3 .ds x} listen 1M "" "\&"
.TH \*(x}
.SH NAME
\f4listen\f1 \- network listener daemon
.SH SYNOPSIS
\f4/usr/lib/saf/listen\fP [ \f4\-m \f2devstem\f1 ] \f2net_spec\fP
.SH DESCRIPTION
The \f4listen\fP process ``listens'' to a network for service requests,
accepts requests when they arrive, and invokes servers in response to
those service requests.
The network listener process may be used with any connection-oriented
network (more precisely, with any connection-oriented transport
provider) that conforms to the Transport Interface (TLI) specification.
.PP
The listener internally generates a pathname for the minor device for
each connection; it is this pathname that is used in the \f4utmp\fP
entry for a service, if one is created.
By default, this pathname is the concatenation of the prefix
\f4/dev/\fP\f2netspec\fP with the decimal representation of the minor
device number.
When the \f4\-m\fP\ \f2devstem\fP option is specified, the listener will
use \f2devstem\fP as the prefix for the pathname.
In either case, the representation of the minor device number will be at
least two digits (e.g., 05 or 27), but will be longer when necessary to
accommodate minor device numbers larger than 99.
.SH "SERVER INVOCATION"
When a connection indication is received, the listener creates a new
transport endpoint and accepts the connection on that endpoint.
Before giving the file descriptor for this new connection to the server,
any designated \s-1STREAMS\s0 modules are pushed and the configuration
script is executed, if one exists.
This file descriptor is appropriate for use with either \s-1TLI\s0 (see
especially \f4t_sync(3N)\fP) or the sockets interface library.
.PP
By default, a new instance of the server is invoked for each connection.
When the server is invoked, file descriptor 0 refers to the
transport endpoint, and is open for reading and writing.
File descriptors 1 and 2 are copies of file descriptor 0; no other file
descriptors are open.
The service is invoked with the user and group IDs of the user name
under which the service was registered with the listener, and with the
current directory set to the \s-1HOME\s0 directory of that user.
.PP
Alternatively, a service may be registered so that the listener will
pass connections to a standing server process through a FIFO or a named
\s-1STREAM\s0, instead of invoking the server anew for each connection.
In this case, the connection is passed in the form of a file descriptor
that refers to the new transport endpoint.
Before the file descriptor is sent to the server, the listener
interprets any configuration script registered for that service using
\f4doconfig\fP(3N), although \f4doconfig\fP is invoked with both the
\s-1NORUN\s0 and \s-1NOASSIGN\s0 flags.
The server receives the file descriptor for the connection in a
\f4strrecvfd\fP structure via an \s-1I_RECVFD\s0 \f4ioctl\fP(2).
.PP
For more details about the listener and its administration, see
\f4nlsadmin\fP(1M).
.SH FILES
\f4/etc/saf/\fP\f2pmtag\fP\f4/\fP*
.SH "SEE ALSO"
\f4nlsadmin\fP(1M), \f4pmadm\fP(1M), \f4sac\fP(1M), \f4sacadm\fP(1M),
.br
\f4doconfig\fP(3N), \f4nlsgetcall\fP, \f4nlsprovider\fP(3N),
.br
.\" streamio(7) is relevant here because it describes passing file pointers
\f4streamio(7)\fP.
.br
\f2Network Programmer's Guide\fP
.SH NOTES
When passing a connection to a standing server, the user and group IDs
contained in the \f4strrecvfd\fP structure will be those for the
listener (that is, they will both be 0); the user name under which the
service was registered with the listener is not reflected in these IDs.
.PP
When operating multiple instances of the listener on a single transport
provider, there is a potential race condition in the binding of
addresses during initialization of the listeners if any of their
services have dynamically assigned addresses.
This condition would appear as an inability of the listener to bind a
static-address service to its otherwise valid address, and would result
from a dynamic-address service having been bound to that address by a
different instance of the listener.
