man/rpc_svc_reg.3t

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