xref: /dragonfly/lib/libc/rpc/rpc_svc_calls.3 (revision 19fe1c42) 
1.\" @(#)rpc_svc_calls.3n 1.28 93/05/10 SMI; from SVr4
2.\" Copyright 1989 AT&T
3.\" @(#)rpc_svc_calls 1.5 89/07/25 SMI;
4.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
5.\"	$NetBSD: rpc_svc_calls.3,v 1.1 2000/06/02 23:11:13 fvdl Exp $
6.\" $FreeBSD: src/lib/libc/rpc/rpc_svc_calls.3,v 1.10 2005/11/23 16:44:23 ru Exp $
7.\" $DragonFly$
8.Dd May 3, 1993
9.Dt RPC_SVC_CALLS 3
10.Os
11.Sh NAME
12.Nm svc_dg_enablecache ,
13.Nm svc_exit ,
14.Nm svc_fdset ,
15.Nm svc_freeargs ,
16.Nm svc_getargs ,
17.Nm svc_getreq_common ,
18.Nm svc_getreq_poll ,
19.Nm svc_getreqset ,
20.Nm svc_getrpccaller ,
21.Nm svc_pollset ,
22.Nm svc_run ,
23.Nm svc_sendreply
24.Nd library routines for RPC servers
25.Sh LIBRARY
26.Lb libc
27.Sh SYNOPSIS
28.In rpc/rpc.h
29.Ft int
30.Fn svc_dg_enablecache "SVCXPRT *xprt" "const unsigned cache_size"
31.Ft void
32.Fn svc_exit "void"
33.Ft bool_t
34.Fn svc_freeargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
35.Ft bool_t
36.Fn svc_getargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
37.Ft void
38.Fn svc_getreq_common "const int fd"
39.Ft void
40.Fn svc_getreq_poll "struct pollfd *pfdp" "const int pollretval"
41.Ft void
42.Fn svc_getreqset "fd_set * rdfds"
43.Ft "struct netbuf *"
44.Fn svc_getrpccaller "const SVCXPRT *xprt"
45.Ft "struct cmsgcred *"
46.Fn __svc_getcallercreds "const SVCXPRT *xprt"
47.Vt struct pollfd svc_pollset[FD_SETSIZE];
48.Ft void
49.Fn svc_run "void"
50.Ft bool_t
51.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "void *out"
52.Sh DESCRIPTION
53These routines are part of the
54RPC
55library which allows C language programs to make procedure
56calls on other machines across the network.
57.Pp
58These routines are associated with the server side of the
59RPC mechanism.
60Some of them are called by the server side dispatch function,
61while others
62(such as
63.Fn svc_run )
64are called when the server is initiated.
65.\" .Pp
66.\" In the current implementation, the service transport handle,
67.\" .Dv SVCXPRT ,
68.\" contains a single data area for decoding arguments and encoding results.
69.\" Therefore, this structure cannot be freely shared between threads that call
70.\" functions that do this.
71.\" Routines on this page that are affected by this
72.\" restriction are marked as unsafe for MT applications.
73.Sh Routines
74See
75.Xr rpc 3
76for the definition of the
77.Vt SVCXPRT
78data structure.
79.Bl -tag -width __svc_getcallercreds()
80.It Fn svc_dg_enablecache
81This function allocates a duplicate request cache for the
82service endpoint
83.Fa xprt ,
84large enough to hold
85.Fa cache_size
86entries.
87Once enabled, there is no way to disable caching.
88This routine returns 0 if space necessary for a cache of the given size
89was successfully allocated, and 1 otherwise.
90.It Fn svc_exit
91This function, when called by any of the RPC server procedure or
92otherwise, causes
93.Fn svc_run
94to return.
95.Pp
96As currently implemented,
97.Fn svc_exit
98zeroes the
99.Va svc_fdset
100global variable.
101If RPC server activity is to be resumed,
102services must be reregistered with the RPC library
103either through one of the
104.Xr rpc_svc_create 3
105functions, or using
106.Fn xprt_register .
107The
108.Fn svc_exit
109function
110has global scope and ends all RPC server activity.
111.It Xo
112.Vt fd_set Va svc_fdset
113.Xc
114A global variable reflecting the
115RPC server's read file descriptor bit mask; it is suitable as an argument
116to the
117.Xr select 2
118system call.
119This is only of interest
120if service implementors do not call
121.Fn svc_run ,
122but rather do their own asynchronous event processing.
123This variable is read-only (do not pass its address to
124.Xr select 2 ! ) ,
125yet it may change after calls to
126.Fn svc_getreqset
127or any creation routines.
128.It Fn svc_freeargs
129A function macro that frees any data allocated by the
130RPC/XDR system when it decoded the arguments to a service procedure
131using
132.Fn svc_getargs .
133This routine returns
134.Dv TRUE
135if the results were successfully
136freed, and
137.Dv FALSE
138otherwise.
139.It Fn svc_getargs
140A function macro that decodes the arguments of an
141RPC request associated with the RPC
142service transport handle
143.Fa xprt .
144The
145.Fa in
146argument
147is the address where the arguments will be placed;
148.Fa inproc
149is the XDR
150routine used to decode the arguments.
151This routine returns
152.Dv TRUE
153if decoding succeeds, and
154.Dv FALSE
155otherwise.
156.It Fn svc_getreq_common
157This routine is called to handle a request on the given
158file descriptor.
159.It Fn svc_getreq_poll
160This routine is only of interest if a service implementor
161does not call
162.Fn svc_run ,
163but instead implements custom asynchronous event processing.
164It is called when
165.Xr poll 2
166has determined that an RPC request has arrived on some RPC
167file descriptors;
168.Fa pollretval
169is the return value from
170.Xr poll 2
171and
172.Fa pfdp
173is the array of
174.Vt pollfd
175structures on which the
176.Xr poll 2
177was done.
178It is assumed to be an array large enough to
179contain the maximal number of descriptors allowed.
180.It Fn svc_getreqset
181This routine is only of interest if a service implementor
182does not call
183.Fn svc_run ,
184but instead implements custom asynchronous event processing.
185It is called when
186.Xr poll 2
187has determined that an RPC
188request has arrived on some RPC file descriptors;
189.Fa rdfds
190is the resultant read file descriptor bit mask.
191The routine returns when all file descriptors
192associated with the value of
193.Fa rdfds
194have been serviced.
195.It Fn svc_getrpccaller
196The approved way of getting the network address of the caller
197of a procedure associated with the
198RPC service transport handle
199.Fa xprt .
200.It Fn __svc_getcallercreds
201.Em Warning :
202this macro is specific to
203.Fx
204and thus not portable.
205This macro returns a pointer to a
206.Vt cmsgcred
207structure, defined in
208.In sys/socket.h ,
209identifying the calling client.
210This only works if the client is
211calling the server over an
212.Dv AF_LOCAL
213socket.
214.It Xo
215.Vt struct pollfd Va svc_pollset[FD_SETSIZE] ;
216.Xc
217.Va svc_pollset
218is an array of
219.Vt pollfd
220structures derived from
221.Va svc_fdset[] .
222It is suitable as an argument to the
223.Xr poll 2
224system call.
225The derivation of
226.Va svc_pollset
227from
228.Va svc_fdset
229is made in the current implementation in
230.Fn svc_run .
231Service implementors who do not call
232.Fn svc_run
233and who wish to use this array must perform this derivation themselves.
234.It Fn svc_run
235This routine never returns.
236It waits for RPC
237requests to arrive, and calls the appropriate service
238procedure using
239.Fn svc_getreq_poll
240when one arrives.
241This procedure is usually waiting for the
242.Xr poll 2
243system call to return.
244.It Fn svc_sendreply
245Called by an RPC service's dispatch routine to send the results of a
246remote procedure call.
247The
248.Fa xprt
249argument
250is the request's associated transport handle;
251.Fa outproc
252is the XDR
253routine which is used to encode the results; and
254.Fa out
255is the address of the results.
256This routine returns
257.Dv TRUE
258if it succeeds,
259.Dv FALSE
260otherwise.
261.El
262.Sh SEE ALSO
263.Xr poll 2 ,
264.Xr select 2 ,
265.Xr rpc 3 ,
266.Xr rpc_svc_create 3 ,
267.Xr rpc_svc_err 3 ,
268.Xr rpc_svc_reg 3
269