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