'\"macro stdmacro
.if n .pH g3n.rpc_svc_cr @(#)rpc_svc_cr	40.5 of 10/10/89
.\" Copyright 1989 AT&T
.\" ident	"@(#)svid_rs:rs_lib/rpc_svc_create	1.3"
.\" @(#)rpc_svc_crea 1.3 89/06/28 SMI;
'\" macro stdmacro
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.nr X
.if \nX=0 .ds x} rpc_svc_create 3N "" "\&"
.if \nX=1 .ds x} rpc_svc_create 3N ""
.if \nX=2 .ds x} rpc_svc_create 3N "" "\&"
.if \nX=3 .ds x} rpc_svc_create "" "" "\&"
.TH \*(x}
.SH NAME
.na
\f4rpc_svc_create\fP: \f4 svc_create\f1, \f4svc_destroy\f1, \f4svc_dg_create\f1, \f4svc_fd_create\f1, \f4svc_raw_create\f1, \f4svc_tli_create\f1, \f4svc_tp_create\f1, \f4svc_vc_create\f1 \- library routines for dealing with the creation of server handles
.ad
.SH DESCRIPTION
These routines are part of the RPC
library which allows C language programs to make procedure
calls on servers across the network.
These routines deal with the creation of service handles.
Once the handle is created, the server can be invoked by calling
\f4svc_run\fP.
.SS Routines
See \f4rpc\fP(3N) for the definition of the 
\f4SVCXPRT\f1
data structure.
.P
.ft 4
.nf
.sp .5
#include <rpc/rpc.h>
.fi
.ft 1
.if t .ne 8
.P
.ft 4
.nf
.sp .5
int
svc_create(
	const void (*dispatch)(const struct svc_req *, const SVCXPRT *),
	const u_long prognum, const u_long versnum,
	const char *nettype);
.fi
.ft 1
.IP
\f4svc_create\f1
creates server handles for all the transports
belonging to the class
\f2nettype\f1.
.IP
\f2nettype\f1
defines a class of transports which can be used
for a particular application.
The transports are tried in
left to right order in
\f4NETPATH\f1
variable or in top to down order in
the netconfig database.
.IP
If
\f2nettype\f1
is \f4NULL\fP,
it defaults to
\f4netpath\f1.
\f4svc_create\f1
registers itself with the
\f4rpcbind\f1 service
[see \f4rpcbind\fP(1M)].
\f2dispatch\f1
is called when there is a remote procedure call
for the given
\f2prognum\f1
and
\f2versnum\f1;
this requires calling
\f4svc_run\f1
[see \f4svc_run\f1 in \f4rpc_svc_reg\fP(3N)].
If it succeeds,
\f4svc_create\f1
returns the number of server
handles it created,
otherwise it returns \f40\f1 and the error message is logged.
.br
.if t .ne 7
.P
.ft 4
.nf
.sp .5
void
svc_destroy(SVCXPRT *xprt);
.fi
.ft 1
.IP
A function macro that destroys the RPC
service transport handle
\f2xprt\f1.
Destruction usually involves deallocation
of private data structures,
including
\f2xprt\f1
itself.
Use of
\f2xprt\f1
is undefined after calling this routine.
.br
.if t .ne 10
.P
.ft 4
.nf
.sp .5
SVCXPRT *
svc_dg_create(const int fd, const u_int sendsz, const u_int recvsz);
.fi
.ft 1
.IP
This routine creates a connectionless
RPC service handle,
and returns a pointer to it.
This routine returns \f4NULL\fP
if it fails, and an error message is logged.
\f2sendsz\f1
and
\f2recvsz\f1
are parameters used to specify the size of the
buffers.
If they are \f40\f1,
suitable defaults are chosen.
The file descriptor
\f2fd\f1
should be open and bound.
.IP
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.
.br
.if t .ne 11
.P
.ft 4
.nf
.sp .5
SVCXPRT *
svc_fd_create(const int fd, const u_int sendsz, const u_int recvsz);
.fi
.ft 1
.IP
This routine creates a service on top of any open and bound descriptor,
and returns the handle to it.
Typically,
this descriptor is a connected file descriptor for a
connection-oriented transport.
\f2sendsz\f1
and
\f2recvsz\f1
indicate sizes for the send and receive buffers.
If they are \f40\f1,
a reasonable default is chosen.
This routine returns
\f4NULL\fP,
if it fails, and an error message is logged.
.br
.if t .ne 11
.P
.ft 4
.nf
.sp .5
SVCXPRT *
svc_raw_create(void);
.fi
.ft 1
.IP
This routine creates a toy
RPC service transport,
to which it returns a pointer.
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
\f4clnt_raw_create\f1
in
rpc_clnt_create\f1].
This routine allows simulation of RPC
and acquisition of RPC
overheads (such as round trip times),
without any kernel interference.
This routine returns \f4NULL\fP
if it fails, and an error message is logged.
.br
.if t .ne 8
.P
.ft 4
.nf
.sp .5
SVCXPRT *
svc_tli_create(const int fd, const struct netconfig *netconf,
	const struct t_bind *bindaddr, const u_int sendsz,
	const u_int recvsz);
.fi
.ft 1
.IP
This routine creates an RPC
server handle, and returns a pointer to it.
\f2fd\f1
is the file descriptor on which the service is listening. 
If
\f2fd\f1
is
\f4RPC_ANYFD\f1,
it opens a file descriptor on the
transport specified by
\f2netconf\f1.
If the file descriptor is unbound, it is bound to the address
specified by
\f2bindaddr\f1, 
if
\f2bindaddr\f1
is non-null, otherwise
it 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
\f2sendsz\f1
and
\f2recvsz\f1;
values of \f40\f1 choose suitable defaults.
This routine returns \f4NULL\fP if it fails,
and an error message is logged.
.br
.if t .ne 8
.P
.ft 4
.nf
.sp .5
SVCPRT *
svc_tp_create(const void (*dispatch)(const RQSTP *, const SVCXPRT *),
	const u_long prognum, const u_long versnum,
	const struct netconfig *netconf);
.fi
.ft 1
.IP
\f4svc_tp_create\f1
creates a server handle for the network
specified by
\f2netconf\f1,
and registers itself with the
\f4rpcbind\f1 service.
\f2dispatch\f1
is called when there is a remote procedure call
for the given
\f2prognum\f1
and
\f2versnum\f1;
this requires calling
\f4svc_run\f1.
\f4svc_tp_create\f1
returns the service handle if it succeeds,
otherwise a \f4NULL\fP is returned,
and an error message is logged.
.br
.if t .ne 11
.P
.ft 4
.nf
.sp .5
SVCXPRT *
svc_vc_create(const int fd, const u_int sendsz, const u_int recvsz);
.fi
.ft 1
.IP
This routine creates a connection-oriented RPC
service and returns a pointer to it.
This routine returns \f4NULL\fP
if it fails,
and an error message is logged.
The users may specify the size of the send and receive buffers
with the parameters
\f2sendsz\f1
and
\f2recvsz\f1;
values of \f40\f1 choose suitable defaults.
The file descriptor
\f2fd\f1
should be open and bound.
.SH SEE ALSO
.na
\f4rpcbind\fP(1M),
\f4rpc\fP(3N),
\f4rpc_svc_calls\fP(3N),
\f4rpc_svc_err\fP(3N),
\f4rpc_svc_reg\fP(3N).
.ad
