svc_create man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

rpc_svc_create(3NSL) Networking Services Library Functionsrpc_svc_create(3NSL)

NAME
       rpc_svc_create,	svc_control,  svc_create,  svc_destroy, svc_dg_create,
       svc_fd_create,	 svc_raw_create,    svc_tli_create,	svc_tp_create,
       svc_vc_create,  svc_door_create	- library routines for the creation of
       server handles

SYNOPSIS
       #include <rpc/rpc.h>

       bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);

       int svc_create(const void (*dispatch)(const  struct  svc_req  *,	 const
       SVCXPRT	*),  const  rpcprog_t  prognum, const rpcvers_t versnum, const
       char *nettype);

       void svc_destroy(SVCXPRT *xprt);

       SVCXPRT *svc_dg_create(const int fildes,	 const	uint_t	sendsz,	 const
       uint_t recvsz);

       SVCXPRT	*svc_fd_create(const  int  fildes,  const uint_t sendsz, const
       uint_t recvsz);

       SVCXPRT *svc_raw_create(void);

       SVCXPRT *svc_tli_create(const int fildes, const struct netconfig	 *net‐
       conf, const struct t_bind *bind_addr, const uint_t sendsz, const uint_t
       recvsz);

       SVCXPRT *svc_tp_create(const void (*dispatch)(const struct  svc_req  *,
       const  SVCXPRT  *)),  const rpcprog_t prognum, const rpcvers_t versnum,
       const struct netconfig *netconf);

       SVCXPRT *svc_vc_create(const int fildes,	 const	uint_t	sendsz,	 const
       uint_t recvsz);

       SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
       const rpcprog_t prognum, const rpcvers_t versnum, const uint_t sendsz);

