man/rpcbind.3t

   1 .\" @(#)rpcbind.3n 1.25 93/05/07 SMI; from SVr4
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (c) 1988 Sun Microsystem's, Inc. - All Right's Reserved.
   4 .\"     $NetBSD: rpcbind.3,v 1.2 2000/06/03 18:47:28 fvdl Exp   $
   5 .\"     $FreeBSD: src/lib/libc/rpc/rpcbind.3,v 1.5 2002/12/19 09:40:23 ru Exp $
   6 .Dd May 7, 1993
   7 .Dt RPCBIND 3
   8 .Os
   9 .Sh NAME
  10 .Nm rpcb_getmaps ,
  11 .Nm rpcb_getaddr ,
  12 .Nm rpcb_gettime ,
  13 .Nm rpcb_rmtcall ,
  14 .Nm rpcb_set ,
  15 .Nm rpcb_unset
  16 .Nd library routines for RPC bind service
  17 .Sh SYNOPSIS
  18 .In rpc/rpc.h
  19 .Ft "rpcblist *"
  20 .Fn rpcb_getmaps "const struct netconfig *netconf" "const char *host"
  21 .Ft bool_t
  22 .Fn rpcb_getaddr "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const char *host"
  23 .Ft bool_t
  24 .Fn rpcb_gettime "const char *host" "time_t * timep"
  25 .Ft "enum clnt_stat"
  26 .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 caddr_t in" "const xdrproc_t outproc" "const caddr_t out" "const struct timeval tout, const struct netbuf *svcaddr"
  27 .Ft bool_t
  28 .Fn rpcb_set "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct netbuf *svcaddr"
  29 .Ft bool_t
  30 .Fn rpcb_unset "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
  31 .Sh DESCRIPTION
  32 These routines allow client C programs to make procedure
  33 calls to the RPC binder service.
  34 (see
  35 .Xr rpcbind 8 )
  36 maintains a list of mappings between programs
  37 and their universal addresses.
  38 .Sh Routines
  39 .Bl -tag -width XXXXX
  40 .It Fn rpcb_getmaps
  41 An interface to the rpcbind service,
  42 which returns a list of the current
  43 RPC program-to-address mappings on
  44 .Fa host .
  45 It uses the transport specified through
  46 .Fa netconf
  47 to contact the remote rpcbind
  48 service on
  49 .Fa host .
  50 This routine will return
  51 .Dv NULL ,
  52 if the remote rpcbind could not be contacted.
  53 .It Fn rpcb_getaddr
  54 An interface to the rpcbind
  55 service, which finds the address of the service on
  56 .Fa host
  57 that is registered with program number
  58 .Fa prognum ,
  59 version
  60 .Fa versnum ,
  61 and speaks the transport protocol associated with
  62 .Fa netconf .
  63 The address found is returned in
  64 .Fa svcaddr .
  65 The
  66 .Fa svcaddr
  67 argument
  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 .It Fn rpcb_gettime
  85 This routine returns the time on
  86 .Fa host
  87 in
  88 .Fa timep .
  89 If
  90 .Fa host
  91 is
  92 .Dv NULL ,
  93 .Fn rpcb_gettime
  94 returns the time on its own machine.
  95 This routine returns
  96 .Dv TRUE
  97 if it succeeds,
  98 .Dv FALSE
  99 if it fails.
 100 The
 101 .Fn rpcb_gettime
 102 function
 103 can be used to synchronize the time between the
 104 client and the remote server.
 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
 115 .Fa svcaddr
 116 argument
 117 will be modified to the server's address if the procedure succeeds
 118 (see
 119 .Fn rpc_call
 120 and
 121 .Fn clnt_call
 122 in
 123 .Xr rpc_clnt_calls 3
 124 for the definitions of other arguments).
 125 .Pp
 126 This procedure should normally be used for a
 127 .Dq ping
 128 and nothing else.
 129 This routine allows programs to do lookup and call, all in one step.
 130 .Pp
 131 Note: Even if the server is not running
 132 .Fn rpcb_rmtcall
 133 does not return any error messages to the caller.
 134 In such a case, the caller times out.
 135 .Pp
 136 Note:
 137 .Fn rpcb_rmtcall
 138 is only available for connectionless transports.
 139 .It Fn rpcb_set
 140 An interface to the rpcbind
 141 service, which establishes a mapping between the triple
 142 .Bq Fa prognum , versnum , netconf->nc_netid
 143 and
 144 .Fa svcaddr
 145 on the machine's rpcbind
 146 service.
 147 The value of
 148 .Fa nc_netid
 149 must correspond to a network identifier that is defined by the
 150 netconfig database.
 151 This routine returns
 152 .Dv TRUE
 153 if it succeeds,
 154 .Dv FALSE
 155 otherwise.
 156 (See also
 157 .Fn svc_reg
 158 in
 159 .Xr rpc_svc_calls 3 . )
 160 If there already exists such an entry with rpcbind,
 161 .Fn rpcb_set
 162 will fail.
 163 .It Fn rpcb_unset
 164 An interface to the rpcbind
 165 service, which destroys the mapping between the triple
 166 .Bq Fa prognum , versnum , netconf->nc_netid
 167 and the address on the machine's rpcbind
 168 service.
 169 If
 170 .Fa netconf
 171 is
 172 .Dv NULL ,
 173 .Fn rpcb_unset
 174 destroys all mapping between the triple
 175 .Bq Fa prognum , versnum , No all-transports
 176 and the addresses on the machine's rpcbind service.
 177 This routine returns
 178 .Dv TRUE
 179 if it succeeds,
 180 .Dv FALSE
 181 otherwise.
 182 Only the owner of the service or the super-user can destroy the mapping.
 183 (See also
 184 .Fn svc_unreg
 185 in
 186 .Xr rpc_svc_calls 3 . )
 187 .El
 188 .Sh AVAILABILITY
 189 These functions are part of libtirpc.
 190 .Sh SEE ALSO
 191 .Xr rpc_clnt_calls 3 ,
 192 .Xr rpc_svc_calls 3 ,
 193 .Xr rpcbind 8 ,
 194 .Xr rpcinfo 8