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