lib/libc/rpc/rpc_svc_reg.3

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