svc_vc_create man page on SmartOS

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

RPC_SVC_CREATE(3NSL)					  RPC_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 - server handle creation routines

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 *netconf,
	    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 opera‐
			    tion 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	number
						     served by this server but
						     the   version  number  is
						     outside the range	regis‐
						     tered with the server, an
						     RPC_PROGVERSMISMATCH
						     error  will  normally  be
						     returned.	info should be
						     a	pointer to an integer.
						     Upon  successful  comple‐
						     tion  of  the SVCGET_VER‐
						     SQUIET  request,	 *info
						     contains an integer which
						     describes	the   server's
						     current	behavior:    0
						     indicates	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	number
						     served by this server but
						     the   version  number  is
						     outside the range	regis‐
						     tered with the server, an
						     RPC_PROGVERSMISMATCH
						     error  will  normally  be
						     returned.	 It  is	 some‐
						     times desirable to change
						     this    behavior.	  info
						     should be a pointer to an
						     integer which  is	either
						     0,	   indicating	normal
						     server  behavior  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 connection−oriented
						     and connectionless trans‐
						     port  service  calls. The
						     transaction   ID  assists
						     in	 uniquely  identifying
						     client  requests  for   a
						     given  RPC	 version, pro‐
						     gram  number,  procedure,
						     and  client. The transac‐
						     tion   ID	is   extracted
						     from  the	service trans‐
						     port  handle   svc.  info
						     must  be a pointer	 to an
						     unsigned long.  Upon suc‐
						     cessful completion of the
						     SVCGET_XID	      request,
						     *info contains the trans‐
						     action   ID.  Note	  that
						     rendezvous	 and  raw ser‐
						     vice   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_control() 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 handler  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 connec‐
						     tion  shuts  down.	  This
						     handler  is  only	useful
						     for a connection oriented
						     service handle.

						     *info     contains	   the
						     address of the error han‐
						     dler  to  attach, or NULL
						     to	 detach	 a  previously
						     defined  one.  The	 error
						     handler  has  two	 argu‐
						     ments.  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  ser‐
						     vice  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    connection   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  comple‐
						     tion	 of	   the
						     SVCGET_RECVERRHANDLER
						     request,  *info  contains
						     the address of  the  han‐
						     dler     for    receiving
						     errors.   Upon   failure,
						     *info contains NULL.

			    SVCSET_CONNMAXREC
						     Set  the  maximum	record
						     size   (in	  bytes)   and
						     enable  non-blocking mode
						     for this service  handle.
						     Value can be set and read
						     for both  connection  and
						     non-connection   oriented
						     transports,    but	    is
						     silently  ignored for the
						     non-connection   oriented
						     case.  The	 info argument
						     should be a pointer to an
						     int.

			    SVCGET_CONNMAXREC
						     Get  the  maximum	record
						     size  for	this   service
						     handle.   Zero  means  no
						     maximum in effect and the
						     connection is in blocking
						     mode. The result  is  not
						     significant  for non-con‐
						     nection  oriented	trans‐
						     ports.  The info argument
						     should be a pointer to an
						     int.

			    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 vari‐
			    able or in top to bottom order  in	the  netconfig
			    database.  If nettype is NULL, it defaults to net‐
			    path.

			    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  calling
			    svc_run() (see svc_run() in rpc_svc_reg(3NSL)). If
			    svc_create()  succeeds,  it	 returns the number of
			    server handles it created, otherwise it returns  0
			    and an error message is logged.

       svc_destroy()
			    A  function	 macro	that  destroys the RPC service
			    handle xprt.  Destruction usually involves deallo‐
			    cation  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 service
			    handle, and returns a pointer to it. This  routine
			    returns  NULL if it fails, and an error message is
			    logged. sendsz and recvsz are parameters  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  messages
			    can only hold limited amount of encoded data, this
			    transport cannot be used for procedures 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-oriented	trans‐
			    port.  sendsz  and	recvsz	indicate sizes for the
			    send and receive buffers. If they are  0,  reason‐
			    able  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 simu‐
			    lation 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 netconf.	 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 out‐
			    standing connect requests is set to 8 for  connec‐
			    tion-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,  otherwise  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  routine
			    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 buffer 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 registered with rpcbind(1M). The
			    SVCSET_CONNMAXREC and  SVCGET_CONNMAXREC  svc_con‐
			    trol()  requests can be used to set and change the
			    maximum allowed request size for the doors	trans‐
			    port.

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Architecture	    │ All	      │
       ├────────────────────┼─────────────────┤
       │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)

				 Dec 27, 2013		  RPC_SVC_CREATE(3NSL)
[top]

List of man pages available for SmartOS

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