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