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