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 .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
  36 These routines are a part of the RPC
  37 library which allows the RPC
  38 servers to register themselves with rpcbind
  39 (see
  40 .Xr rpcbind 8 ) ,
  41 and associate the given program and version
  42 number with the dispatch function.
  43 When the RPC server receives a RPC request, the library invokes the
  44 dispatch routine with the appropriate arguments.
  45 .Sh Routines
  46 See
  47 .Xr rpc 3
  48 for the definition of the
  49 .Vt SVCXPRT
  50 data structure.
  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 argument(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 arguments 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 .It Fn svc_reg
  82 Associates
  83 .Fa prognum
  84 and
  85 .Fa versnum
  86 with the service dispatch procedure,
  87 .Fa dispatch .
  88 If
  89 .Fa netconf
  90 is
  91 .Dv NULL ,
  92 the service is not registered with the
  93 .Xr rpcbind 8
  94 service.
  95 If
  96 .Fa netconf
  97 is non-zero,
  98 then a mapping of the triple
  99 .Bq Fa prognum , versnum , netconf->nc_netid
 100 to
 101 .Fa xprt->xp_ltaddr
 102 is established with the local rpcbind
 103 service.
 104 .Pp
 105 The
 106 .Fn svc_reg
 107 routine returns 1 if it succeeds,
 108 and 0 otherwise.
 109 .It Fn svc_unreg
 110 Remove from the rpcbind
 111 service, all mappings of the triple
 112 .Bq Fa prognum , versnum , No all-transports
 113 to network address
 114 and all mappings within the RPC service package
 115 of the double
 116 .Bq Fa prognum , versnum
 117 to dispatch routines.
 118 .It Fn svc_auth_reg
 119 Registers the service authentication routine
 120 .Fa handler
 121 with the dispatch mechanism so that it can be
 122 invoked to authenticate RPC requests received
 123 with authentication type
 124 .Fa cred_flavor .
 125 This interface allows developers to add new authentication
 126 types to their RPC applications without needing to modify
 127 the libraries.
 128 Service implementors usually do not need this routine.
 129 .Pp
 130 Typical service application would call
 131 .Fn svc_auth_reg
 132 after registering the service and prior to calling
 133 .Fn svc_run .
 134 When needed to process an RPC credential of type
 135 .Fa cred_flavor ,
 136 the
 137 .Fa handler
 138 procedure will be called with two arguments,
 139 .Fa "struct svc_req *rqst"
 140 and
 141 .Fa "struct rpc_msg *msg" ,
 142 and is expected to return a valid
 143 .Vt "enum auth_stat"
 144 value.
 145 There is no provision to change or delete an authentication handler
 146 once registered.
 147 .Pp
 148 The
 149 .Fn svc_auth_reg
 150 routine returns 0 if the registration is successful,
 151 1 if
 152 .Fa cred_flavor
 153 already has an authentication handler registered for it,
 154 and \-1 otherwise.
 155 .It Fn xprt_register
 156 After RPC service transport handle
 157 .Fa xprt
 158 is created, it is registered with the RPC
 159 service package.
 160 This routine modifies the global variable
 161 .Va svc_fdset
 162 (see
 163 .Xr rpc_svc_calls 3 ) .
 164 Service implementors usually do not need this routine.
 165 .It Fn xprt_unregister
 166 Before an RPC service transport handle
 167 .Fa xprt
 168 is destroyed, it unregisters itself with the
 169 RPC service package.
 170 This routine modifies the global variable
 171 .Va svc_fdset
 172 (see
 173 .Xr rpc_svc_calls 3 ) .
 174 Service implementors usually do not need this routine.
 175 .El
 176 .Sh SEE ALSO
 177 .Xr select 2 ,
 178 .Xr rpc 3 ,
 179 .Xr rpcbind 3 ,
 180 .Xr rpc_svc_calls 3 ,
 181 .Xr rpc_svc_create 3 ,
 182 .Xr rpc_svc_err 3 ,
 183 .Xr rpcbind 8