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$ 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 LIBRARY 18.Lb libc 19.Sh SYNOPSIS 20.In rpc/rpc.h 21.Ft "rpcblist *" 22.Fn rpcb_getmaps "const struct netconfig *netconf" "const char *host" 23.Ft bool_t 24.Fn rpcb_getaddr "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const char *host" 25.Ft bool_t 26.Fn rpcb_gettime "const char *host" "time_t * timep" 27.Ft "enum clnt_stat" 28.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" 29.Ft bool_t 30.Fn rpcb_set "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct netbuf *svcaddr" 31.Ft bool_t 32.Fn rpcb_unset "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" 33.Sh DESCRIPTION 34These routines allow client C programs to make procedure 35calls to the RPC binder service. 36(see 37.Xr rpcbind 8 ) 38maintains a list of mappings between programs 39and their universal addresses. 40.Sh Routines 41.Bl -tag -width XXXXX 42.It Fn rpcb_getmaps 43An interface to the rpcbind service, 44which returns a list of the current 45RPC program-to-address mappings on 46.Fa host . 47It uses the transport specified through 48.Fa netconf 49to contact the remote rpcbind 50service on 51.Fa host . 52This routine will return 53.Dv NULL , 54if the remote rpcbind could not be contacted. 55.It Fn rpcb_getaddr 56An interface to the rpcbind 57service, which finds the address of the service on 58.Fa host 59that is registered with program number 60.Fa prognum , 61version 62.Fa versnum , 63and speaks the transport protocol associated with 64.Fa netconf . 65The address found is returned in 66.Fa svcaddr . 67.Fa svcaddr 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 parameter 115.Fa svcaddr 116will be modified to the server's address if the procedure succeeds 117(see 118.Fn rpc_call 119and 120.Fn clnt_call 121in 122.Xr rpc_clnt_calls 3 123for the definitions of other parameters). 124.Pp 125This procedure should normally be used for a 126.Dq ping 127and nothing else. 128This routine allows programs to do lookup and call, all in one step. 129.Pp 130Note: Even if the server is not running 131.Fn rpcb_rmtcall 132does not return any error messages to the caller. 133In such a case, the caller times out. 134.Pp 135Note: 136.Fn rpcb_rmtcall 137is only available for connectionless transports. 138.It Fn rpcb_set 139An interface to the rpcbind 140service, which establishes a mapping between the triple 141.Bq Fa prognum , versnum , netconf->nc_netid 142and 143.Fa svcaddr 144on the machine's rpcbind 145service. 146The value of 147.Fa nc_netid 148must correspond to a network identifier that is defined by the 149netconfig database. 150This routine returns 151.Dv TRUE 152if it succeeds, 153.Dv FALSE 154otherwise. 155(See also 156.Fn svc_reg 157in 158.Xr rpc_svc_calls 3 . ) 159If there already exists such an entry with rpcbind, 160.Fn rpcb_set 161will fail. 162.It Fn rpcb_unset 163An interface to the rpcbind 164service, which destroys the mapping between the triple 165.Bq Fa prognum , versnum , netconf->nc_netid 166and the address on the machine's rpcbind 167service. 168If 169.Fa netconf 170is 171.Dv NULL , 172.Fn rpcb_unset 173destroys all mapping between the triple 174.Bq Fa prognum , versnum , No all-transports 175and the addresses on the machine's rpcbind service. 176This routine returns 177.Dv TRUE 178if it succeeds, 179.Dv FALSE 180otherwise. 181Only the owner of the service or the super-user can destroy the mapping. 182(See also 183.Fn svc_unreg 184in 185.Xr rpc_svc_calls 3 . ) 186.El 187.Sh SEE ALSO 188.Xr rpc_clnt_calls 3 , 189.Xr rpc_svc_calls 3 , 190.Xr rpcbind 8 , 191.Xr rpcinfo 8 192