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 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 . 67The 68.Fa svcaddr 69argument 70should be preallocated. 71This routine returns 72.Dv TRUE 73if it succeeds. 74A return value of 75.Dv FALSE 76means that the mapping does not exist 77or that the RPC 78system failed to contact the remote 79rpcbind service. 80In the latter case, the global variable 81.Va rpc_createerr 82(see 83.Xr rpc_clnt_create 3 ) 84contains the 85RPC status. 86.It Fn rpcb_gettime 87This routine returns the time on 88.Fa host 89in 90.Fa timep . 91If 92.Fa host 93is 94.Dv NULL , 95.Fn rpcb_gettime 96returns the time on its own machine. 97This routine returns 98.Dv TRUE 99if it succeeds, 100.Dv FALSE 101if it fails. 102The 103.Fn rpcb_gettime 104function 105can be used to synchronize the time between the 106client and the remote server. 107.It Fn rpcb_rmtcall 108An interface to the rpcbind service, which instructs 109rpcbind on 110.Fa host 111to make an RPC 112call on your behalf to a procedure on that host. 113The 114.Fn netconfig 115structure should correspond to a connectionless transport. 116The 117.Fa svcaddr 118argument 119will be modified to the server's address if the procedure succeeds 120(see 121.Fn rpc_call 122and 123.Fn clnt_call 124in 125.Xr rpc_clnt_calls 3 126for the definitions of other arguments). 127.Pp 128This procedure should normally be used for a 129.Dq ping 130and nothing else. 131This routine allows programs to do lookup and call, all in one step. 132.Pp 133Note: Even if the server is not running 134.Fn rpcb_rmtcall 135does not return any error messages to the caller. 136In such a case, the caller times out. 137.Pp 138Note: 139.Fn rpcb_rmtcall 140is only available for connectionless transports. 141.It Fn rpcb_set 142An interface to the rpcbind 143service, which establishes a mapping between the triple 144.Bq Fa prognum , versnum , netconf->nc_netid 145and 146.Fa svcaddr 147on the machine's rpcbind 148service. 149The value of 150.Fa nc_netid 151must correspond to a network identifier that is defined by the 152netconfig database. 153This routine returns 154.Dv TRUE 155if it succeeds, 156.Dv FALSE 157otherwise. 158(See also 159.Fn svc_reg 160in 161.Xr rpc_svc_calls 3 . ) 162If there already exists such an entry with rpcbind, 163.Fn rpcb_set 164will fail. 165.It Fn rpcb_unset 166An interface to the rpcbind 167service, which destroys the mapping between the triple 168.Bq Fa prognum , versnum , netconf->nc_netid 169and the address on the machine's rpcbind 170service. 171If 172.Fa netconf 173is 174.Dv NULL , 175.Fn rpcb_unset 176destroys all mapping between the triple 177.Bq Fa prognum , versnum , No all-transports 178and the addresses on the machine's rpcbind service. 179This routine returns 180.Dv TRUE 181if it succeeds, 182.Dv FALSE 183otherwise. 184Only the owner of the service or the super-user can destroy the mapping. 185(See also 186.Fn svc_unreg 187in 188.Xr rpc_svc_calls 3 . ) 189.El 190.Sh SEE ALSO 191.Xr rpc_clnt_calls 3 , 192.Xr rpc_svc_calls 3 , 193.Xr rpcbind 8 , 194.Xr rpcinfo 8 195