lib/libc/rpc/rpcbind.3

   1 .\" @(#)rpcbind.3n 1.25 93/05/07 SMI; from SVr4
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
   4 .\"     $NetBSD: rpcbind.3,v 1.11 2009/04/11 16:07:20 joerg Exp $
   5 .Dd December 4, 2005
   6 .Dt RPCBIND 3
   7 .Os
   8 .Sh NAME
   9 .Nm rpcb_getmaps ,
  10 .Nm rpcb_getaddr ,
  11 .Nm rpcb_gettime ,
  12 .Nm rpcb_rmtcall ,
  13 .Nm rpcb_set ,
  14 .Nm rpcb_unset
  15 .Nd library routines for RPC bind service
  16 .Sh LIBRARY
  17 .Lb libc
  18 .Sh SYNOPSIS
  19 .In rpc/rpc.h
  20 .Ft "struct rpcblist *"
  21 .Fn rpcb_getmaps "const struct netconfig *netconf" "const char *host"
  22 .Ft bool_t
  23 .Fn rpcb_getaddr "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const char *host"
  24 .Ft bool_t
  25 .Fn rpcb_gettime "const char *host" "time_t * timep"
  26 .Ft "enum clnt_stat"
  27 .Fn rpcb_rmtcall "const struct netconfig *netconf" "const char *host" "const rpcprog_t prognum, const rpcvers_t versnum" "const rpcproc_t procnum, const xdrproc_t inproc" "const char *in" "const xdrproc_t outproc" "caddr_t out" "const struct timeval tout, struct netbuf  *svcaddr"
  28 .Ft bool_t
  29 .Fn rpcb_set "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct netbuf *svcaddr"
  30 .Ft bool_t
  31 .Fn rpcb_unset "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
  32 .Sh DESCRIPTION
  33 These routines allow client C programs to make procedure
  34 calls to the RPC binder service.
  35 (see
  36 .Xr rpcbind 8 )
  37 maintains a list of mappings between programs
  38 and their universal addresses.
  39 .Sh ROUTINES
  40 .Bl -tag -width XXXXX
  41 .It Fn rpcb_getmaps
  42 An interface to the rpcbind service,
  43 which returns a list of the current
  44 RPC program-to-address mappings on
  45 .Fa host .
  46 It uses the transport specified through
  47 .Fa netconf
  48 to contact the remote rpcbind
  49 service on
  50 .Fa host .
  51 This routine will return
  52 .Dv NULL ,
  53 if the remote rpcbind could not be contacted.
  54 .Pp
  55 .It Fn rpcb_getaddr
  56 An interface to the rpcbind
  57 service, which finds the address of the service on
  58 .Fa host
  59 that is registered with program number
  60 .Fa prognum ,
  61 version
  62 .Fa versnum ,
  63 and speaks the transport protocol associated with
  64 .Fa netconf .
  65 The address found is returned in
  66 .Fa svcaddr .
  67 .Fa svcaddr
  68 should be preallocated.
  69 This routine returns
  70 .Dv TRUE
  71 if it succeeds.
  72 A return value of
  73 .Dv FALSE
  74 means that the mapping does not exist
  75 or that the RPC
  76 system failed to contact the remote
  77 rpcbind service.
  78 In the latter case, the global variable
  79 .Va rpc_createerr
  80 (see
  81 .Xr rpc_clnt_create 3
  82 contains the
  83 RPC status.
  84 .Pp
  85 .It Fn rpcb_gettime
  86 This routine returns the time on
  87 .Fa host
  88 in
  89 .Fa timep .
  90 If
  91 .Fa host
  92 is
  93 .Dv NULL ,
  94 .Fn rpcb_gettime
  95 returns the time on its own machine.
  96 This routine returns
  97 .Dv TRUE
  98 if it succeeds,
  99 .Dv FALSE
 100 if it fails.
 101 .Fn rpcb_gettime
 102 can be used to synchronize the time between the
 103 client and the remote server.
 104 .Pp
 105 .It Fn rpcb_rmtcall
 106 An interface to the rpcbind service, which instructs
 107 rpcbind on
 108 .Fa host
 109 to make an RPC
 110 call on your behalf to a procedure on that host.
 111 The
 112 .Fn netconfig
 113 structure should correspond to a connectionless transport.
 114 The parameter
 115 .Fa svcaddr
 116 will be modified to the server's address if the procedure succeeds
 117 (see
 118 .Fn rpc_call
 119 and
 120 .Fn clnt_call
 121 in
 122 .Xr rpc_clnt_calls 3
 123 for the definitions of other parameters).
 124 .Pp
 125 This procedure should normally be used for a
 126 ``ping'' and nothing else.
 127 This routine allows programs to do lookup and call, all in one step.
 128 .Pp
 129 Note: Even if the server is not running
 130 .Fn rpcb_rmtcall
 131 does not return any error messages to the caller.
 132 In such a case, the caller times out.
 133 .Pp
 134 Note:
 135 .Fn rpcb_rmtcall
 136 is only available for connectionless transports.
 137 .Pp
 138 .It Fn rpcb_set
 139 An interface to the rpcbind
 140 service, which establishes a mapping between the triple
 141 [
 142 .Fa prognum ,
 143 .Fa versnum ,
 144 .Fa netconf-\*[Gt]nc_netid ]
 145 and
 146 .Fa svcaddr
 147 on the machine's rpcbind
 148 service.
 149 The value of
 150 .Fa nc_netid
 151 must correspond to a network identifier that is defined by the
 152 netconfig database.
 153 This routine returns
 154 .Dv TRUE
 155 if it succeeds,
 156 .Dv FALSE
 157 otherwise.
 158 (See also
 159 .Fn svc_reg
 160 in
 161 .Xr rpc_svc_calls 3 .
 162 If there already exists such an entry with rpcbind,
 163 .Fn rpcb_set
 164 will fail.
 165 .Pp
 166 .It Fn rpcb_unset
 167 An interface to the rpcbind
 168 service, which destroys the mapping between the triple
 169 [
 170 .Fa prognum ,
 171 .Fa versnum ,
 172 .Fa netconf-\*[Gt]nc_netid ]
 173 and the address on the machine's rpcbind
 174 service.
 175 If
 176 .Fa netconf
 177 is
 178 .Dv NULL ,
 179 .Fn rpcb_unset
 180 destroys all mapping between the triple
 181 [
 182 .Fa prognum ,
 183 .Fa versnum ,
 184 .Fa all-transports ]
 185 and the addresses on the machine's rpcbind service.
 186 This routine returns
 187 .Dv TRUE
 188 if it succeeds,
 189 .Dv FALSE
 190 otherwise.
 191 Only the owner of the service or the super-user can destroy the mapping.
 192 (See also
 193 .Fn svc_unreg
 194 in
 195 .Xr rpc_svc_calls 3 .
 196 .El
 197 .Sh SEE ALSO
 198 .Xr rpc_clnt_calls 3 ,
 199 .Xr rpc_svc_calls 3 ,
 200 .Xr rpcbind 8 ,
 201 .Xr rpcinfo 8