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. 100.Fn rpcb_gettime 101can be used to synchronize the time between the 102client and the remote server. 103.It Fn rpcb_rmtcall 104An interface to the rpcbind service, which instructs 105rpcbind on 106.Fa host 107to make an RPC 108call on your behalf to a procedure on that host. 109The 110.Fn netconfig 111structure should correspond to a connectionless transport. 112The parameter 113.Fa svcaddr 114will be modified to the server's address if the procedure succeeds 115(see 116.Fn rpc_call 117and 118.Fn clnt_call 119in 120.Xr rpc_clnt_calls 3 121for the definitions of other parameters). 122.Pp 123This procedure should normally be used for a 124.Dq ping 125and nothing else. 126This routine allows programs to do lookup and call, all in one step. 127.Pp 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.It Fn rpcb_set 137An interface to the rpcbind 138service, which establishes a mapping between the triple 139.Bq Fa prognum , versnum , netconf->nc_netid 140and 141.Fa svcaddr 142on the machine's rpcbind 143service. 144The value of 145.Fa nc_netid 146must correspond to a network identifier that is defined by the 147netconfig database. 148This routine returns 149.Dv TRUE 150if it succeeds, 151.Dv FALSE 152otherwise. 153(See also 154.Fn svc_reg 155in 156.Xr rpc_svc_calls 3 . ) 157If there already exists such an entry with rpcbind, 158.Fn rpcb_set 159will fail. 160.It Fn rpcb_unset 161An interface to the rpcbind 162service, which destroys the mapping between the triple 163.Bq Fa prognum , versnum , netconf->nc_netid 164and the address on the machine's rpcbind 165service. 166If 167.Fa netconf 168is 169.Dv NULL , 170.Fn rpcb_unset 171destroys all mapping between the triple 172.Bq Fa prognum , versnum , No all-transports 173and the addresses on the machine's rpcbind service. 174This routine returns 175.Dv TRUE 176if it succeeds, 177.Dv FALSE 178otherwise. 179Only the owner of the service or the super-user can destroy the mapping. 180(See also 181.Fn svc_unreg 182in 183.Xr rpc_svc_calls 3 . ) 184.El 185.Sh SEE ALSO 186.Xr rpc_clnt_calls 3 , 187.Xr rpc_svc_calls 3 , 188.Xr rpcbind 8 , 189.Xr rpcinfo 8 190