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