Networking Services Library Functions            nlsrequest(3NSL)



NAME
     nlsrequest - format and send listener service  request  mes-
     sage

SYNOPSIS
     #include 
     int nlsrequest(int fildes, char *servicecode);
     extern int nlslogterrno;
     extern char *nlsrmsg;


DESCRIPTION
     Given a virtual circuit to a listener process (fildes) and a
     service  code  of a server process, nlsrequest() formats and
     sends a service request message to the remote listener  pro-
     cess   requesting  that it start the given service.   nlsre-
     quest() waits for the remote listener process  to  return  a
     service  request  response message,  which is made available
     to the caller in the  static,  null-terminated  data  buffer
     pointed to by nlsrmsg. The service request response message
     includes a success or failure code and a text  message.  The
     entire message is printable.

RETURN VALUES
     The success or failure code is the integer return code  from
     nlsrequest(). Zero indicates success, other negative  values
     indicate nlsrequest() failures as follows:

     -1       Error encountered by nlsrequest(), see terrno.



     Positive values are error return  codes  from  the  listener
     process.   Mnemonics   for   these   codes  are  defined  in
     .

     2    Request message not interpretable.


     3    Request service code unknown.


     4    Service code known, but currently disabled.



     If non-null, nlsrmsg contains a pointer to a static,  null-
     terminated  character  buffer containing the service request
     response message. Note  that  both  nlsrmsg  and  the  data
     buffer are overwritten by each call to nlsrequest().





SunOS 5.11          Last change: 14 Nov 2002                    1






Networking Services Library Functions            nlsrequest(3NSL)



     If nlslog is non-zero, nlsrequest() prints  error  messages
     on stderr. Initially, nlslog is zero.

FILES
     /usr/lib/libnls.so.1    shared object


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     Unsafe                      
    


SEE ALSO
     nlsadmin(1M),   terror(3NSL),   tsnd(3NSL),   trcv(3NSL),
     attributes(5)

WARNINGS
     nlsrequest() cannot always be certain that the remote server
     process has been successfully started.  In this case, nlsre-
     quest() returns with no  indication  of  an  error  and  the
     caller  will  receive  notification of a disconnect event by
     way of a TLOK error before or during the first tsnd()  or
     trcv() call.

NOTES
     These interfaces are unsafe in  multithreaded  applications.
     Unsafe  interfaces  should  be  called  only  from  the main
     thread.



















SunOS 5.11          Last change: 14 Nov 2002                    2