DESCRIPTION
       These routines are part of the RPC library which allows C language pro‐
       grams to make procedure calls on servers across the network. These rou‐
       tines deal with the creation of service handles.	 Once  the  handle  is
       created, the server can be invoked by calling svc_run().

   Routines
       See rpc(3NSL) for the definition of the	SVCXPRT data structure.

       svc_control()	       A  function  to	change or retrieve information
			       about a service object. req indicates the  type
			       of  operation  and  info	 is  a	pointer to the
			       information.  The  supported  values  of	  req,
			       their argument types, and what they do are:

			       SVCGET_VERSQUIET

				   If a request is received for a program num‐
				   ber served by this server but  the  version
				   number is outside the range registered with
				   the server, an  RPC_PROGVERSMISMATCH	 error
				   will normally be returned.	info should be
				   a pointer to an integer.   Upon  successful
				   completion of the SVCGET_VERSQUIET request,
				   *info contains an integer  which  describes
				   the	server's  current  behavior:   0 indi‐
				   cates normal server behavior, that  is,  an
				   RPC_PROGVERSMISMATCH	   error    will    be
				   returned.  1	 indicates  that  the  out  of
				   range request will be silently ignored.

			       SVCSET_VERSQUIET

				   If a request is received for a program num‐
				   ber served by this server but  the  version
				   number is outside the range registered with
				   the server, an  RPC_PROGVERSMISMATCH	 error
				   will normally be returned.  It is sometimes
				   desirable to change this  behavior.	  info
				   should  be a pointer to an integer which is
				   either  0, indicating normal server	behav‐
				   ior	and an RPC_PROGVERSMISMATCH error will
				   be returned, or  1, indicating that the out
				   of	range	request	  should  be  silently
				   ignored.

			       SVCGET_XID

				   Returns  the	 transaction   ID  of  connec‐
				   tion−oriented  and connectionless transport
				   service calls. The transaction  ID  assists
				   in uniquely identifying client requests for
				   a given  RPC version, program number,  pro‐
				   cedure,  and client. The transaction	 ID is
				   extracted from the service transport handle
				   svc.	   info	 must  be  a  pointer	to  an
				   unsigned long. Upon	successful  completion
				   of the  SVCGET_XID request,	*info contains
				   the transaction  ID. Note  that  rendezvous
				   and	raw  service  handles  do not define a
				   transaction	ID. Thus, if the service  han‐
				   dle	is  of rendezvous or raw type, and the
				   request is of  type	 SVCGET_XID,  svc_con‐
				   trol()  will	 return	 FALSE. Note also that
				   the transaction  ID read by the server  can
				   be  set by the client through the suboption
				   CLSET_XID	in     clnt_control().	   See
				   clnt_create(3NSL)

			       SVCSET_RECVERRHANDLER

				   Attaches  or	 detaches a disconnection han‐
				   dler to the service handle, svc, that  will
				   be  called  when  a transport error arrives
				   during the reception of a request  or  when
				   the server is waiting for a request and the
				   connection shuts down. This handler is only
				   useful  for	a  connection oriented service
				   handle.

				   *info contains the  address	of  the	 error
				   handler to attach, or NULL to detach a pre‐
				   viously defined one. The error handler  has
				   two	arguments.  It	has  a	pointer to the
				   erroneous service handle. It	 also  has  an
				   integer  that indicates if the full service
				   is closed (when equal  to  zero),  or  that
				   only	 one  connection  on  this  service is
				   closed (when not equal to zero).

				   void handler (const SVCXPRT *svc, const bool_t isAConnection);

				   With the service handle address,  svc,  the
				   error  handler is able to detect which con‐
				   nection has failed and to  begin  an	 error
				   recovery  process. The error handler can be
				   called by multiple threads  and  should  be
				   implemented in an MT-safe way.

			       SVCGET_RECVERRHANDLER

				   Upon	   successful	 completion   of   the
				   SVCGET_RECVERRHANDLER request,  *info  con‐
				   tains   the	address	 of  the  handler  for
				   receiving errors. Upon failure, *info  con‐
				   tains NULL.

			       This  routine returns TRUE if the operation was
			       successful. Otherwise, it returns false.

       svc_create()	       svc_create() creates server handles for all the
			       transports belonging to the class nettype.

			       nettype defines a class of transports which can
			       be  used	 for  a	 particular  application.  The
			       transports  are tried in left to right order in
			       NETPATH variable or in top to bottom  order  in
			       the  netconfig database. If nettype is NULL, it
			       defaults to netpath.

			       svc_create() registers itself with the  rpcbind
			       service	(see  rpcbind(1M)). dispatch is called
			       when there is a remote procedure call  for  the
			       given  prognum and versnum; this requires call‐
			       ing     svc_run()     (see     svc_run()	    in
			       rpc_svc_reg(3NSL)).  If	svc_create() succeeds,
			       it returns the number of server handles it cre‐
			       ated,  otherwise it returns 0 and an error mes‐
			       sage is logged.

       svc_destroy()	       A function macro that destroys the RPC  service
			       handle xprt. Destruction usually involves deal‐
			       location of private data structures,  including
			       xprt  itself.   Use  of xprt is undefined after
			       calling this routine.

       svc_dg_create()	       This routine creates a connectionless RPC  ser‐
			       vice  handle, and returns a pointer to it. This
			       routine returns NULL if it fails, and an	 error
			       message is logged. sendsz and recvsz are param‐
			       eters used to specify the size of the  buffers.
			       If  they	 are  0, suitable defaults are chosen.
			       The file descriptor fildes should be  open  and
			       bound.	The  server  is	 not  registered  with
			       rpcbind(1M).

			       Warning: since  connectionless-based  RPC  mes‐
			       sages  can  only hold limited amount of encoded
			       data, this transport cannot be used for	proce‐
			       dures  that take large arguments or return huge
			       results.

       svc_fd_create()	       This routine creates a service  on  top	of  an
			       open and bound file descriptor, and returns the
			       handle to it. Typically, this descriptor	 is  a
			       connected file descriptor for a connection-ori‐
			       ented transport.	 sendsz	 and  recvsz  indicate
			       sizes for the send and receive buffers. If they
			       are 0, reasonable  defaults  are	 chosen.  This
			       routine	returns NULL if it fails, and an error
			       message is logged.

       svc_raw_create()	       This routine creates an RPC service handle  and
			       returns	a  pointer  to	it.  The  transport is
			       really a buffer within  the  process's  address
			       space,  so  the corresponding RPC client should
			       live  in	  the	same   address	 space;	  (see
			       clnt_raw_create()   in  rpc_clnt_create(3NSL)).
			       This  routine  allows  simulation  of  RPC  and
			       acquisition  of	RPC  overheads	(such as round
			       trip times), without any kernel and  networking
			       interference.  This  routine returns NULL if it
			       fails, and an error message is logged.

			       Note: svc_run() should not be called  when  the
			       raw interface is being used.

       svc_tli_create()	       This  routine creates an RPC server handle, and
			       returns a pointer to it.	 fildes	 is  the  file
			       descriptor  on  which the service is listening.
			       If  fildes  is  RPC_ANYFD,  it  opens  a	  file
			       descriptor  on  the transport specified by net‐
			       conf. If the file  descriptor  is  unbound  and
			       bindaddr	 is  non-null  fildes  is bound to the
			       address specified by bindaddr, otherwise fildes
			       is  bound  to  a	 default address chosen by the
			       transport.  In  the  case  where	 the   default
			       address	is  chosen,  the number of outstanding
			       connect requests is set to  8  for  connection-
			       oriented	 transports.  The user may specify the
			       size of the send and receive buffers  with  the
			       parameters  sendsz  and	recvsz	;  values of 0
			       choose suitable defaults. This routine  returns
			       NULL  if	 it  fails,  and  an  error message is
			       logged. The server is not registered  with  the
			       rpcbind(1M) service.

       svc_tp_create()	       svc_tp_create() creates a server handle for the
			       network specified  by  netconf,	and  registers
			       itself  with  the  rpcbind service. dispatch is
			       called when there is a  remote  procedure  call
			       for   the   given  prognum  and	versnum;  this
			       requires	 calling  svc_run().   svc_tp_create()
			       returns the service handle if it succeeds, oth‐
			       erwise a NULL is returned and an error  message
			       is logged.

       svc_vc_create()	       This  routine creates a connection-oriented RPC
			       service and returns a pointer to it. This  rou‐
			       tine  returns  NULL  if	it fails, and an error
			       message is logged. The users  may  specify  the
			       size  of	 the send and receive buffers with the
			       parameters  sendsz  and	recvsz;	 values	 of  0
			       choose  suitable	 defaults. The file descriptor
			       fildes should be open and bound. The server  is
			       not registered with the rpcbind(1M) service.

       svc_door_create()       This  routine creates an RPC server handle over
			       doors and returns a pointer to it. Doors	 is  a
			       transport  mechanism that facilitates fast data
			       transfer between processes on the same machine.
			       for the given program The user may set the size
			       of the send buffer with the  parameter  sendsz.
			       If  sendsz is 0, the corresponding default buf‐
			       fer  size  is  16  Kbyte.  If  successful,  the
			       svc_door_create()  routine  returns the service
			       handle. Otherwise it returns NULL  and  sets  a
			       value for rpc_createerr. The server is not reg‐
			       istered with rpcbind(1M).

ATTRIBUTES
       See attributes(5)  for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Architecture		     │All			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWcsl (32-bit)		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │			     │SUNWcslx (64-bit)		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Evolving			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       rpcbind(1M),  rpc(3NSL),	 rpc_clnt_create(3NSL),	  rpc_svc_calls(3NSL),
       rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)

SunOS 5.10			    Aug 2001		  rpc_svc_create(3NSL)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net