'\"macro stdmacro
.if n .pH g3n.nlsrequest @(#)nlsrequest	40.5 of 12/13/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} nlsrequest 3N "Networking Support Utilities" "\&"
.if \nX=1 .ds x} nlsrequest 3N "Networking Support Utilities"
.if \nX=2 .ds x} nlsrequest 3N "" "\&"
.if \nX=3 .ds x} nlsrequest "" "" "\&"
.TH \*(x}
.SH NAME
\f4nlsrequest\f1 \- format and send listener service request message
.SH SYNOPSIS
.PP
\f4#include <listen.h>\f1
.PP
\f4int nlsrequest (int fd, char \(**service_code);\f1
.PP
\f4extern int _nlslog, t_errno;\f1
.br
\f4extern char \(**_nlsrmsg;\f1
.SH DESCRIPTION
Given a virtual circuit to a listener process (\f2fd\f1) and a 
service code of a server process,
\f4nlsrequest\fP formats and sends
a \f2service request message\f1 to the remote listener process 
requesting that it start the given service.  
\f4nlsrequest\fP waits for the remote listener process
to return a \f2service request response message\f1, 
which is made available to the caller
in the static, null terminated data buffer pointed to by \f4_nlsrmsg\f1.
The \f2service request response message\f1 includes a success or failure code
and a text message.
The entire message is printable.
.SH SEE ALSO
\f4nlsadmin\fP(1), t_\f4error\fP(3).
.SH FILES
\f4/usr/lib/libnls.a
.br
/usr/lib/libslan.a
.br
/usr/lib/libnsl_s.a\f1
.SH DIAGNOSTICS
The success or failure code is the integer
return code from \f4nlsrequest\fP.
Zero indicates success, other negative 
values indicate \f4nlsrequest\fP failures as follows:
.PP
.ta .5i .8i
.nf
	\f4\-1:\f1	Error encountered by nlsrequest, see t_errno.
.fi
.PP
Postive values are error return codes from the \f2listener\f1 process.
Mnemonics for these codes are defined in \f4<listen.h>\f1.
.PP
.ta .5i .8i
.nf
	\f42:\f1	Request message not interpretable.
	\f43:\f1	Request service code unknown.
	\f44:\f1	Service code known, but currently disabled.
.fi
.PP
If non-null, \f4_nlsrmsg\f1 contains a pointer to a static, null terminated
character buffer containing the \f2service request response message\f1.
Note that both \f4_nlsrmsg\f1 and the data buffer are overwritten by each call
to \f4nlsrequest\fP.
.PP
If \f4_nlslog\f1 is non-zero, \f4nlsrequest\fP prints error messages on stderr.
Initially, \f4_nlslog\f1 is zero.
.SH WARNING
\f4nlsrequest\fP cannot always be certain that the remote server process
has been successfully started.  In this case, \f4nlsrequest\fP returns
with no indication of an error and the caller will receive
notification of a disconnect event via a \f4\s-1T_LOOK\s+1\f1 error before
or during the first \f4t_snd\fP or \f4t_rcv\fP call.
