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