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