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