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