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.1 2000/06/02 23:11:14 fvdl 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 int 23.Fn rpc_reg "rpcprog_t prognum" "rpcvers_t versnum" "rpcproc_t procnum" "char *(*procname)()" "xdrproc_t inproc" "xdrproc_t outproc" "char *nettype" 24.Ft bool_t 25.Fn svc_reg "SVCXPRT *xprt" "const rpcprog_t prognum" "const rpcvers_t versnum" "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 "int cred_flavor" "enum auth_stat (*handler)(struct svc_req *, struct rpc_msg *)" 30.Ft void 31.Fn xprt_register "SVCXPRT *xprt" 32.Ft void 33.Fn xprt_unregister "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.Bl -tag -width XXXXX 51.It Fn rpc_reg 52Register program 53.Fa prognum , 54procedure 55.Fa procname , 56and version 57.Fa versnum 58with the RPC 59service package. 60If a request arrives for program 61.Fa prognum , 62version 63.Fa versnum , 64and procedure 65.Fa procnum , 66.Fa procname 67is called with a pointer to its argument(s); 68.Fa procname 69should return a pointer to its static result(s); 70.Fa inproc 71is the XDR function used to decode the arguments while 72.Fa outproc 73is the XDR function used to encode the results. 74Procedures are registered on all available transports of the class 75.Fa nettype . 76See 77.Xr rpc 3 . 78This routine returns 0 if the registration succeeded, 79\-1 otherwise. 80.It Fn svc_reg 81Associates 82.Fa prognum 83and 84.Fa versnum 85with the service dispatch procedure, 86.Fa dispatch . 87If 88.Fa netconf 89is 90.Dv NULL , 91the service is not registered with the 92.Xr rpcbind 8 93service. 94If 95.Fa netconf 96is non-zero, 97then a mapping of the triple 98.Bq Fa prognum , versnum , netconf->nc_netid 99to 100.Fa xprt->xp_ltaddr 101is established with the local rpcbind 102service. 103.Pp 104The 105.Fn svc_reg 106routine returns 1 if it succeeds, 107and 0 otherwise. 108.It Fn svc_unreg 109Remove from the rpcbind 110service, all mappings of the triple 111.Bq Fa prognum , versnum , No all-transports 112to network address 113and all mappings within the RPC service package 114of the double 115.Bq Fa prognum , versnum 116to dispatch routines. 117.It Fn svc_auth_reg 118Registers the service authentication routine 119.Fa handler 120with the dispatch mechanism so that it can be 121invoked to authenticate RPC requests received 122with authentication type 123.Fa cred_flavor . 124This interface allows developers to add new authentication 125types to their RPC applications without needing to modify 126the libraries. 127Service implementors usually do not need this routine. 128.Pp 129Typical service application would call 130.Fn svc_auth_reg 131after registering the service and prior to calling 132.Fn svc_run . 133When needed to process an RPC credential of type 134.Fa cred_flavor , 135the 136.Fa handler 137procedure will be called with two arguments, 138.Fa "struct svc_req *rqst" 139and 140.Fa "struct rpc_msg *msg" , 141and is expected to return a valid 142.Vt "enum auth_stat" 143value. 144There is no provision to change or delete an authentication handler 145once registered. 146.Pp 147The 148.Fn svc_auth_reg 149routine returns 0 if the registration is successful, 1501 if 151.Fa cred_flavor 152already has an authentication handler registered for it, 153and \-1 otherwise. 154.It Fn xprt_register 155After RPC service transport handle 156.Fa xprt 157is created, it is registered with the RPC 158service package. 159This routine modifies the global variable 160.Va svc_fdset 161(see 162.Xr rpc_svc_calls 3 ) . 163Service implementors usually do not need this routine. 164.It Fn xprt_unregister 165Before an RPC service transport handle 166.Fa xprt 167is destroyed, it unregisters itself with the 168RPC service package. 169This routine modifies the global variable 170.Va svc_fdset 171(see 172.Xr rpc_svc_calls 3 ) . 173Service implementors usually do not need this routine. 174.El 175.Sh SEE ALSO 176.Xr select 2 , 177.Xr rpc 3 , 178.Xr rpc_svc_calls 3 , 179.Xr rpc_svc_create 3 , 180.Xr rpc_svc_err 3 , 181.Xr rpcbind 3 , 182.Xr rpcbind 8 183