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.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.In rpc/rpc.h 20.Ft "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" "const caddr_t out" "const struct timeval tout" "const 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.It Fn rpcb_getaddr 55An interface to the rpcbind 56service, which finds the address of the service on 57.Fa host 58that is registered with program number 59.Fa prognum , 60version 61.Fa versnum , 62and speaks the transport protocol associated with 63.Fa netconf . 64The address found is returned in 65.Fa svcaddr . 66The 67.Fa svcaddr 68argument 69should be preallocated. 70This routine returns 71.Dv TRUE 72if it succeeds. 73A return value of 74.Dv FALSE 75means that the mapping does not exist 76or that the RPC 77system failed to contact the remote 78rpcbind service. 79In the latter case, the global variable 80.Va rpc_createerr 81(see 82.Xr rpc_clnt_create 3 ) 83contains the 84RPC status. 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. 101The 102.Fn rpcb_gettime 103function 104can be used to synchronize the time between the 105client and the remote server. 106.It Fn rpcb_rmtcall 107An interface to the rpcbind service, which instructs 108rpcbind on 109.Fa host 110to make an RPC 111call on your behalf to a procedure on that host. 112The 113.Fn netconfig 114structure should correspond to a connectionless transport. 115The 116.Fa svcaddr 117argument 118will be modified to the server's address if the procedure succeeds 119(see 120.Fn rpc_call 121and 122.Fn clnt_call 123in 124.Xr rpc_clnt_calls 3 125for the definitions of other arguments). 126.Pp 127This procedure should normally be used for a 128.Dq ping 129and nothing else. 130This routine allows programs to do lookup and call, all in one step. 131.Pp 132Note: Even if the server is not running 133.Fn rpcb_rmtcall 134does not return any error messages to the caller. 135In such a case, the caller times out. 136.Pp 137Note: 138.Fn rpcb_rmtcall 139is only available for connectionless transports. 140.It Fn rpcb_set 141An interface to the rpcbind 142service, which establishes a mapping between the triple 143.Bq Fa prognum , versnum , netconf->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.Fn 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.It Fn rpcb_unset 165An interface to the rpcbind 166service, which destroys the mapping between the triple 167.Bq Fa prognum , versnum , netconf->nc_netid 168and the address on the machine's rpcbind 169service. 170If 171.Fa netconf 172is 173.Dv NULL , 174.Fn rpcb_unset 175destroys all mapping between the triple 176.Bq Fa prognum , versnum , No all-transports 177and the addresses on the machine's rpcbind service. 178This routine returns 179.Dv TRUE 180if it succeeds, 181.Dv FALSE 182otherwise. 183Only the owner of the service or the super-user can destroy the mapping. 184(See also 185.Fn svc_unreg 186in 187.Xr rpc_svc_calls 3 . ) 188.El 189.Sh SEE ALSO 190.Xr rpc_clnt_calls 3 , 191.Xr rpc_svc_calls 3 , 192.Xr rpcbind 8 , 193.Xr rpcinfo 8 194