1.\" @(#)rpc_svc_reg.3n 1.32 93/08/31 SMI; from SVr4 2.\" Copyright 1989 AT&T 3.\" @(#)rpc_svc_call 1.6 89/07/20 SMI; 4.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. 5.\" $NetBSD: rpc_svc_reg.3,v 1.11 2017/07/03 21:32:49 wiz Exp $ 6.Dd May 3, 1993 7.Dt RPC_SVC_REG 3 8.Os 9.Sh NAME 10.Nm rpc_svc_reg , 11.Nm rpc_reg , 12.Nm svc_reg , 13.Nm svc_unreg , 14.Nm svc_auth_reg , 15.Nm xprt_register , 16.Nm xprt_unregister 17.Nd library routines for registering servers 18.Sh LIBRARY 19.Lb libc 20.Sh SYNOPSIS 21.In rpc/rpc.h 22.Ft bool_t 23.Fn rpc_reg "const rpcprog_t prognum" "const rpcvers_t versnum" "const rpcproc_t procnum" "const char *(*procname)()" "const xdrproc_t inproc" "const xdrproc_t outproc" "const char *nettype" 24.Ft int 25.Fn svc_reg "const SVCXPRT *xprt" "const rpcprog_t prognum" "const rpcvers_t versnum" "const void (*dispatch(struct svc_req *, SVCXPRT *)" "const struct netconfig *netconf" 26.Ft void 27.Fn svc_unreg "const rpcprog_t prognum" "const rpcvers_t versnum" 28.Ft int 29.Fn svc_auth_reg "const int cred_flavor" "const enum auth_stat (*handler(struct svc_req *, struct rpc_msg *))" 30.Ft bool_t 31.Fn xprt_register "const SVCXPRT *xprt" 32.Ft void 33.Fn xprt_unregister "const SVCXPRT *xprt" 34.Sh DESCRIPTION 35These routines are a part of the RPC 36library which allows the RPC 37servers to register themselves with rpcbind 38(see 39.Xr rpcbind 8 ) , 40and associate the given program and version 41number with the dispatch function. 42When the RPC server receives a RPC request, the library invokes the 43dispatch routine with the appropriate arguments. 44.Sh ROUTINES 45See 46.Xr rpc 3 47for the definition of the 48.Vt SVCXPRT 49data structure. 50.Pp 51.Bl -tag -width XXXXX 52.It Fn rpc_reg 53Register program 54.Fa prognum , 55procedure 56.Fa procname , 57and version 58.Fa versnum 59with the RPC 60service package. 61If a request arrives for program 62.Fa prognum , 63version 64.Fa versnum , 65and procedure 66.Fa procnum , 67.Fa procname 68is called with a pointer to its parameter(s); 69.Fa procname 70should return a pointer to its static result(s); 71.Fa inproc 72is the XDR function used to decode the parameters while 73.Fa outproc 74is the XDR function used to encode the results. 75Procedures are registered on all available transports of the class 76.Fa nettype . 77See 78.Xr rpc 3 . 79This routine returns 0 if the registration succeeded, 80-1 otherwise. 81.Pp 82.It Fn svc_reg 83Associates 84.Fa prognum 85and 86.Fa versnum 87with the service dispatch procedure, 88.Fa dispatch . 89If 90.Fa netconf 91is 92.Dv NULL , 93the service is not registered with the 94.Xr rpcbind 8 95service. 96If 97.Fa netconf 98is non-zero, 99then a mapping of the triple 100[ 101.Fa prognum , 102.Fa versnum , 103.Fa netconf->nc_netid ] 104to 105.Fa xprt->xp_ltaddr 106is established with the local rpcbind 107service. 108.Pp 109The 110.Fn svc_reg 111routine returns 1 if it succeeds, 112and 0 otherwise. 113.Pp 114.It Fn svc_unreg 115Remove from the rpcbind 116service, all mappings of the triple 117[ 118.Fa prognum , 119.Fa versnum , 120all-transports ] 121to network address 122and all mappings within the RPC service package 123of the double 124[ 125.Fa prognum , 126.Fa versnum ] 127to dispatch routines. 128.Pp 129.It Fn svc_auth_reg 130Registers the service authentication routine 131.Fa handler 132with the dispatch mechanism so that it can be 133invoked to authenticate RPC requests received 134with authentication type 135.Fa cred_flavor . 136This interface allows developers to add new authentication 137types to their RPC applications without needing to modify 138the libraries. 139Service implementors usually do not need this routine. 140.Pp 141Typical service application would call 142.Fn svc_auth_reg 143after registering the service and prior to calling 144.Fn svc_run . 145When needed to process an RPC credential of type 146.Fa cred_flavor , 147the 148.Fa handler 149procedure will be called with two parameters 150.Fa "struct svc_req *rqst" , 151and 152.Fa "struct rpc_msg * msg" , 153and is expected to return a valid 154.Vt "enum auth_stat" 155value. 156There is no provision to change or delete an authentication handler 157once registered. 158.Pp 159The 160.Fn svc_auth_reg 161routine returns 0 if the registration is successful, 1621 if 163.Fa cred_flavor 164already has an authentication handler registered for it, 165and -1 otherwise. 166.Pp 167.It Fn xprt_register 168After RPC service transport handle 169.Fa xprt 170is created, it is registered with the RPC 171service package. 172This routine modifies the global variable 173.Va svc_fdset 174(see 175.Xr rpc_svc_calls 3 ) . 176Service implementors usually do not need this routine. 177.Pp 178.It Fn xprt_unregister 179Before an RPC service transport handle 180.Fa xprt 181is destroyed, it unregisters itself with the 182RPC service package. 183This routine modifies the global variable 184.Va svc_fdset 185(see 186.Xr rpc_svc_calls 3 ) . 187Service implementors usually do not need this routine. 188.El 189.Sh SEE ALSO 190.Xr select 2 , 191.Xr rpc 3 , 192.Xr rpc_svc_calls 3 , 193.Xr rpc_svc_create 3 , 194.Xr rpc_svc_err 3 , 195.Xr rpcbind 3 , 196.Xr rpcbind 8 197