usr/src/man/man3nsl/rpc_svc_reg.3nsl

   1 '\" te
   2 .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
   3 .\"  Copyright 1989 AT&T  Copyright (c) 1995 Sun Microsystems, Inc.   All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH RPC_SVC_REG 3NSL "Nov 24, 2014"
   8 .SH NAME
   9 rpc_svc_reg, rpc_reg, svc_reg, svc_unreg, svc_auth_reg, xprt_register,
  10 xprt_unregister \- library routines for registering servers
  11 .SH DESCRIPTION
  12 .LP
  13 These routines are a part of the \fBRPC\fR library which allows the \fBRPC\fR
  14 servers to register themselves with \fBrpcbind()\fR (see  \fBrpcbind\fR(1M)),
  15 and associate the given program and version number with the dispatch function.
  16 When the RPC server receives a RPC request, the library invokes the dispatch
  17 routine with the appropriate arguments.
  18 .SS "Routines"
  19 .LP
  20 See \fBrpc\fR(3NSL) for the definition of the  \fBSVCXPRT\fR data structure.
  21 .sp
  22 .in +2
  23 .nf
  24 \fB#include <rpc/rpc.h>\fR
  25 .fi
  26 .in -2
  27 .sp
  28
  29 .sp
  30 .ne 2
  31 .na
  32 \fBbool_t rpc_reg(const rpcprog_t \fIprognum\fR, const rpcvers_t \fIversnum\fR,
  33 const rpcproc_t \fIprocnum\fR, char * (*\fIprocname\fR)(\|), const xdrproc_t
  34 \fIinproc\fR, const xdrproc_t \fIoutproc\fR, const char *\fInettype\fR);\fR
  35 .ad
  36 .sp .6
  37 .RS 4n
  38 Register program \fIprognum\fR, procedure \fIprocname\fR, and version
  39 \fIversnum\fR with the \fBRPC\fR service package. If a request arrives for
  40 program \fIprognum\fR, version \fIversnum\fR, and procedure \fIprocnum\fR,
  41 \fIprocname\fR is called with a pointer to its parameter(s); \fIprocname\fR
  42 should return a pointer to its \fBstatic\fR result(s). The \fIarg\fR parameter
  43 to \fIprocname\fR is a pointer to the (decoded) procedure argument.
  44 \fIinproc\fR is the XDR function used to decode the parameters while
  45 \fIoutproc\fR is the XDR function used to encode the results. Procedures are
  46 registered on all available transports of the class \fInettype\fR. See
  47 \fBrpc\fR(3NSL). This routine returns \fB0\fR if the registration succeeded,
  48 \fB\(mi1\fR otherwise.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fBint svc_reg(const SVCXPRT *\fIxprt\fR, const rpcprog_t \fIprognum\fR, const
  55 rpcvers_t \fIversnum\fR, const void (*\fIdispatch\fR)(\|), const struct
  56 netconfig *\fInetconf\fR);\fR
  57 .ad
  58 .sp .6
  59 .RS 4n
  60 Associates \fIprognum\fR and \fIversnum\fR with the service dispatch procedure,
  61 \fIdispatch\fR. If \fInetconf\fR is \fINULL\fR, the service is not registered
  62 with the \fBrpcbind\fR service.  For example, if a service has already been
  63 registered using some other means, such as \fBinetd\fR (see  \fBinetd\fR(1M)),
  64 it will not need to be registered again. If \fInetconf\fR is non-zero, then a
  65 mapping of the triple [\fIprognum\fR, \fI versnum\fR, \fInetconf\fR->\fI]\fR to
  66 \fIxprt\fR-> \fIxp_ltaddr\fR is established with the local \fBrpcbind\fR
  67 service.
  68 .sp
  69 The \fBsvc_reg()\fR routine returns \fB1\fR if it succeeds, and \fB0\fR
  70 otherwise.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fBvoid svc_unreg(const rpcprog_t \fIprognum\fR, const rpcvers_t
  77 \fIversnum\fR);\fR
  78 .ad
  79 .sp .6
  80 .RS 4n
  81 Remove from the \fBrpcbind\fR service, all mappings of the triple
  82 [\fIprognum\fR, \fIversnum\fR, \fIall-transports\fR] to network address and all
  83 mappings within the RPC service package of the double [\fIprognum\fR,
  84 \fIversnum\fR] to dispatch routines.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fBint svc_auth_reg(const int \fIcred_flavor\fR, const enum auth_stat
  91 (*handler)(\|));\fR
  92 .ad
  93 .sp .6
  94 .RS 4n
  95 Registers the service authentication routine \fIhandler\fR with the dispatch
  96 mechanism so that it can be invoked to authenticate RPC requests received with
  97 authentication type \fIcred_flavor\fR. This interface allows developers to add
  98 new authentication types to their RPC applications without needing to modify
  99 the libraries. Service implementors usually do not need this routine.
 100 .sp
 101 Typical service application would call \fBsvc_auth_reg()\fR after registering
 102 the service and prior to calling \fBsvc_run()\fR. When needed to process an RPC
 103 credential of type \fIcred_flavor\fR, the \fIhandler\fR procedure will be
 104 called with two parameters \fB (struct svc_req *\fR\fIrqst\fR\fB,\fR \fBstruct
 105 rpc_msg *\fR\fImsg\fR\fB)\fR and is expected to return a valid \fBenum
 106 auth_stat\fR value. There is no provision to change or delete an authentication
 107 handler once registered.
 108 .sp
 109 The \fBsvc_auth_reg()\fR routine returns \fB0\fR if the registration is
 110 successful, \fB1\fR if \fIcred_flavor\fR already has an authentication handler
 111 registered for it, and \fB\(mi1\fR otherwise.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fBvoid xprt_register(const SVCXPRT *\fIxprt\fR);\fR
 118 .ad
 119 .sp .6
 120 .RS 4n
 121 After \fBRPC\fR service transport handle \fIxprt\fR is created, it is
 122 registered with the \fBRPC\fR service package. This routine modifies the global
 123 variables \fBsvc_fdset\fR and \fBsvc_pollfd\fR (see \fBrpc_svc_calls\fR(3NSL)).
 124 Service implementors usually do not need this routine.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fBvoid xprt_unregister(const SVCXPRT *\fIxprt\fR);\fR
 131 .ad
 132 .sp .6
 133 .RS 4n
 134 Before an \fBRPC\fR service transport handle \fIxprt\fR is destroyed, it
 135 unregisters itself with the \fBRPC\fR service package. This routine modifies
 136 the global variables \fBsvc_fdset\fR and \fBsvc_pollfd\fR (see
 137 \fBrpc_svc_calls\fR(3NSL)). Service implementors usually do not need this
 138 routine.
 139 .RE
 140
 141 .SH ATTRIBUTES
 142 .LP
 143 See \fBattributes\fR(5) for descriptions of the following attributes:
 144 .sp
 145
 146 .sp
 147 .TS
 148 box;
 149 c | c
 150 l | l .
 151 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 152 _
 153 MT-Level        MT-Safe
 154 .TE
 155
 156 .SH SEE ALSO
 157 .LP
 158 \fBinetd\fR(1M), \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_svc_calls\fR(3NSL),
 159 \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpcbind\fR(3NSL),
 160 \fBselect\fR(3C), \fBattributes\fR(5)