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