'\" te
.\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
.\"  Copyright 1989 AT&T  Copyright (c) 1995 Sun Microsystems, Inc.   All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH RPC_SVC_REG 3NSL "Nov 24, 2014"
.SH NAME
rpc_svc_reg, rpc_reg, svc_reg, svc_unreg, svc_auth_reg, xprt_register,
xprt_unregister \- library routines for registering servers
.SH DESCRIPTION
.LP
These routines are a part of the \fBRPC\fR library which allows the \fBRPC\fR
servers to register themselves with \fBrpcbind()\fR (see  \fBrpcbind\fR(1M)),
and associate the given program and version number with the dispatch function.
When the RPC server receives a RPC request, the library invokes the dispatch
routine with the appropriate arguments.
.SS "Routines"
.LP
See \fBrpc\fR(3NSL) for the definition of the  \fBSVCXPRT\fR data structure.
.sp
.in +2
.nf
\fB#include <rpc/rpc.h>\fR
.fi
.in -2
.sp

.sp
.ne 2
.na
\fBbool_t rpc_reg(const rpcprog_t \fIprognum\fR, const rpcvers_t \fIversnum\fR,
const rpcproc_t \fIprocnum\fR, char * (*\fIprocname\fR)(\|), const xdrproc_t
\fIinproc\fR, const xdrproc_t \fIoutproc\fR, const char *\fInettype\fR);\fR
.ad
.sp .6
.RS 4n
Register program \fIprognum\fR, procedure \fIprocname\fR, and version
\fIversnum\fR with the \fBRPC\fR service package. If a request arrives for
program \fIprognum\fR, version \fIversnum\fR, and procedure \fIprocnum\fR,
\fIprocname\fR is called with a pointer to its parameter(s); \fIprocname\fR
should return a pointer to its \fBstatic\fR result(s). The \fIarg\fR parameter
to \fIprocname\fR is a pointer to the (decoded) procedure argument.
\fIinproc\fR is the XDR function used to decode the parameters while
\fIoutproc\fR is the XDR function used to encode the results. Procedures are
registered on all available transports of the class \fInettype\fR. See
\fBrpc\fR(3NSL). This routine returns \fB0\fR if the registration succeeded,
\fB\(mi1\fR otherwise.
.RE

.sp
.ne 2
.na
\fBint svc_reg(const SVCXPRT *\fIxprt\fR, const rpcprog_t \fIprognum\fR, const
rpcvers_t \fIversnum\fR, const void (*\fIdispatch\fR)(\|), const struct
netconfig *\fInetconf\fR);\fR
.ad
.sp .6
.RS 4n
Associates \fIprognum\fR and \fIversnum\fR with the service dispatch procedure,
\fIdispatch\fR. If \fInetconf\fR is \fINULL\fR, the service is not registered
with the \fBrpcbind\fR service.  For example, if a service has already been
registered using some other means, such as \fBinetd\fR (see  \fBinetd\fR(1M)),
it will not need to be registered again. If \fInetconf\fR is non-zero, then a
mapping of the triple [\fIprognum\fR, \fI versnum\fR, \fInetconf\fR->\fI]\fR to
\fIxprt\fR-> \fIxp_ltaddr\fR is established with the local \fBrpcbind\fR
service.
.sp
The \fBsvc_reg()\fR routine returns \fB1\fR if it succeeds, and \fB0\fR
otherwise.
.RE

.sp
.ne 2
.na
\fBvoid svc_unreg(const rpcprog_t \fIprognum\fR, const rpcvers_t
\fIversnum\fR);\fR
.ad
.sp .6
.RS 4n
Remove from the \fBrpcbind\fR service, all mappings of the triple
[\fIprognum\fR, \fIversnum\fR, \fIall-transports\fR] to network address and all
mappings within the RPC service package of the double [\fIprognum\fR,
\fIversnum\fR] to dispatch routines.
.RE

.sp
.ne 2
.na
\fBint svc_auth_reg(const int \fIcred_flavor\fR, const enum auth_stat
(*handler)(\|));\fR
.ad
.sp .6
.RS 4n
Registers the service authentication routine \fIhandler\fR with the dispatch
mechanism so that it can be invoked to authenticate RPC requests received with
authentication type \fIcred_flavor\fR. This interface allows developers to add
new authentication types to their RPC applications without needing to modify
the libraries. Service implementors usually do not need this routine.
.sp
Typical service application would call \fBsvc_auth_reg()\fR after registering
the service and prior to calling \fBsvc_run()\fR. When needed to process an RPC
credential of type \fIcred_flavor\fR, the \fIhandler\fR procedure will be
called with two parameters \fB (struct svc_req *\fR\fIrqst\fR\fB,\fR \fBstruct
rpc_msg *\fR\fImsg\fR\fB)\fR and is expected to return a valid \fBenum
auth_stat\fR value. There is no provision to change or delete an authentication
handler once registered.
.sp
The \fBsvc_auth_reg()\fR routine returns \fB0\fR if the registration is
successful, \fB1\fR if \fIcred_flavor\fR already has an authentication handler
registered for it, and \fB\(mi1\fR otherwise.
.RE

.sp
.ne 2
.na
\fBvoid xprt_register(const SVCXPRT *\fIxprt\fR);\fR
.ad
.sp .6
.RS 4n
After \fBRPC\fR service transport handle \fIxprt\fR is created, it is
registered with the \fBRPC\fR service package. This routine modifies the global
variables \fBsvc_fdset\fR and \fBsvc_pollfd\fR (see \fBrpc_svc_calls\fR(3NSL)).
Service implementors usually do not need this routine.
.RE

.sp
.ne 2
.na
\fBvoid xprt_unregister(const SVCXPRT *\fIxprt\fR);\fR
.ad
.sp .6
.RS 4n
Before an \fBRPC\fR service transport handle \fIxprt\fR is destroyed, it
unregisters itself with the \fBRPC\fR service package. This routine modifies
the global variables \fBsvc_fdset\fR and \fBsvc_pollfd\fR (see
\fBrpc_svc_calls\fR(3NSL)). Service implementors usually do not need this
routine.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.LP
\fBinetd\fR(1M), \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_svc_calls\fR(3NSL),
\fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpcbind\fR(3NSL),
\fBselect\fR(3C), \fBattributes\fR(5)