xref: /dragonfly/lib/libc/rpc/rpcbind.3 (revision 0db87cb7) 
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.6 2005/02/09 18:03:14 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.Vt 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