1.\" @(#)rpcbind.3n 1.25 93/05/07 SMI; from SVr4 2.\" Copyright 1989 AT&T 3.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. 4.\" $NetBSD: rpcbind.3,v 1.11 2009/04/11 16:07:20 joerg Exp $ 5.Dd December 4, 2005 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.In rpc/rpc.h 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 char *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. 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.Pp 85.It Fn rpcb_gettime 86This routine returns the time on 87.Fa host 88in 89.Fa timep . 90If 91.Fa host 92is 93.Dv NULL , 94.Fn rpcb_gettime 95returns the time on its own machine. 96This routine returns 97.Dv TRUE 98if it succeeds, 99.Dv FALSE 100if it fails. 101.Fn rpcb_gettime 102can be used to synchronize the time between the 103client and the remote server. 104.Pp 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``ping'' and nothing else. 127This routine allows programs to do lookup and call, all in one step. 128.Pp 129Note: Even if the server is not running 130.Fn rpcb_rmtcall 131does not return any error messages to the caller. 132In such a case, the caller times out. 133.Pp 134Note: 135.Fn rpcb_rmtcall 136is only available for connectionless transports. 137.Pp 138.It Fn rpcb_set 139An interface to the rpcbind 140service, which establishes a mapping between the triple 141[ 142.Fa prognum , 143.Fa versnum , 144.Fa netconf-\*[Gt]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.Pp 166.It Fn rpcb_unset 167An interface to the rpcbind 168service, which destroys the mapping between the triple 169[ 170.Fa prognum , 171.Fa versnum , 172.Fa netconf-\*[Gt]nc_netid ] 173and the address on the machine's rpcbind 174service. 175If 176.Fa netconf 177is 178.Dv NULL , 179.Fn rpcb_unset 180destroys all mapping between the triple 181[ 182.Fa prognum , 183.Fa versnum , 184.Fa all-transports ] 185and the addresses on the machine's rpcbind service. 186This routine returns 187.Dv TRUE 188if it succeeds, 189.Dv FALSE 190otherwise. 191Only the owner of the service or the super-user can destroy the mapping. 192(See also 193.Fn svc_unreg 194in 195.Xr rpc_svc_calls 3 . 196.El 197.Sh SEE ALSO 198.Xr rpc_clnt_calls 3 , 199.Xr rpc_svc_calls 3 , 200.Xr rpcbind 8 , 201.Xr rpcinfo 8 202