1 | .\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI |
---|
2 | .\" $FreeBSD: src/lib/libc/rpc/rpc.3,v 1.11 2000/03/02 09:13:47 sheldonh Exp $ |
---|
3 | .\" |
---|
4 | .TH RPC 3 "16 February 1988" |
---|
5 | .SH NAME |
---|
6 | rpc \- library routines for remote procedure calls |
---|
7 | .SH SYNOPSIS AND DESCRIPTION |
---|
8 | These routines allow C programs to make procedure |
---|
9 | calls on other machines across the network. |
---|
10 | First, the client calls a procedure to send a |
---|
11 | data packet to the server. |
---|
12 | Upon receipt of the packet, the server calls a dispatch routine |
---|
13 | to perform the requested service, and then sends back a |
---|
14 | reply. |
---|
15 | Finally, the procedure call returns to the client. |
---|
16 | .LP |
---|
17 | Routines that are used for Secure RPC (DES authentication) are described in |
---|
18 | .BR rpc_secure (3). |
---|
19 | Secure RPC can be used only if DES encryption is available. |
---|
20 | .LP |
---|
21 | .ft B |
---|
22 | .nf |
---|
23 | .sp .5 |
---|
24 | #include <rpc/rpc.h> |
---|
25 | .fi |
---|
26 | .ft R |
---|
27 | .br |
---|
28 | .if t .ne 8 |
---|
29 | .LP |
---|
30 | .ft B |
---|
31 | .nf |
---|
32 | .sp .5 |
---|
33 | void |
---|
34 | auth_destroy(auth) |
---|
35 | \s-1AUTH\s0 *auth; |
---|
36 | .fi |
---|
37 | .ft R |
---|
38 | .IP |
---|
39 | A macro that destroys the authentication information associated with |
---|
40 | .IR auth . |
---|
41 | Destruction usually involves deallocation of private data |
---|
42 | structures. |
---|
43 | The use of |
---|
44 | .I auth |
---|
45 | is undefined after calling |
---|
46 | .BR auth_destroy(\|) . |
---|
47 | .br |
---|
48 | .if t .ne 6 |
---|
49 | .LP |
---|
50 | .ft B |
---|
51 | .nf |
---|
52 | .sp .5 |
---|
53 | \s-1AUTH\s0 * |
---|
54 | authnone_create(\|) |
---|
55 | .fi |
---|
56 | .ft R |
---|
57 | .IP |
---|
58 | Create and returns an |
---|
59 | .SM RPC |
---|
60 | authentication handle that passes nonusable authentication |
---|
61 | information with each remote procedure call. |
---|
62 | This is the |
---|
63 | default authentication used by |
---|
64 | .SM RPC. |
---|
65 | .if t .ne 10 |
---|
66 | .LP |
---|
67 | .ft B |
---|
68 | .nf |
---|
69 | .sp .5 |
---|
70 | \s-1AUTH\s0 * |
---|
71 | authunix_create(host, uid, gid, len, aup_gids) |
---|
72 | char *host; |
---|
73 | int uid, gid, len, *aup.gids; |
---|
74 | .fi |
---|
75 | .ft R |
---|
76 | .IP |
---|
77 | Create and return an |
---|
78 | .SM RPC |
---|
79 | authentication handle that contains |
---|
80 | .UX |
---|
81 | authentication information. |
---|
82 | The parameter |
---|
83 | .I host |
---|
84 | is the name of the machine on which the information was |
---|
85 | created; |
---|
86 | .I uid |
---|
87 | is the user's user |
---|
88 | .SM ID ; |
---|
89 | .I gid |
---|
90 | is the user's current group |
---|
91 | .SM ID ; |
---|
92 | .I len |
---|
93 | and |
---|
94 | .I aup_gids |
---|
95 | refer to a counted array of groups to which the user belongs. |
---|
96 | It is easy to impersonate a user. |
---|
97 | .br |
---|
98 | .if t .ne 5 |
---|
99 | .LP |
---|
100 | .ft B |
---|
101 | .nf |
---|
102 | .sp .5 |
---|
103 | \s-1AUTH\s0 * |
---|
104 | authunix_create_default(\|) |
---|
105 | .fi |
---|
106 | .ft R |
---|
107 | .IP |
---|
108 | Calls |
---|
109 | .B authunix_create(\|) |
---|
110 | with the appropriate parameters. |
---|
111 | .br |
---|
112 | .if t .ne 13 |
---|
113 | .LP |
---|
114 | .ft B |
---|
115 | .nf |
---|
116 | .sp .5 |
---|
117 | callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out) |
---|
118 | char *host; |
---|
119 | u_long prognum, versnum, procnum; |
---|
120 | char *in, *out; |
---|
121 | xdrproc_t inproc, outproc; |
---|
122 | .fi |
---|
123 | .ft R |
---|
124 | .IP |
---|
125 | Call the remote procedure associated with |
---|
126 | .IR prognum , |
---|
127 | .IR versnum , |
---|
128 | and |
---|
129 | .I procnum |
---|
130 | on the machine, |
---|
131 | .IR host . |
---|
132 | The parameter |
---|
133 | .I in |
---|
134 | is the address of the procedure's argument(s), and |
---|
135 | .I out |
---|
136 | is the address of where to place the result(s); |
---|
137 | .I inproc |
---|
138 | is used to encode the procedure's parameters, and |
---|
139 | .I outproc |
---|
140 | is used to decode the procedure's results. |
---|
141 | This routine returns zero if it succeeds, or the value of |
---|
142 | .B "enum clnt_stat" |
---|
143 | cast to an integer if it fails. |
---|
144 | The routine |
---|
145 | .B clnt_perrno(\|) |
---|
146 | is handy for translating failure statuses into messages. |
---|
147 | .IP |
---|
148 | Warning: calling remote procedures with this routine |
---|
149 | uses |
---|
150 | .SM UDP/IP |
---|
151 | as a transport; see |
---|
152 | .B clntudp_create(\|) |
---|
153 | for restrictions. |
---|
154 | You do not have control of timeouts or authentication using |
---|
155 | this routine. |
---|
156 | .br |
---|
157 | .if t .ne 16 |
---|
158 | .LP |
---|
159 | .ft B |
---|
160 | .nf |
---|
161 | .sp .5 |
---|
162 | enum clnt_stat |
---|
163 | clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult) |
---|
164 | u_long prognum, versnum, procnum; |
---|
165 | char *in, *out; |
---|
166 | xdrproc_t inproc, outproc; |
---|
167 | resultproc_t eachresult; |
---|
168 | .fi |
---|
169 | .ft R |
---|
170 | .IP |
---|
171 | Like |
---|
172 | .BR callrpc(\|) , |
---|
173 | except the call message is broadcast to all locally |
---|
174 | connected broadcast nets. |
---|
175 | Each time it receives a |
---|
176 | response, this routine calls |
---|
177 | .BR eachresult(\|) , |
---|
178 | whose form is: |
---|
179 | .IP |
---|
180 | .RS 1i |
---|
181 | .ft B |
---|
182 | .nf |
---|
183 | eachresult(out, addr) |
---|
184 | char *out; |
---|
185 | struct sockaddr_in *addr; |
---|
186 | .ft R |
---|
187 | .fi |
---|
188 | .RE |
---|
189 | .IP |
---|
190 | where |
---|
191 | .I out |
---|
192 | is the same as |
---|
193 | .I out |
---|
194 | passed to |
---|
195 | .BR clnt_broadcast(\|) , |
---|
196 | except that the remote procedure's output is decoded there; |
---|
197 | .I addr |
---|
198 | points to the address of the machine that sent the results. |
---|
199 | If |
---|
200 | .B eachresult(\|) |
---|
201 | returns zero, |
---|
202 | .B clnt_broadcast(\|) |
---|
203 | waits for more replies; otherwise it returns with appropriate |
---|
204 | status. |
---|
205 | .IP |
---|
206 | Warning: broadcast sockets are limited in size to the |
---|
207 | maximum transfer unit of the data link. |
---|
208 | For ethernet, |
---|
209 | this value is 1500 bytes. |
---|
210 | .br |
---|
211 | .if t .ne 13 |
---|
212 | .LP |
---|
213 | .ft B |
---|
214 | .nf |
---|
215 | .sp .5 |
---|
216 | enum clnt_stat |
---|
217 | clnt_call(clnt, procnum, inproc, in, outproc, out, tout) |
---|
218 | \s-1CLIENT\s0 *clnt; |
---|
219 | u_long |
---|
220 | procnum; |
---|
221 | xdrproc_t inproc, outproc; |
---|
222 | char *in, *out; |
---|
223 | struct timeval tout; |
---|
224 | .fi |
---|
225 | .ft R |
---|
226 | .IP |
---|
227 | A macro that calls the remote procedure |
---|
228 | .I procnum |
---|
229 | associated with the client handle, |
---|
230 | .IR clnt , |
---|
231 | which is obtained with an |
---|
232 | .SM RPC |
---|
233 | client creation routine such as |
---|
234 | .BR clnt_create(\|) . |
---|
235 | The parameter |
---|
236 | .I in |
---|
237 | is the address of the procedure's argument(s), and |
---|
238 | .I out |
---|
239 | is the address of where to place the result(s); |
---|
240 | .I inproc |
---|
241 | is used to encode the procedure's parameters, and |
---|
242 | .I outproc |
---|
243 | is used to decode the procedure's results; |
---|
244 | .I tout |
---|
245 | is the time allowed for results to come back. |
---|
246 | .br |
---|
247 | .if t .ne 7 |
---|
248 | .LP |
---|
249 | .ft B |
---|
250 | .nf |
---|
251 | .sp .5 |
---|
252 | clnt_destroy(clnt) |
---|
253 | \s-1CLIENT\s0 *clnt; |
---|
254 | .fi |
---|
255 | .ft R |
---|
256 | .IP |
---|
257 | A macro that destroys the client's |
---|
258 | .SM RPC |
---|
259 | handle. |
---|
260 | Destruction usually involves deallocation |
---|
261 | of private data structures, including |
---|
262 | .I clnt |
---|
263 | itself. Use of |
---|
264 | .I clnt |
---|
265 | is undefined after calling |
---|
266 | .BR clnt_destroy(\|) . |
---|
267 | If the |
---|
268 | .SM RPC |
---|
269 | library opened the associated socket, it will close it also. |
---|
270 | Otherwise, the socket remains open. |
---|
271 | .br |
---|
272 | .if t .ne 10 |
---|
273 | .LP |
---|
274 | .ft B |
---|
275 | .nf |
---|
276 | .sp .5 |
---|
277 | \s-1CLIENT\s0 * |
---|
278 | clnt_create(host, prog, vers, proto) |
---|
279 | char *host; |
---|
280 | u_long prog, vers; |
---|
281 | char *proto; |
---|
282 | .fi |
---|
283 | .ft R |
---|
284 | .IP |
---|
285 | Generic client creation routine. |
---|
286 | .I host |
---|
287 | identifies the name of the remote host where the server |
---|
288 | is located. |
---|
289 | .I proto |
---|
290 | indicates which kind of transport protocol to use. |
---|
291 | The |
---|
292 | currently supported values for this field are \(lqudp\(rq |
---|
293 | and \(lqtcp\(rq. |
---|
294 | Default timeouts are set, but can be modified using |
---|
295 | .BR clnt_control(\|) . |
---|
296 | .IP |
---|
297 | Warning: Using |
---|
298 | .SM UDP |
---|
299 | has its shortcomings. Since |
---|
300 | .SM UDP\s0-based |
---|
301 | .SM RPC |
---|
302 | messages can only hold up to 8 Kbytes of encoded data, |
---|
303 | this transport cannot be used for procedures that take |
---|
304 | large arguments or return huge results. |
---|
305 | .br |
---|
306 | .if t .ne 10 |
---|
307 | .LP |
---|
308 | .ft B |
---|
309 | .nf |
---|
310 | .sp .5 |
---|
311 | bool_t |
---|
312 | clnt_control(cl, req, info) |
---|
313 | \s-1CLIENT\s0 *cl; |
---|
314 | u_int req; |
---|
315 | char *info; |
---|
316 | .fi |
---|
317 | .ft R |
---|
318 | .IP |
---|
319 | A macro used to change or retrieve various information |
---|
320 | about a client object. |
---|
321 | .I req |
---|
322 | indicates the type of operation, and |
---|
323 | .I info |
---|
324 | is a pointer to the information. |
---|
325 | For both |
---|
326 | .SM UDP |
---|
327 | and |
---|
328 | .SM TCP\s0, |
---|
329 | the supported values of |
---|
330 | .I req |
---|
331 | and their argument types and what they do are: |
---|
332 | .IP |
---|
333 | .nf |
---|
334 | .ta +2.0i +2.0i +2.0i |
---|
335 | .SM CLSET_TIMEOUT\s0 struct timeval set total timeout |
---|
336 | .SM CLGET_TIMEOUT\s0 struct timeval get total timeout |
---|
337 | .fi |
---|
338 | .IP |
---|
339 | Note: if you set the timeout using |
---|
340 | .BR clnt_control(\|) , |
---|
341 | the timeout parameter passed to |
---|
342 | .B clnt_call(\|) |
---|
343 | will be ignored in all future calls. |
---|
344 | .IP |
---|
345 | .nf |
---|
346 | .SM CLGET_SERVER_ADDR\s0 struct sockaddr_in get server's address |
---|
347 | .fi |
---|
348 | .br |
---|
349 | .IP |
---|
350 | The following operations are valid for |
---|
351 | .SM UDP |
---|
352 | only: |
---|
353 | .IP |
---|
354 | .nf |
---|
355 | .ta +2.0i ; +2.0i ; +2.0i |
---|
356 | .SM CLSET_RETRY_TIMEOUT\s0 struct timeval set the retry timeout |
---|
357 | .SM CLGET_RETRY_TIMEOUT\s0 struct timeval get the retry timeout |
---|
358 | .fi |
---|
359 | .br |
---|
360 | .IP |
---|
361 | The retry timeout is the time that |
---|
362 | .SM "UDP RPC" |
---|
363 | waits for the server to reply before |
---|
364 | retransmitting the request. |
---|
365 | .br |
---|
366 | .if t .ne 10 |
---|
367 | .LP |
---|
368 | .ft B |
---|
369 | .nf |
---|
370 | .sp .5 |
---|
371 | clnt_freeres(clnt, outproc, out) |
---|
372 | \s-1CLIENT\s0 *clnt; |
---|
373 | xdrproc_t outproc; |
---|
374 | char *out; |
---|
375 | .fi |
---|
376 | .ft R |
---|
377 | .IP |
---|
378 | A macro that frees any data allocated by the |
---|
379 | .SM RPC/XDR |
---|
380 | system when it decoded the results of an |
---|
381 | .SM RPC |
---|
382 | call. The |
---|
383 | parameter |
---|
384 | .I out |
---|
385 | is the address of the results, and |
---|
386 | .I outproc |
---|
387 | is the |
---|
388 | .SM XDR |
---|
389 | routine describing the results. |
---|
390 | This routine returns one if the results were successfully |
---|
391 | freed, |
---|
392 | and zero otherwise. |
---|
393 | .br |
---|
394 | .if t .ne 6 |
---|
395 | .LP |
---|
396 | .ft B |
---|
397 | .nf |
---|
398 | .sp .5 |
---|
399 | void |
---|
400 | clnt_geterr(clnt, errp) |
---|
401 | \s-1CLIENT\s0 *clnt; |
---|
402 | struct rpc_err *errp; |
---|
403 | .fi |
---|
404 | .ft R |
---|
405 | .IP |
---|
406 | A macro that copies the error structure out of the client |
---|
407 | handle |
---|
408 | to the structure at address |
---|
409 | .IR errp . |
---|
410 | .br |
---|
411 | .if t .ne 8 |
---|
412 | .LP |
---|
413 | .ft B |
---|
414 | .nf |
---|
415 | .sp .5 |
---|
416 | void |
---|
417 | clnt_pcreateerror(s) |
---|
418 | char *s; |
---|
419 | .fi |
---|
420 | .ft R |
---|
421 | .IP |
---|
422 | Print a message to standard error indicating |
---|
423 | why a client |
---|
424 | .SM RPC |
---|
425 | handle could not be created. |
---|
426 | The message is prepended with string |
---|
427 | .I s |
---|
428 | and a colon. |
---|
429 | Used when a |
---|
430 | .BR clnt_create(\|) , |
---|
431 | .BR clntraw_create(\|) , |
---|
432 | .BR clnttcp_create(\|) , |
---|
433 | or |
---|
434 | .B clntudp_create(\|) |
---|
435 | call fails. |
---|
436 | .br |
---|
437 | .if t .ne 8 |
---|
438 | .LP |
---|
439 | .ft B |
---|
440 | .nf |
---|
441 | .sp .5 |
---|
442 | void |
---|
443 | clnt_perrno(stat) |
---|
444 | enum clnt_stat stat; |
---|
445 | .fi |
---|
446 | .ft R |
---|
447 | .IP |
---|
448 | Print a message to standard error corresponding |
---|
449 | to the condition indicated by |
---|
450 | .IR stat . |
---|
451 | Used after |
---|
452 | .BR callrpc(\|) . |
---|
453 | .br |
---|
454 | .if t .ne 8 |
---|
455 | .LP |
---|
456 | .ft B |
---|
457 | .nf |
---|
458 | .sp .5 |
---|
459 | clnt_perror(clnt, s) |
---|
460 | \s-1CLIENT\s0 *clnt; |
---|
461 | char *s; |
---|
462 | .fi |
---|
463 | .ft R |
---|
464 | .IP |
---|
465 | Print a message to standard error indicating why an |
---|
466 | .SM RPC |
---|
467 | call failed; |
---|
468 | .I clnt |
---|
469 | is the handle used to do the call. |
---|
470 | The message is prepended with string |
---|
471 | .I s |
---|
472 | and a colon. |
---|
473 | Used after |
---|
474 | .BR clnt_call(\|) . |
---|
475 | .br |
---|
476 | .if t .ne 9 |
---|
477 | .LP |
---|
478 | .ft B |
---|
479 | .nf |
---|
480 | .sp .5 |
---|
481 | char * |
---|
482 | clnt_spcreateerror |
---|
483 | char *s; |
---|
484 | .fi |
---|
485 | .ft R |
---|
486 | .IP |
---|
487 | Like |
---|
488 | .BR clnt_pcreateerror(\|) , |
---|
489 | except that it returns a string |
---|
490 | instead of printing to the standard error. |
---|
491 | .IP |
---|
492 | Bugs: returns pointer to static data that is overwritten |
---|
493 | on each call. |
---|
494 | .br |
---|
495 | .if t .ne 9 |
---|
496 | .LP |
---|
497 | .ft B |
---|
498 | .nf |
---|
499 | .sp .5 |
---|
500 | char * |
---|
501 | clnt_sperrno(stat) |
---|
502 | enum clnt_stat stat; |
---|
503 | .fi |
---|
504 | .ft R |
---|
505 | .IP |
---|
506 | Take the same arguments as |
---|
507 | .BR clnt_perrno(\|) , |
---|
508 | but instead of sending a message to the standard error |
---|
509 | indicating why an |
---|
510 | .SM RPC |
---|
511 | call failed, return a pointer to a string which contains |
---|
512 | the message. The string ends with a |
---|
513 | .SM NEWLINE\s0. |
---|
514 | .IP |
---|
515 | .B clnt_sperrno(\|) |
---|
516 | is used instead of |
---|
517 | .B clnt_perrno(\|) |
---|
518 | if the program does not have a standard error (as a program |
---|
519 | running as a server quite likely does not), or if the |
---|
520 | programmer |
---|
521 | does not want the message to be output with |
---|
522 | .BR printf , |
---|
523 | or if a message format different from that supported by |
---|
524 | .B clnt_perrno(\|) |
---|
525 | is to be used. |
---|
526 | Note: unlike |
---|
527 | .B clnt_sperror(\|) |
---|
528 | and |
---|
529 | .BR clnt_spcreaterror(\|) , |
---|
530 | .B clnt_sperrno(\|) |
---|
531 | returns pointer to static data, but the |
---|
532 | result will not get overwritten on each call. |
---|
533 | .br |
---|
534 | .if t .ne 7 |
---|
535 | .LP |
---|
536 | .ft B |
---|
537 | .nf |
---|
538 | .sp .5 |
---|
539 | char * |
---|
540 | clnt_sperror(rpch, s) |
---|
541 | \s-1CLIENT\s0 *rpch; |
---|
542 | char *s; |
---|
543 | .fi |
---|
544 | .ft R |
---|
545 | .IP |
---|
546 | Like |
---|
547 | .BR clnt_perror(\|) , |
---|
548 | except that (like |
---|
549 | .BR clnt_sperrno(\|) ) |
---|
550 | it returns a string instead of printing to standard error. |
---|
551 | .IP |
---|
552 | Bugs: returns pointer to static data that is overwritten |
---|
553 | on each call. |
---|
554 | .br |
---|
555 | .if t .ne 10 |
---|
556 | .LP |
---|
557 | .ft B |
---|
558 | .nf |
---|
559 | .sp .5 |
---|
560 | \s-1CLIENT\s0 * |
---|
561 | clntraw_create(prognum, versnum) |
---|
562 | u_long prognum, versnum; |
---|
563 | .fi |
---|
564 | .ft R |
---|
565 | .IP |
---|
566 | This routine creates a toy |
---|
567 | .SM RPC |
---|
568 | client for the remote program |
---|
569 | .IR prognum , |
---|
570 | version |
---|
571 | .IR versnum . |
---|
572 | The transport used to pass messages to the service is |
---|
573 | actually a buffer within the process's address space, so the |
---|
574 | corresponding |
---|
575 | .SM RPC |
---|
576 | server should live in the same address space; see |
---|
577 | .BR svcraw_create(\|) . |
---|
578 | This allows simulation of |
---|
579 | .SM RPC |
---|
580 | and acquisition of |
---|
581 | .SM RPC |
---|
582 | overheads, such as round trip times, without any |
---|
583 | kernel interference. |
---|
584 | This routine returns |
---|
585 | .SM NULL |
---|
586 | if it fails. |
---|
587 | .br |
---|
588 | .if t .ne 15 |
---|
589 | .LP |
---|
590 | .ft B |
---|
591 | .nf |
---|
592 | .sp .5 |
---|
593 | \s-1CLIENT\s0 * |
---|
594 | clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz) |
---|
595 | struct sockaddr_in *addr; |
---|
596 | u_long prognum, versnum; |
---|
597 | int *sockp; |
---|
598 | u_int sendsz, recvsz; |
---|
599 | .fi |
---|
600 | .ft R |
---|
601 | .IP |
---|
602 | This routine creates an |
---|
603 | .SM RPC |
---|
604 | client for the remote program |
---|
605 | .IR prognum , |
---|
606 | version |
---|
607 | .IR versnum ; |
---|
608 | the client uses |
---|
609 | .SM TCP/IP |
---|
610 | as a transport. |
---|
611 | The remote program is located at Internet |
---|
612 | address |
---|
613 | .IR *addr . |
---|
614 | If |
---|
615 | .\"The following in-line font conversion is necessary for the hyphen indicator |
---|
616 | \fB\%addr\->sin_port\fR |
---|
617 | is zero, then it is set to the actual port that the remote |
---|
618 | program is listening on (the remote |
---|
619 | .B portmap |
---|
620 | service is consulted for this information). The parameter |
---|
621 | .I sockp |
---|
622 | is a socket; if it is |
---|
623 | .BR \s-1RPC_ANYSOCK\s0 , |
---|
624 | then this routine opens a new one and sets |
---|
625 | .IR sockp . |
---|
626 | Since |
---|
627 | .SM TCP\s0-based |
---|
628 | .SM RPC |
---|
629 | uses buffered |
---|
630 | .SM I/O , |
---|
631 | the user may specify the size of the send and receive buffers |
---|
632 | with the parameters |
---|
633 | .I sendsz |
---|
634 | and |
---|
635 | .IR recvsz ; |
---|
636 | values of zero choose suitable defaults. |
---|
637 | This routine returns |
---|
638 | .SM NULL |
---|
639 | if it fails. |
---|
640 | .br |
---|
641 | .if t .ne 15 |
---|
642 | .LP |
---|
643 | .ft B |
---|
644 | .nf |
---|
645 | .sp .5 |
---|
646 | \s-1CLIENT\s0 * |
---|
647 | clntudp_create(addr, prognum, versnum, wait, sockp) |
---|
648 | struct sockaddr_in *addr; |
---|
649 | u_long prognum, versnum; |
---|
650 | struct timeval wait; |
---|
651 | int *sockp; |
---|
652 | .fi |
---|
653 | .ft R |
---|
654 | .IP |
---|
655 | This routine creates an |
---|
656 | .SM RPC |
---|
657 | client for the remote program |
---|
658 | .IR prognum , |
---|
659 | version |
---|
660 | .IR versnum ; |
---|
661 | the client uses |
---|
662 | .SM UDP/IP |
---|
663 | as a transport. |
---|
664 | The remote program is located at Internet |
---|
665 | address |
---|
666 | .IR addr . |
---|
667 | If |
---|
668 | \fB\%addr\->sin_port\fR |
---|
669 | is zero, then it is set to actual port that the remote |
---|
670 | program is listening on (the remote |
---|
671 | .B portmap |
---|
672 | service is consulted for this information). The parameter |
---|
673 | .I sockp |
---|
674 | is a socket; if it is |
---|
675 | .BR \s-1RPC_ANYSOCK\s0 , |
---|
676 | then this routine opens a new one and sets |
---|
677 | .IR sockp . |
---|
678 | The |
---|
679 | .SM UDP |
---|
680 | transport resends the call message in intervals of |
---|
681 | .B wait |
---|
682 | time until a response is received or until the call times |
---|
683 | out. |
---|
684 | The total time for the call to time out is specified by |
---|
685 | .BR clnt_call(\|) . |
---|
686 | .IP |
---|
687 | Warning: since |
---|
688 | .SM UDP\s0-based |
---|
689 | .SM RPC |
---|
690 | messages can only hold up to 8 Kbytes |
---|
691 | of encoded data, this transport cannot be used for procedures |
---|
692 | that take large arguments or return huge results. |
---|
693 | .br |
---|
694 | .if t .ne 8 |
---|
695 | .LP |
---|
696 | .ft B |
---|
697 | .nf |
---|
698 | .sp .5 |
---|
699 | \s-1CLIENT\s0 * |
---|
700 | clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsize, recosize) |
---|
701 | struct sockaddr_in *addr; |
---|
702 | u_long prognum, versnum; |
---|
703 | struct timeval wait; |
---|
704 | int *sockp; |
---|
705 | unsigned int sendsize; |
---|
706 | unsigned int recosize; |
---|
707 | .fi |
---|
708 | .ft R |
---|
709 | .IP |
---|
710 | This routine creates an |
---|
711 | .SM RPC |
---|
712 | client for the remote program |
---|
713 | .IR prognum , |
---|
714 | on |
---|
715 | .IR versnum ; |
---|
716 | the client uses |
---|
717 | .SM UDP/IP |
---|
718 | as a transport. |
---|
719 | The remote program is located at Internet |
---|
720 | address |
---|
721 | .IR addr . |
---|
722 | If |
---|
723 | \fB\%addr\->sin_port\fR |
---|
724 | is zero, then it is set to actual port that the remote |
---|
725 | program is listening on (the remote |
---|
726 | .B portmap |
---|
727 | service is consulted for this information). The parameter |
---|
728 | .I sockp |
---|
729 | is a socket; if it is |
---|
730 | .BR \s-1RPC_ANYSOCK\s0 , |
---|
731 | then this routine opens a new one and sets |
---|
732 | .BR sockp . |
---|
733 | The |
---|
734 | .SM UDP |
---|
735 | transport resends the call message in intervals of |
---|
736 | .B wait |
---|
737 | time until a response is received or until the call times |
---|
738 | out. |
---|
739 | The total time for the call to time out is specified by |
---|
740 | .BR clnt_call(\|) . |
---|
741 | .IP |
---|
742 | This allows the user to specify the maximum packet size for sending and receiving |
---|
743 | .SM UDP\s0-based |
---|
744 | .SM RPC |
---|
745 | messages. |
---|
746 | .br |
---|
747 | .if t .ne 7 |
---|
748 | .LP |
---|
749 | .ft B |
---|
750 | .nf |
---|
751 | .sp .5 |
---|
752 | int |
---|
753 | get_myaddress(addr) |
---|
754 | struct sockaddr_in *addr; |
---|
755 | .fi |
---|
756 | .ft R |
---|
757 | .IP |
---|
758 | Stuff the machine's |
---|
759 | .SM IP |
---|
760 | address into |
---|
761 | .IR *addr , |
---|
762 | without consulting the library routines that deal with |
---|
763 | .BR /etc/hosts . |
---|
764 | The port number is always set to |
---|
765 | .BR htons(\s-1PMAPPORT\s0) . |
---|
766 | Returns zero on success, non-zero on failure. |
---|
767 | .br |
---|
768 | .if t .ne 10 |
---|
769 | .LP |
---|
770 | .ft B |
---|
771 | .nf |
---|
772 | .sp .5 |
---|
773 | struct pmaplist * |
---|
774 | pmap_getmaps(addr) |
---|
775 | struct sockaddr_in *addr; |
---|
776 | .fi |
---|
777 | .ft R |
---|
778 | .IP |
---|
779 | A user interface to the |
---|
780 | .B portmap |
---|
781 | service, which returns a list of the current |
---|
782 | .SM RPC |
---|
783 | program-to-port mappings |
---|
784 | on the host located at |
---|
785 | .SM IP |
---|
786 | address |
---|
787 | .IR *addr . |
---|
788 | This routine can return |
---|
789 | .SM NULL . |
---|
790 | The command |
---|
791 | .RB ` "rpcinfo \-p" ' |
---|
792 | uses this routine. |
---|
793 | .br |
---|
794 | .if t .ne 12 |
---|
795 | .LP |
---|
796 | .ft B |
---|
797 | .nf |
---|
798 | .sp .5 |
---|
799 | u_short |
---|
800 | pmap_getport(addr, prognum, versnum, protocol) |
---|
801 | struct sockaddr_in *addr; |
---|
802 | u_long prognum, versnum, protocol; |
---|
803 | .fi |
---|
804 | .ft R |
---|
805 | .IP |
---|
806 | A user interface to the |
---|
807 | .B portmap |
---|
808 | service, which returns the port number |
---|
809 | on which waits a service that supports program number |
---|
810 | .IR prognum , |
---|
811 | version |
---|
812 | .IR versnum , |
---|
813 | and speaks the transport protocol associated with |
---|
814 | .IR protocol . |
---|
815 | The value of |
---|
816 | .I protocol |
---|
817 | is most likely |
---|
818 | .B |
---|
819 | .SM IPPROTO_UDP |
---|
820 | or |
---|
821 | .BR \s-1IPPROTO_TCP\s0 . |
---|
822 | A return value of zero means that the mapping does not exist |
---|
823 | or that |
---|
824 | the |
---|
825 | .SM RPC |
---|
826 | system failed to contact the remote |
---|
827 | .B portmap |
---|
828 | service. In the latter case, the global variable |
---|
829 | .B rpc_createerr(\|) |
---|
830 | contains the |
---|
831 | .SM RPC |
---|
832 | status. |
---|
833 | .br |
---|
834 | .if t .ne 15 |
---|
835 | .LP |
---|
836 | .ft B |
---|
837 | .nf |
---|
838 | .sp .5 |
---|
839 | enum clnt_stat |
---|
840 | pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, tout, portp) |
---|
841 | struct sockaddr_in *addr; |
---|
842 | u_long prognum, versnum, procnum; |
---|
843 | char *in, *out; |
---|
844 | xdrproc_t inproc, outproc; |
---|
845 | struct timeval tout; |
---|
846 | u_long *portp; |
---|
847 | .fi |
---|
848 | .ft R |
---|
849 | .IP |
---|
850 | A user interface to the |
---|
851 | .B portmap |
---|
852 | service, which instructs |
---|
853 | .B portmap |
---|
854 | on the host at |
---|
855 | .SM IP |
---|
856 | address |
---|
857 | .I *addr |
---|
858 | to make an |
---|
859 | .SM RPC |
---|
860 | call on your behalf to a procedure on that host. |
---|
861 | The parameter |
---|
862 | .I *portp |
---|
863 | will be modified to the program's port number if the |
---|
864 | procedure |
---|
865 | succeeds. |
---|
866 | The definitions of other parameters are discussed |
---|
867 | in |
---|
868 | .B callrpc(\|) |
---|
869 | and |
---|
870 | .BR clnt_call(\|) . |
---|
871 | This procedure should be used for a \(lqping\(rq and nothing |
---|
872 | else. |
---|
873 | See also |
---|
874 | .BR clnt_broadcast(\|) . |
---|
875 | .br |
---|
876 | .if t .ne 9 |
---|
877 | .LP |
---|
878 | .ft B |
---|
879 | .nf |
---|
880 | .sp .5 |
---|
881 | pmap_set(prognum, versnum, protocol, port) |
---|
882 | u_long prognum, versnum, protocol; |
---|
883 | u_short port; |
---|
884 | .fi |
---|
885 | .ft R |
---|
886 | .IP |
---|
887 | A user interface to the |
---|
888 | .B portmap |
---|
889 | service, which establishes a mapping between the triple |
---|
890 | .RI [ prognum , versnum , protocol\fR] |
---|
891 | and |
---|
892 | .I port |
---|
893 | on the machine's |
---|
894 | .B portmap |
---|
895 | service. |
---|
896 | The value of |
---|
897 | .I protocol |
---|
898 | is most likely |
---|
899 | .B |
---|
900 | .SM IPPROTO_UDP |
---|
901 | or |
---|
902 | .BR \s-1IPPROTO_TCP\s0 . |
---|
903 | This routine returns one if it succeeds, zero otherwise. |
---|
904 | Automatically done by |
---|
905 | .BR svc_register(\|) . |
---|
906 | .br |
---|
907 | .if t .ne 7 |
---|
908 | .LP |
---|
909 | .ft B |
---|
910 | .nf |
---|
911 | .sp .5 |
---|
912 | pmap_unset(prognum, versnum) |
---|
913 | u_long prognum, versnum; |
---|
914 | .fi |
---|
915 | .ft R |
---|
916 | .IP |
---|
917 | A user interface to the |
---|
918 | .B portmap |
---|
919 | service, which destroys all mapping between the triple |
---|
920 | .RI [ prognum , versnum , *\fR] |
---|
921 | and |
---|
922 | .B ports |
---|
923 | on the machine's |
---|
924 | .B portmap |
---|
925 | service. |
---|
926 | This routine returns one if it succeeds, zero |
---|
927 | otherwise. |
---|
928 | .br |
---|
929 | .if t .ne 15 |
---|
930 | .LP |
---|
931 | .ft B |
---|
932 | .nf |
---|
933 | .sp .5 |
---|
934 | registerrpc(prognum, versnum, procnum, procname, inproc, outproc) |
---|
935 | u_long prognum, versnum, procnum; |
---|
936 | char *(*procname) (\|) ; |
---|
937 | xdrproc_t inproc, outproc; |
---|
938 | .fi |
---|
939 | .ft R |
---|
940 | .IP |
---|
941 | Register procedure |
---|
942 | .I procname |
---|
943 | with the |
---|
944 | .SM RPC |
---|
945 | service package. If a request arrives for program |
---|
946 | .IR prognum , |
---|
947 | version |
---|
948 | .IR versnum , |
---|
949 | and procedure |
---|
950 | .IR procnum , |
---|
951 | .I procname |
---|
952 | is called with a pointer to its parameter(s); |
---|
953 | .I progname |
---|
954 | should return a pointer to its static result(s); |
---|
955 | .I inproc |
---|
956 | is used to decode the parameters while |
---|
957 | .I outproc |
---|
958 | is used to encode the results. |
---|
959 | This routine returns zero if the registration succeeded, \-1 |
---|
960 | otherwise. |
---|
961 | .IP |
---|
962 | Warning: remote procedures registered in this form |
---|
963 | are accessed using the |
---|
964 | .SM UDP/IP |
---|
965 | transport; see |
---|
966 | .B svcudp_create(\|) |
---|
967 | for restrictions. |
---|
968 | .br |
---|
969 | .if t .ne 5 |
---|
970 | .LP |
---|
971 | .ft B |
---|
972 | .nf |
---|
973 | .sp .5 |
---|
974 | struct rpc_createerr rpc_createerr; |
---|
975 | .fi |
---|
976 | .ft R |
---|
977 | .IP |
---|
978 | A global variable whose value is set by any |
---|
979 | .SM RPC |
---|
980 | client creation routine |
---|
981 | that does not succeed. Use the routine |
---|
982 | .B clnt_pcreateerror(\|) |
---|
983 | to print the reason why. |
---|
984 | .if t .ne 7 |
---|
985 | .LP |
---|
986 | .ft B |
---|
987 | .nf |
---|
988 | .sp .5 |
---|
989 | svc_destroy(xprt) |
---|
990 | \s-1SVCXPRT\s0 * |
---|
991 | xprt; |
---|
992 | .fi |
---|
993 | .ft R |
---|
994 | .IP |
---|
995 | A macro that destroys the |
---|
996 | .SM RPC |
---|
997 | service transport handle, |
---|
998 | .IR xprt . |
---|
999 | Destruction usually involves deallocation |
---|
1000 | of private data structures, including |
---|
1001 | .I xprt |
---|
1002 | itself. Use of |
---|
1003 | .I xprt |
---|
1004 | is undefined after calling this routine. |
---|
1005 | .br |
---|
1006 | .if t .ne 8 |
---|
1007 | .LP |
---|
1008 | .ft B |
---|
1009 | .nf |
---|
1010 | .sp .5 |
---|
1011 | fd_set svc_fdset; |
---|
1012 | .fi |
---|
1013 | .ft R |
---|
1014 | .IP |
---|
1015 | A global variable reflecting the |
---|
1016 | .SM RPC |
---|
1017 | service side's |
---|
1018 | read file descriptor bit mask; it is suitable as a template parameter |
---|
1019 | to the |
---|
1020 | .B select |
---|
1021 | system call. |
---|
1022 | This is only of interest |
---|
1023 | if a service implementor does not call |
---|
1024 | .BR svc_run(\|) , |
---|
1025 | but rather does his own asynchronous event processing. |
---|
1026 | This variable is read-only (do not pass its address to |
---|
1027 | .BR select !), |
---|
1028 | yet it may change after calls to |
---|
1029 | .B svc_getreqset(\|) |
---|
1030 | or any creation routines. |
---|
1031 | .br |
---|
1032 | As well, note that if the process has descriptor limits |
---|
1033 | which are extended beyond |
---|
1034 | .BR FD_SETSIZE , |
---|
1035 | this variable will only be usable for the first |
---|
1036 | .BR FD_SETSIZE |
---|
1037 | descriptors. |
---|
1038 | .br |
---|
1039 | .if t .ne 6 |
---|
1040 | .LP |
---|
1041 | .ft B |
---|
1042 | .nf |
---|
1043 | .sp .5 |
---|
1044 | int svc_fds; |
---|
1045 | .fi |
---|
1046 | .ft R |
---|
1047 | .IP |
---|
1048 | Similar to |
---|
1049 | .BR svc_fedset(\|) , |
---|
1050 | but limited to 32 descriptors. |
---|
1051 | This |
---|
1052 | interface is obsoleted by |
---|
1053 | .BR svc_fdset(\|) . |
---|
1054 | .br |
---|
1055 | .if t .ne 9 |
---|
1056 | .LP |
---|
1057 | .ft B |
---|
1058 | .nf |
---|
1059 | .sp .5 |
---|
1060 | svc_freeargs(xprt, inproc, in) |
---|
1061 | \s-1SVCXPRT\s0 *xprt; |
---|
1062 | xdrproc_t inproc; |
---|
1063 | char *in; |
---|
1064 | .fi |
---|
1065 | .ft R |
---|
1066 | .IP |
---|
1067 | A macro that frees any data allocated by the |
---|
1068 | .SM RPC/XDR |
---|
1069 | system when it decoded the arguments to a service procedure |
---|
1070 | using |
---|
1071 | .BR svc_getargs(\|) . |
---|
1072 | This routine returns 1 if the results were successfully |
---|
1073 | freed, |
---|
1074 | and zero otherwise. |
---|
1075 | .br |
---|
1076 | .if t .ne 10 |
---|
1077 | .LP |
---|
1078 | .ft B |
---|
1079 | .nf |
---|
1080 | .sp .5 |
---|
1081 | svc_getargs(xprt, inproc, in) |
---|
1082 | \s-1SVCXPRT\s0 *xprt; |
---|
1083 | xdrproc_t inproc; |
---|
1084 | char *in; |
---|
1085 | .fi |
---|
1086 | .ft R |
---|
1087 | .IP |
---|
1088 | A macro that decodes the arguments of an |
---|
1089 | .SM RPC |
---|
1090 | request |
---|
1091 | associated with the |
---|
1092 | .SM RPC |
---|
1093 | service transport handle, |
---|
1094 | .IR xprt . |
---|
1095 | The parameter |
---|
1096 | .I in |
---|
1097 | is the address where the arguments will be placed; |
---|
1098 | .I inproc |
---|
1099 | is the |
---|
1100 | .SM XDR |
---|
1101 | routine used to decode the arguments. |
---|
1102 | This routine returns one if decoding succeeds, and zero |
---|
1103 | otherwise. |
---|
1104 | .br |
---|
1105 | .if t .ne 9 |
---|
1106 | .LP |
---|
1107 | .ft B |
---|
1108 | .nf |
---|
1109 | .sp .5 |
---|
1110 | struct sockaddr_in * |
---|
1111 | svc_getcaller(xprt) |
---|
1112 | \s-1SVCXPRT\s0 *xprt; |
---|
1113 | .fi |
---|
1114 | .ft R |
---|
1115 | .IP |
---|
1116 | The approved way of getting the network address of the caller |
---|
1117 | of a procedure associated with the |
---|
1118 | .SM RPC |
---|
1119 | service transport handle, |
---|
1120 | .IR xprt . |
---|
1121 | .br |
---|
1122 | .if t .ne 9 |
---|
1123 | .LP |
---|
1124 | .ft B |
---|
1125 | .nf |
---|
1126 | .sp .5 |
---|
1127 | svc_getreqset(rdfds) |
---|
1128 | fd_set *rdfds; |
---|
1129 | .fi |
---|
1130 | .ft R |
---|
1131 | .IP |
---|
1132 | This routine is only of interest if a service implementor |
---|
1133 | does not call |
---|
1134 | .BR svc_run(\|) , |
---|
1135 | but instead implements custom asynchronous event processing. |
---|
1136 | It is called when the |
---|
1137 | .B select |
---|
1138 | system call has determined that an |
---|
1139 | .SM RPC |
---|
1140 | request has arrived on some |
---|
1141 | .SM RPC |
---|
1142 | .B socket(s) ; |
---|
1143 | .I rdfds |
---|
1144 | is the resultant read file descriptor bit mask. |
---|
1145 | The routine returns when all sockets associated with the |
---|
1146 | value of |
---|
1147 | .I rdfds |
---|
1148 | have been serviced. |
---|
1149 | .br |
---|
1150 | .if t .ne 6 |
---|
1151 | .LP |
---|
1152 | .ft B |
---|
1153 | .nf |
---|
1154 | .sp .5 |
---|
1155 | svc_getreq(rdfds) |
---|
1156 | int rdfds; |
---|
1157 | .fi |
---|
1158 | .ft R |
---|
1159 | .IP |
---|
1160 | Similar to |
---|
1161 | .BR svc_getreqset(\|) , |
---|
1162 | but limited to 32 descriptors. |
---|
1163 | This interface is obsoleted by |
---|
1164 | .BR svc_getreqset(\|) . |
---|
1165 | .br |
---|
1166 | .if t .ne 17 |
---|
1167 | .LP |
---|
1168 | .ft B |
---|
1169 | .nf |
---|
1170 | .sp .5 |
---|
1171 | svc_register(xprt, prognum, versnum, dispatch, protocol) |
---|
1172 | \s-1SVCXPRT\s0 *xprt; |
---|
1173 | u_long prognum, versnum; |
---|
1174 | void (*dispatch) (\|); |
---|
1175 | u_long protocol; |
---|
1176 | .fi |
---|
1177 | .ft R |
---|
1178 | .IP |
---|
1179 | Associates |
---|
1180 | .I prognum |
---|
1181 | and |
---|
1182 | .I versnum |
---|
1183 | with the service dispatch procedure, |
---|
1184 | .IR dispatch . |
---|
1185 | If |
---|
1186 | .I protocol |
---|
1187 | is zero, the service is not registered with the |
---|
1188 | .B portmap |
---|
1189 | service. If |
---|
1190 | .I protocol |
---|
1191 | is non-zero, then a mapping of the triple |
---|
1192 | .RI [ prognum , versnum , protocol\fR] |
---|
1193 | to |
---|
1194 | \fB\%xprt\->xp_port\fR |
---|
1195 | is established with the local |
---|
1196 | .B portmap |
---|
1197 | service (generally |
---|
1198 | .I protocol |
---|
1199 | is zero, |
---|
1200 | .B |
---|
1201 | .SM IPPROTO_UDP |
---|
1202 | or |
---|
1203 | .B |
---|
1204 | .SM IPPROTO_TCP |
---|
1205 | ). |
---|
1206 | The procedure |
---|
1207 | .I dispatch |
---|
1208 | has the following form: |
---|
1209 | .RS 1i |
---|
1210 | .ft B |
---|
1211 | .nf |
---|
1212 | dispatch(request, xprt) |
---|
1213 | struct svc_req *request; |
---|
1214 | \s-1SVCXPRT\s0 *xprt; |
---|
1215 | .ft R |
---|
1216 | .fi |
---|
1217 | .RE |
---|
1218 | .IP |
---|
1219 | The |
---|
1220 | .B svc_register(\|) |
---|
1221 | routine returns one if it succeeds, and zero otherwise. |
---|
1222 | .br |
---|
1223 | .if t .ne 6 |
---|
1224 | .LP |
---|
1225 | .ft B |
---|
1226 | .nf |
---|
1227 | .sp .5 |
---|
1228 | svc_run(\|) |
---|
1229 | .fi |
---|
1230 | .ft R |
---|
1231 | .IP |
---|
1232 | This routine never returns. |
---|
1233 | It waits for |
---|
1234 | .SM RPC |
---|
1235 | requests to arrive, and calls the appropriate service |
---|
1236 | procedure using |
---|
1237 | .B svc_getreq(\|) |
---|
1238 | when one arrives. |
---|
1239 | This procedure is usually waiting for a |
---|
1240 | .B select(\|) |
---|
1241 | system call to return. |
---|
1242 | .br |
---|
1243 | .if t .ne 9 |
---|
1244 | .LP |
---|
1245 | .ft B |
---|
1246 | .nf |
---|
1247 | .sp .5 |
---|
1248 | svc_sendreply(xprt, outproc, out) |
---|
1249 | \s-1SVCXPRT\s0 *xprt; |
---|
1250 | xdrproc_t outproc; |
---|
1251 | char *out; |
---|
1252 | .fi |
---|
1253 | .ft R |
---|
1254 | .IP |
---|
1255 | Called by an |
---|
1256 | .SM RPC |
---|
1257 | service's dispatch routine to send the results of a |
---|
1258 | remote procedure call. The parameter |
---|
1259 | .I xprt |
---|
1260 | is the request's associated transport handle; |
---|
1261 | .I outproc |
---|
1262 | is the |
---|
1263 | .SM XDR |
---|
1264 | routine which is used to encode the results; and |
---|
1265 | .I out |
---|
1266 | is the address of the results. |
---|
1267 | This routine returns one if it succeeds, zero otherwise. |
---|
1268 | .br |
---|
1269 | .if t .ne 7 |
---|
1270 | .LP |
---|
1271 | .ft B |
---|
1272 | .nf |
---|
1273 | .sp .5 |
---|
1274 | void |
---|
1275 | svc_unregister(prognum, versnum) |
---|
1276 | u_long prognum, versnum; |
---|
1277 | .fi |
---|
1278 | .ft R |
---|
1279 | .IP |
---|
1280 | Remove all mapping of the double |
---|
1281 | .RI [ prognum , versnum ] |
---|
1282 | to dispatch routines, and of the triple |
---|
1283 | .RI [ prognum , versnum , *\fR] |
---|
1284 | to port number. |
---|
1285 | .br |
---|
1286 | .if t .ne 9 |
---|
1287 | .LP |
---|
1288 | .ft B |
---|
1289 | .nf |
---|
1290 | .sp .5 |
---|
1291 | void |
---|
1292 | svcerr_auth(xprt, why) |
---|
1293 | \s-1SVCXPRT\s0 *xprt; |
---|
1294 | enum auth_stat why; |
---|
1295 | .fi |
---|
1296 | .ft R |
---|
1297 | .IP |
---|
1298 | Called by a service dispatch routine that refuses to perform |
---|
1299 | a remote procedure call due to an authentication error. |
---|
1300 | .br |
---|
1301 | .if t .ne 7 |
---|
1302 | .LP |
---|
1303 | .ft B |
---|
1304 | .nf |
---|
1305 | .sp .5 |
---|
1306 | void |
---|
1307 | svcerr_decode(xprt) |
---|
1308 | \s-1SVCXPRT\s0 *xprt; |
---|
1309 | .fi |
---|
1310 | .ft R |
---|
1311 | .IP |
---|
1312 | Called by a service dispatch routine that cannot successfully |
---|
1313 | decode its parameters. |
---|
1314 | See also |
---|
1315 | .BR svc_getargs(\|) . |
---|
1316 | .br |
---|
1317 | .if t .ne 7 |
---|
1318 | .LP |
---|
1319 | .ft B |
---|
1320 | .nf |
---|
1321 | .sp .5 |
---|
1322 | void |
---|
1323 | svcerr_noproc(xprt) |
---|
1324 | \s-1SVCXPRT\s0 *xprt; |
---|
1325 | .fi |
---|
1326 | .ft R |
---|
1327 | .IP |
---|
1328 | Called by a service dispatch routine that does not implement |
---|
1329 | the procedure number that the caller requests. |
---|
1330 | .br |
---|
1331 | .if t .ne 7 |
---|
1332 | .LP |
---|
1333 | .ft B |
---|
1334 | .nf |
---|
1335 | .sp .5 |
---|
1336 | void |
---|
1337 | svcerr_noprog(xprt) |
---|
1338 | \s-1SVCXPRT\s0 *xprt; |
---|
1339 | .fi |
---|
1340 | .ft R |
---|
1341 | .IP |
---|
1342 | Called when the desired program is not registered with the |
---|
1343 | .SM RPC |
---|
1344 | package. |
---|
1345 | Service implementors usually do not need this routine. |
---|
1346 | .br |
---|
1347 | .if t .ne 7 |
---|
1348 | .LP |
---|
1349 | .ft B |
---|
1350 | .nf |
---|
1351 | .sp .5 |
---|
1352 | void |
---|
1353 | svcerr_progvers(xprt) |
---|
1354 | \s-1SVCXPRT\s0 *xprt; |
---|
1355 | .fi |
---|
1356 | .ft R |
---|
1357 | .IP |
---|
1358 | Called when the desired version of a program is not registered |
---|
1359 | with the |
---|
1360 | .SM RPC |
---|
1361 | package. |
---|
1362 | Service implementors usually do not need this routine. |
---|
1363 | .br |
---|
1364 | .if t .ne 7 |
---|
1365 | .LP |
---|
1366 | .ft B |
---|
1367 | .nf |
---|
1368 | .sp .5 |
---|
1369 | void |
---|
1370 | svcerr_systemerr(xprt) |
---|
1371 | \s-1SVCXPRT\s0 *xprt; |
---|
1372 | .fi |
---|
1373 | .ft R |
---|
1374 | .IP |
---|
1375 | Called by a service dispatch routine when it detects a system |
---|
1376 | error |
---|
1377 | not covered by any particular protocol. |
---|
1378 | For example, if a service can no longer allocate storage, |
---|
1379 | it may call this routine. |
---|
1380 | .br |
---|
1381 | .if t .ne 8 |
---|
1382 | .LP |
---|
1383 | .ft B |
---|
1384 | .nf |
---|
1385 | .sp .5 |
---|
1386 | void |
---|
1387 | svcerr_weakauth(xprt) |
---|
1388 | \s-1SVCXPRT\s0 *xprt; |
---|
1389 | .fi |
---|
1390 | .ft R |
---|
1391 | .IP |
---|
1392 | Called by a service dispatch routine that refuses to perform |
---|
1393 | a remote procedure call due to insufficient |
---|
1394 | authentication parameters. The routine calls |
---|
1395 | .BR "svcerr_auth(xprt, \s-1AUTH_TOOWEAK\s0)" . |
---|
1396 | .br |
---|
1397 | .if t .ne 11 |
---|
1398 | .LP |
---|
1399 | .ft B |
---|
1400 | .nf |
---|
1401 | .sp .5 |
---|
1402 | \s-1SVCXPRT\s0 * |
---|
1403 | svcraw_create(\|) |
---|
1404 | .fi |
---|
1405 | .ft R |
---|
1406 | .IP |
---|
1407 | This routine creates a toy |
---|
1408 | .SM RPC |
---|
1409 | service transport, to which it returns a pointer. The |
---|
1410 | transport |
---|
1411 | is really a buffer within the process's address space, |
---|
1412 | so the corresponding |
---|
1413 | .SM RPC |
---|
1414 | client should live in the same |
---|
1415 | address space; |
---|
1416 | see |
---|
1417 | .BR clntraw_create(\|) . |
---|
1418 | This routine allows simulation of |
---|
1419 | .SM RPC |
---|
1420 | and acquisition of |
---|
1421 | .SM RPC |
---|
1422 | overheads (such as round trip times), without any kernel |
---|
1423 | interference. |
---|
1424 | This routine returns |
---|
1425 | .SM NULL |
---|
1426 | if it fails. |
---|
1427 | .br |
---|
1428 | .if t .ne 11 |
---|
1429 | .LP |
---|
1430 | .ft B |
---|
1431 | .nf |
---|
1432 | .sp .5 |
---|
1433 | \s-1SVCXPRT\s0 * |
---|
1434 | svctcp_create(sock, send_buf_size, recv_buf_size) |
---|
1435 | int sock; |
---|
1436 | u_int send_buf_size, recv_buf_size; |
---|
1437 | .fi |
---|
1438 | .ft R |
---|
1439 | .IP |
---|
1440 | This routine creates a |
---|
1441 | .SM TCP/IP\s0-based |
---|
1442 | .SM RPC |
---|
1443 | service transport, to which it returns a pointer. |
---|
1444 | The transport is associated with the socket |
---|
1445 | .IR sock , |
---|
1446 | which may be |
---|
1447 | .BR \s-1RPC_ANYSOCK\s0 , |
---|
1448 | in which case a new socket is created. |
---|
1449 | If the socket is not bound to a local |
---|
1450 | .SM TCP |
---|
1451 | port, then this routine binds it to an arbitrary port. Upon |
---|
1452 | completion, |
---|
1453 | \fB\%xprt\->xp_sock\fR |
---|
1454 | is the transport's socket descriptor, and |
---|
1455 | \fB\%xprt\->xp_port\fR |
---|
1456 | is the transport's port number. |
---|
1457 | This routine returns |
---|
1458 | .SM NULL |
---|
1459 | if it fails. |
---|
1460 | Since |
---|
1461 | .SM TCP\s0-based |
---|
1462 | .SM RPC |
---|
1463 | uses buffered |
---|
1464 | .SM I/O , |
---|
1465 | users may specify the size of buffers; values of zero |
---|
1466 | choose suitable defaults. |
---|
1467 | .br |
---|
1468 | .if t .ne 11 |
---|
1469 | .LP |
---|
1470 | .ft B |
---|
1471 | .nf |
---|
1472 | .sp .5 |
---|
1473 | \s-1SVCXPRT\s0 * |
---|
1474 | svcfd_create(fd, sendsize, recvsize) |
---|
1475 | int fd; |
---|
1476 | u_int sendsize; |
---|
1477 | u_int recvsize; |
---|
1478 | .fi |
---|
1479 | .ft R |
---|
1480 | .IP |
---|
1481 | Create a service on top of any open descriptor. |
---|
1482 | Typically, |
---|
1483 | this |
---|
1484 | descriptor is a connected socket for a stream protocol such |
---|
1485 | as |
---|
1486 | .SM TCP\s0. |
---|
1487 | .I sendsize |
---|
1488 | and |
---|
1489 | .I recvsize |
---|
1490 | indicate sizes for the send and receive buffers. If they are |
---|
1491 | zero, a reasonable default is chosen. |
---|
1492 | .br |
---|
1493 | .if t .ne 10 |
---|
1494 | .LP |
---|
1495 | .ft B |
---|
1496 | .nf |
---|
1497 | .sp .5 |
---|
1498 | \s-1SVCXPRT\s0 * |
---|
1499 | svcudp_bufcreate(sock, sendsize, recosize) |
---|
1500 | int sock; |
---|
1501 | .fi |
---|
1502 | .ft R |
---|
1503 | .IP |
---|
1504 | This routine creates a |
---|
1505 | .SM UDP/IP\s0-based |
---|
1506 | .SM RPC |
---|
1507 | service transport, to which it returns a pointer. |
---|
1508 | The transport is associated with the socket |
---|
1509 | .IR sock , |
---|
1510 | which may be |
---|
1511 | .B \s-1RPC_ANYSOCK\s0 , |
---|
1512 | in which case a new socket is created. |
---|
1513 | If the socket is not bound to a local |
---|
1514 | .SM UDP |
---|
1515 | port, then this routine binds it to an arbitrary port. |
---|
1516 | Upon |
---|
1517 | completion, |
---|
1518 | \fB\%xprt\->xp_sock\fR |
---|
1519 | is the transport's socket descriptor, and |
---|
1520 | \fB\%xprt\->xp_port\fR |
---|
1521 | is the transport's port number. |
---|
1522 | This routine returns |
---|
1523 | .SM NULL |
---|
1524 | if it fails. |
---|
1525 | .IP |
---|
1526 | This allows the user to specify the maximum packet size for sending and |
---|
1527 | receiving |
---|
1528 | .SM UDP\s0-based |
---|
1529 | .SM RPC messages. |
---|
1530 | .br |
---|
1531 | .if t .ne 7 |
---|
1532 | .LP |
---|
1533 | .ft B |
---|
1534 | .nf |
---|
1535 | .sp .5 |
---|
1536 | xdr_accepted_reply(xdrs, ar) |
---|
1537 | \s-1XDR\s0 *xdrs; |
---|
1538 | struct accepted_reply *ar; |
---|
1539 | .fi |
---|
1540 | .ft R |
---|
1541 | .IP |
---|
1542 | Used for encoding |
---|
1543 | .SM RPC |
---|
1544 | reply messages. |
---|
1545 | This routine is useful for users who |
---|
1546 | wish to generate |
---|
1547 | \s-1RPC\s0-style |
---|
1548 | messages without using the |
---|
1549 | .SM RPC |
---|
1550 | package. |
---|
1551 | .br |
---|
1552 | .if t .ne 7 |
---|
1553 | .LP |
---|
1554 | .ft B |
---|
1555 | .nf |
---|
1556 | .sp .5 |
---|
1557 | xdr_authunix_parms(xdrs, aupp) |
---|
1558 | \s-1XDR\s0 *xdrs; |
---|
1559 | struct authunix_parms *aupp; |
---|
1560 | .fi |
---|
1561 | .ft R |
---|
1562 | .IP |
---|
1563 | Used for describing |
---|
1564 | .SM UNIX |
---|
1565 | credentials. |
---|
1566 | This routine is useful for users |
---|
1567 | who wish to generate these credentials without using the |
---|
1568 | .SM RPC |
---|
1569 | authentication package. |
---|
1570 | .br |
---|
1571 | .if t .ne 7 |
---|
1572 | .LP |
---|
1573 | .ft B |
---|
1574 | .nf |
---|
1575 | .sp .5 |
---|
1576 | void |
---|
1577 | xdr_callhdr(xdrs, chdr) |
---|
1578 | \s-1XDR\s0 *xdrs; |
---|
1579 | struct rpc_msg *chdr; |
---|
1580 | .fi |
---|
1581 | .ft R |
---|
1582 | .IP |
---|
1583 | Used for describing |
---|
1584 | .SM RPC |
---|
1585 | call header messages. |
---|
1586 | This routine is useful for users who wish to generate |
---|
1587 | .SM RPC\s0-style |
---|
1588 | messages without using the |
---|
1589 | .SM RPC |
---|
1590 | package. |
---|
1591 | .br |
---|
1592 | .if t .ne 7 |
---|
1593 | .LP |
---|
1594 | .ft B |
---|
1595 | .nf |
---|
1596 | .sp .5 |
---|
1597 | xdr_callmsg(xdrs, cmsg) |
---|
1598 | \s-1XDR\s0 *xdrs; |
---|
1599 | struct rpc_msg *cmsg; |
---|
1600 | .fi |
---|
1601 | .ft R |
---|
1602 | .IP |
---|
1603 | Used for describing |
---|
1604 | .SM RPC |
---|
1605 | call messages. |
---|
1606 | This routine is useful for users who wish to generate |
---|
1607 | .SM RPC\s0-style |
---|
1608 | messages without using the |
---|
1609 | .SM RPC |
---|
1610 | package. |
---|
1611 | .br |
---|
1612 | .if t .ne 7 |
---|
1613 | .LP |
---|
1614 | .ft B |
---|
1615 | .nf |
---|
1616 | .sp .5 |
---|
1617 | xdr_opaque_auth(xdrs, ap) |
---|
1618 | \s-1XDR\s0 *xdrs; |
---|
1619 | struct opaque_auth *ap; |
---|
1620 | .fi |
---|
1621 | .ft R |
---|
1622 | .IP |
---|
1623 | Used for describing |
---|
1624 | .SM RPC |
---|
1625 | authentication information messages. |
---|
1626 | This routine is useful for users who wish to generate |
---|
1627 | .SM RPC\s0-style |
---|
1628 | messages without using the |
---|
1629 | .SM RPC |
---|
1630 | package. |
---|
1631 | .br |
---|
1632 | .if t .ne 7 |
---|
1633 | .LP |
---|
1634 | .ft B |
---|
1635 | .nf |
---|
1636 | .sp .5 |
---|
1637 | xdr_pmap(xdrs, regs) |
---|
1638 | \s-1XDR\s0 *xdrs; |
---|
1639 | struct pmap *regs; |
---|
1640 | .fi |
---|
1641 | .ft R |
---|
1642 | .IP |
---|
1643 | Used for describing parameters to various |
---|
1644 | .B portmap |
---|
1645 | procedures, externally. |
---|
1646 | This routine is useful for users who wish to generate |
---|
1647 | these parameters without using the |
---|
1648 | .B pmap |
---|
1649 | interface. |
---|
1650 | .br |
---|
1651 | .if t .ne 7 |
---|
1652 | .LP |
---|
1653 | .ft B |
---|
1654 | .nf |
---|
1655 | .sp .5 |
---|
1656 | xdr_pmaplist(xdrs, rp) |
---|
1657 | \s-1XDR\s0 *xdrs; |
---|
1658 | struct pmaplist **rp; |
---|
1659 | .fi |
---|
1660 | .ft R |
---|
1661 | .IP |
---|
1662 | Used for describing a list of port mappings, externally. |
---|
1663 | This routine is useful for users who wish to generate |
---|
1664 | these parameters without using the |
---|
1665 | .B pmap |
---|
1666 | interface. |
---|
1667 | .br |
---|
1668 | .if t .ne 7 |
---|
1669 | .LP |
---|
1670 | .ft B |
---|
1671 | .nf |
---|
1672 | .sp .5 |
---|
1673 | xdr_rejected_reply(xdrs, rr) |
---|
1674 | \s-1XDR\s0 *xdrs; |
---|
1675 | struct rejected_reply *rr; |
---|
1676 | .fi |
---|
1677 | .ft R |
---|
1678 | .IP |
---|
1679 | Used for describing |
---|
1680 | .SM RPC |
---|
1681 | reply messages. |
---|
1682 | This routine is useful for users who wish to generate |
---|
1683 | .SM RPC\s0-style |
---|
1684 | messages without using the |
---|
1685 | .SM RPC |
---|
1686 | package. |
---|
1687 | .br |
---|
1688 | .if t .ne 8 |
---|
1689 | .LP |
---|
1690 | .ft B |
---|
1691 | .nf |
---|
1692 | .sp .5 |
---|
1693 | xdr_replymsg(xdrs, rmsg) |
---|
1694 | \s-1XDR\s0 *xdrs; |
---|
1695 | struct rpc_msg *rmsg; |
---|
1696 | .fi |
---|
1697 | .ft R |
---|
1698 | .IP |
---|
1699 | Used for describing |
---|
1700 | .SM RPC |
---|
1701 | reply messages. |
---|
1702 | This routine is useful for users who wish to generate |
---|
1703 | .SM RPC |
---|
1704 | style messages without using the |
---|
1705 | .SM RPC |
---|
1706 | package. |
---|
1707 | .br |
---|
1708 | .if t .ne 8 |
---|
1709 | .LP |
---|
1710 | .ft B |
---|
1711 | .nf |
---|
1712 | .sp .5 |
---|
1713 | void |
---|
1714 | xprt_register(xprt) |
---|
1715 | \s-1SVCXPRT\s0 *xprt; |
---|
1716 | .fi |
---|
1717 | .ft R |
---|
1718 | .IP |
---|
1719 | After |
---|
1720 | .SM RPC |
---|
1721 | service transport handles are created, |
---|
1722 | they should register themselves with the |
---|
1723 | .SM RPC |
---|
1724 | service package. |
---|
1725 | This routine modifies the global variable |
---|
1726 | .BR svc_fds(\|) . |
---|
1727 | Service implementors usually do not need this routine. |
---|
1728 | .br |
---|
1729 | .if t .ne 8 |
---|
1730 | .LP |
---|
1731 | .ft B |
---|
1732 | .nf |
---|
1733 | .sp .5 |
---|
1734 | void |
---|
1735 | xprt_unregister(xprt) |
---|
1736 | \s-1SVCXPRT\s0 *xprt; |
---|
1737 | .fi |
---|
1738 | .ft R |
---|
1739 | .IP |
---|
1740 | Before an |
---|
1741 | .SM RPC |
---|
1742 | service transport handle is destroyed, |
---|
1743 | it should unregister itself with the |
---|
1744 | .SM RPC |
---|
1745 | service package. |
---|
1746 | This routine modifies the global variable |
---|
1747 | .BR svc_fds(\|) . |
---|
1748 | Service implementors usually do not need this routine. |
---|
1749 | .SH SEE ALSO |
---|
1750 | .BR rpc_secure (3), |
---|
1751 | .BR xdr (3) |
---|
1752 | .br |
---|
1753 | The following manuals: |
---|
1754 | .RS |
---|
1755 | .ft I |
---|
1756 | Remote Procedure Calls: Protocol Specification |
---|
1757 | .br |
---|
1758 | Remote Procedure Call Programming Guide |
---|
1759 | .br |
---|
1760 | rpcgen Programming Guide |
---|
1761 | .br |
---|
1762 | .ft R |
---|
1763 | .RE |
---|
1764 | .IR "\s-1RPC\s0: Remote Procedure Call Protocol Specification" , |
---|
1765 | .SM RFC1050, Sun Microsystems, Inc., |
---|
1766 | .SM USC-ISI\s0. |
---|
1767 | |
---|