usr/src/man/man1m/listen.1m

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH LISTEN 1M "Apr 3, 1997"
   7 .SH NAME
   8 listen \- network listener daemon
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/lib/saf/listen\fR [\fB-m\fR \fIdevstem\fR] \fInet_spec\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBlisten\fR process ``listens'' to a network for service requests, accepts
  19 requests when they arrive, and invokes servers in response to those service
  20 requests. The network listener process may be used with any connection-oriented
  21 network (more precisely, with any connection-oriented transport provider) that
  22 conforms to the Transport Layer Interface (TLI) Specification.
  23 .sp
  24 .LP
  25 The listener internally generates a pathname for the minor device for each
  26 connection; it is this pathname that is used in the \fButmpx\fR entry for a
  27 service, if one is created. By default, this pathname is the concatenation of
  28 the prefix \fB/dev/\fR\fInetspec\fR with the decimal representation of the
  29 minor device number. In either case, the representation of the minor device
  30 number will be at least two digits (for example, 05 or 27), or longer when it
  31 is necessary to accommodate minor device numbers larger than 99.
  32 .SH SERVER INVOCATION
  33 .sp
  34 .LP
  35 When a connection indication is received, the listener creates a new transport
  36 endpoint and accepts the connection on that endpoint. Before giving the file
  37 descriptor for this new connection to the server, any designated STREAMS
  38 modules are pushed and the configuration script is executed, (if one exists).
  39 This file descriptor is appropriate for use with either TLI (see
  40 \fBt_sync\fR(3NSL) ) or the sockets interface library.
  41 .sp
  42 .LP
  43 By default, a new instance of the server is invoked for each connection. When
  44 the server is invoked, file descriptor 0 refers to the transport endpoint, and
  45 is open for reading and writing. File descriptors 1 and 2 are copies of file
  46 descriptor 0; no other file descriptors are open. The service is invoked with
  47 the user and group IDs of the user name under which the service was registered
  48 with the listener, and with the current directory set to the HOME directory of
  49 that user.
  50 .sp
  51 .LP
  52 Alternatively, a service may be registered so that the listener will pass
  53 connections to a standing server process through a FIFO or a named stream,
  54 instead of invoking the server anew for each connection. In this case, the
  55 connection is passed in the form of a file descriptor that refers to the new
  56 transport endpoint. Before the file descriptor is sent to the server, the
  57 listener interprets any configuration script registered for that service using
  58 \fBdoconfig\fR(3NSL), although \fBdoconfig\fR is invoked with both the
  59 \fBNORUN\fR and \fBNOASSIGN\fR flags. The server receives the file descriptor
  60 for the connection in a \fBstrrecvfd\fR structure using an \fBI_RECVFD\fR
  61 \fBioctl\fR(2).
  62 .sp
  63 .LP
  64 For more details about the listener and its administration, see
  65 \fBnlsadmin\fR(1M).
  66 .SH OPTIONS
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fB-m\fR\fIdevstem\fR\fR
  71 .ad
  72 .RS 13n
  73 The listener will use \fIdevstem\fR as the prefix for the pathname.
  74 .RE
  75
  76 .SH FILES
  77 .sp
  78 .LP
  79 \fB/etc/saf/\fR\fIpmtag\fR\fB/\fR\fI*\fR
  80 .SH SEE ALSO
  81 .sp
  82 .LP
  83 \fBnlsadmin\fR(1M), \fBpmadm\fR(1M), \fBsac\fR(1M), \fBsacadm\fR(1M),
  84 \fBioctl\fR(2), \fBdoconfig\fR(3NSL), \fBnlsgetcall\fR(3NSL),
  85 \fBnlsprovider\fR(3NSL), \fBt_sync\fR(3NSL), \fBattributes\fR(5),
  86 \fBstreamio\fR(7I)
  87 .sp
  88 .LP
  89 \fI\fR
  90 .SH NOTES
  91 .sp
  92 .LP
  93 When passing a connection to a standing server, the user and group IDs
  94 contained in the \fBstrrecvfd\fR structure will be those for the listener (that
  95 is, they will both be 0); the user name under which the service was registered
  96 with the listener is not reflected in these IDs.
  97 .sp
  98 .LP
  99 When operating multiple instances of the listener on a single transport
 100 provider, there is a potential race condition in the binding of addresses
 101 during initialization of the listeners, if any of their services have
 102 dynamically assigned addresses. This condition would appear as an inability of
 103 the listener to bind a static-address service to its otherwise valid address,
 104 and would result from a dynamic-address service having been bound to that
 105 address by a different instance of the listener.