1rpc_svc_calls(3NSL)  Networking Services Library Functions rpc_svc_calls(3NSL)
2
3
4

NAME

6       rpc_svc_calls,   svc_dg_enablecache,   svc_done,  svc_exit,  svc_fdset,
7       svc_freeargs,    svc_getargs,    svc_getreq_common,    svc_getreq_poll,
8       svc_getreqset,  svc_getrpccaller,  svc_max_pollfd, svc_pollfd, svc_run,
9       svc_sendreply,  svc_getcallerucred,  svc_fd_negotiate_ucred  -  library
10       routines for RPC servers
11

SYNOPSIS

13       cc [ flag... ] file... -lnsl [ library...]
14       #include <rpc/rpc.h>
15
16       int svc_dg_enablecache(SVCXPRT *xprt, const uint_t cache_size);
17
18
19       int svc_done(SVCXPRT *xprt);
20
21
22       void svc_exit(void);
23
24
25       void svc_fd_negotiate_ucred(int fd);
26
27
28       bool_t svc_freeargs(const SVCXPRT *xprt, const txdrproc_t inproc,
29            caddr_t in);
30
31
32       bool_t svc_getargs(const SVCXPRT *xprt, const xdrproc_t inproc,
33            caddr_t in);
34
35
36       int svc_getcallerucred(const SVCXPRT *xprt, ucred_t **ucred);
37
38
39       void svc_getreq_common(const int fd);
40
41
42       void svc_getreqset(fd_set *rdfds);
43
44
45       void svc_getreq_poll(struct pollfd *pfdp, const int pollretval);
46
47
48       struct netbuf *svc_getrpccaller(const SVCXPRT *xprt);
49
50
51       void svc_run(void);
52
53
54       bool_t svc_sendreply(const SVCXPRT *xprt, const xdrproc_t outproc,
55            caddr_t outint svc_max_pollfd;
56       fd_set svc_fdset;
57       pollfd_t *svc_pollfd;
58
59

DESCRIPTION

61       These routines are part of the RPC library which allows C language pro‐
62       grams to make procedure calls on other machines across the network.
63
64
65       These routines are associated with the server side of  the  RPC  mecha‐
66       nism.  Some  of  them  are called by the server side dispatch function.
67       Others, such as svc_run(), are called when the server is initiated.
68
69
70       Because the service transport handle SVCXPRT  contains  a  single  data
71       area  for decoding arguments and encoding results, the structure cannot
72       freely be shared between threads that call functions  to  decode  argu‐
73       ments  and  encode results. When a server is operating in the Automatic
74       or User MT modes, however, a copy of this structure is  passed  to  the
75       service  dispatch  procedure in order to enable concurrent request pro‐
76       cessing. Under these circumstances, some routines which would otherwise
77       be  Unsafe, become Safe. These are marked as such. Also marked are rou‐
78       tines that are Unsafe for multithreaded applications, and are not to be
79       used  by  such  applications.  See  rpc(3NSL) for the definition of the
80       SVCXPRT data structure.
81
82
83       The svc_dg_enablecache() function allocates a duplicate  request  cache
84       for the service endpoint xprt, large enough to hold cache_size entries.
85       Once enabled, there is no way to disable caching. The function  returns
86       1  if  space  necessary  for a cache of the given size was successfully
87       allocated, and 0 otherwise. This  function  is  Safe  in  multithreaded
88       applications.
89
90
91       The  svc_done()  function frees resources allocated to service a client
92       request directed to the service endpoint xprt. This call pertains  only
93       to  servers executing in the User MT mode. In the User MT mode, service
94       procedures must invoke this  call  before  returning,  either  after  a
95       client  request has been serviced, or after an error or abnormal condi‐
96       tion that prevents  a  reply  from  being  sent.  After  svc_done()  is
97       invoked, the service endpoint xprt should not be referenced by the ser‐
98       vice procedure. Server multithreading modes and parameters can  be  set
99       using  the  rpc_control()  call. This function is Safe in multithreaded
100       applications. It will have no effect if invoked in modes other than the
101       User MT mode.
102
103
104       The svc_exit() function when called by any of the RPC server procedures
105       or otherwise, destroys all services registered by the server and causes
106       svc_run()  to return. If RPC server activity is to be resumed, services
107       must be reregistered with the RPC library either  through  one  of  the
108       rpc_svc_create(3NSL)   functions,  or  using  xprt_register(3NSL).  The
109       svc_exit() function has global scope and ends all RPC server activity.
110
111
112       The svc_freeargs() function macro  frees  any  data  allocated  by  the
113       RPC/XDR  system  when  it  decoded the arguments to a service procedure
114       using svc_getargs(). This routine returns TRUE if the results were suc‐
115       cessfully  freed,  and  FALSE otherwise. This function macro is Safe in
116       multithreaded applications utilizing the Automatic or User MT modes.
117
118
119       The svc_getargs() function  macro  decodes  the  arguments  of  an  RPC
120       request  associated  with  the  RPC  service transport handle xprt. The
121       parameter in is the address where the arguments will be placed;  inproc
122       is  the  XDR routine used to decode the arguments. This routine returns
123       TRUE if decoding succeeds, and FALSE otherwise. This function macro  is
124       Safe  in  multithreaded applications utilizing the Automatic or User MT
125       modes.
126
127
128       The svc_getreq_common() function is called to handle  a  request  on  a
129       file descriptor.
130
131
132       The  svc_getreq_poll() function is only of interest if a service imple‐
133       mentor does not call svc_run(), but instead implements custom asynchro‐
134       nous event processing. It is called when poll(2) has determined that an
135       RPC request has arrived on some RPC file descriptors; pollretval is the
136       return value from poll(2) and pfdp is the array of pollfd structures on
137       which the poll(2) was done. It is assumed to be an array  large  enough
138       to   contain   the   maximal   number   of   descriptors  allowed.  The
139       svc_getreq_poll() function macro is Unsafe  in  multithreaded  applica‐
140       tions.
141
142
143       The svc_getreqset() function is only of interest if a service implemen‐
144       tor does not call svc_run(), but instead implements custom asynchronous
145       event  processing.  It is called when select(3C) has determined that an
146       RPC request has arrived on some RPC  file  descriptors;  rdfds  is  the
147       resultant  read  file descriptor bit mask. The routine returns when all
148       file descriptors associated with the value of rdfds have been serviced.
149       This function macro is Unsafe in multithreaded applications.
150
151
152       The svc_getrpccaller() function is the approved way of getting the net‐
153       work address of the caller of a procedure associated with the RPC  ser‐
154       vice  transport  handle  xprt.  This  function  macro is Safe in multi‐
155       threaded applications.
156
157
158       The svc_run() function never  returns.  In  single-threaded  mode,  the
159       function waits for RPC requests to arrive. When an RPC request arrives,
160       the svc_run() function calls the appropriate  service  procedure.  This
161       procedure is usually waiting for the poll(2) library call to return.
162
163
164       Applications  that  execute in the Automatic or the User MT mode should
165       invoke the svc_run() function exactly once. In the Automatic  MT  mode,
166       the  svc_run()  function creates threads to service client requests. In
167       the User MT mode, the function provides a framework for service  devel‐
168       opers  to  create  and  manage  their  own threads for servicing client
169       requests.
170
171
172       The svc_fdset global variable  reflects  the  RPC  server's  read  file
173       descriptor  bit  mask. This is only of interest if service implementors
174       do not call svc_run(), but rather do their own asynchronous event  pro‐
175       cessing.   This  variable  is  read-only  may  change  after  calls  to
176       svc_getreqset() or after any creation routine. Do not pass its  address
177       to  select(3C).  Instead,  pass  the  address  of a copy. multithreaded
178       applications executing in either the Automatic MT mode or the  user  MT
179       mode should never read this variable. They should use auxiliary threads
180       to do asynchronous event processing. The svc_fdset variable is  limited
181       to  1024 file descriptors and is considered obsolete. Use of svc_pollfd
182       is recommended instead.
183
184
185       The svc_pollfd global variable points to an array  of  pollfd_t  struc‐
186       tures that reflect the RPC server's read file descriptor array. This is
187       only of interest if service service implementors do not call  svc_run()
188       but rather do their own asynchronous event processing. This variable is
189       read-only, and it may change after calls to  svc_getreg_poll()  or  any
190       creation routines. Do no pass its address to poll(2). Instead, pass the
191       address of a copy. By default, svc_pollfd is limited to  1024  entries.
192       Use rpc_control(3NSL) to remove this limitation. multithreaded applica‐
193       tions executing in either the Automatic MT mode or  the  user  MT  mode
194       should  never  be read this variable. They should use auxiliary threads
195       to do asynchronous event processing.
196
197
198       The svc_max_pollfd global variable contains the maximum length  of  the
199       svc_pollfd  array.  This variable is read-only, and it may change after
200       calls to svc_getreg_poll() or any creation routines.
201
202
203       The svc_sendreply() function is called by an RPC service dispatch  rou‐
204       tine to send the results of a remote procedure call. The xprt parameter
205       is the transport handle of the request. The outproc  parameter  is  the
206       XDR  routine  used  to  encode  the  results.  The out parameter is the
207       address of the results. This routine returns TRUE if it succeeds, FALSE
208       otherwise.  The svc_sendreply() function macro is Safe in multithreaded
209       applications that use the Automatic or the User MT mode.
210
211
212       The svc_fd_negotiate_ucred() function is called by  an  RPC  server  to
213       inform  the  underlying  transport  that the function wishes to receive
214       ucreds for local calls, including those over IP transports.
215
216
217       The svc_getcallerucred() function  attempts  to  retrieve  the  ucred_t
218       associated  with the caller. The function returns 0 when successful and
219       -1 when not.
220
221
222       When successful, the svc_getcallerucred() function stores  the  pointer
223       to a freshly allocated ucred_t in the memory location pointed to by the
224       ucred argument if that memory location contains the  null  pointer.  If
225       the  memory  location  is  non-null,  the  function reuses the existing
226       ucred_t. When ucred is no longer  needed,  a  credential  allocated  by
227       svc_getcallerucred() should be freed with ucred_free(3C).
228

ATTRIBUTES

230       See attributes(5) for descriptions of attribute types and values.
231
232
233
234
235       ┌─────────────────────────────┬─────────────────────────────┐
236       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
237       ├─────────────────────────────┼─────────────────────────────┤
238       │MT-Level                     │See below.                   │
239       └─────────────────────────────┴─────────────────────────────┘
240
241
242       The svc_fd_negotiate_ucred(), svc_dg_enablecache(), svc_getrpccaller(),
243       and svc_getcallerucred() functions are Safe in  multithreaded  applica‐
244       tions. The svc_freeargs(), svc_getargs(), and svc_sendreply() functions
245       are Safe in multithreaded applications that use the  Automatic  or  the
246       User   MT   mode.   The   svc_getreq_common(),   svc_getreqset(),   and
247       svc_getreq_poll() functions are Unsafe  in  multithreaded  applications
248       and should be called only from the main thread.
249

SEE ALSO

251       rpcgen(1),  poll(2),  getpeerucred(3C),  rpc(3NSL),  rpc_control(3NSL),
252       rpc_svc_create(3NSL), rpc_svc_err(3NSL), rpc_svc_reg(3NSL), select(3C),
253       ucred_free(3C), xprt_register(3NSL), attributes(5)
254
255
256
257SunOS 5.11                        26 Jan 2004              rpc_svc_calls(3NSL)
Impressum