| blob | 995644210846f7a6e34ce03724c1e84b20ea9e6b |
1 .\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
2 .\" $NetBSD: rpc_soc.3,v 1.14 2013/03/04 17:29:03 christos Exp $
3 .\" Converted to mdoc by Thomas Klausner <wiz@NetBSD.org>
4 .\"
5 .Dd December 12, 2008
6 .Dt RPC_SOC 3
7 .Os
8 .Sh NAME
9 .Nm rpc_soc ,
10 .Nm auth_destroy ,
11 .Nm authnone_create ,
12 .Nm authunix_create ,
13 .Nm authunix_create_default ,
14 .Nm callrpc ,
15 .Nm clnt_broadcast ,
16 .Nm clnt_call ,
17 .Nm clnt_control ,
18 .Nm clnt_create ,
19 .Nm clnt_destroy ,
20 .Nm clnt_freeres ,
21 .Nm clnt_geterr ,
22 .Nm clnt_pcreateerror ,
23 .Nm clnt_perrno ,
24 .Nm clnt_perror ,
25 .Nm clnt_spcreateerror ,
26 .Nm clnt_sperrno ,
27 .Nm clnt_sperror ,
28 .Nm clntraw_create ,
29 .Nm clnttcp_create ,
30 .Nm clntudp_bufcreate ,
31 .Nm clntudp_create ,
32 .Nm get_myaddress ,
33 .Nm pmap_getmaps ,
34 .Nm pmap_getport ,
35 .Nm pmap_rmtcall ,
36 .Nm pmap_set ,
37 .Nm pmap_unset ,
38 .Nm registerrpc ,
39 .Nm rpc_createerr ,
40 .Nm svc_destroy ,
41 .Nm svc_fds ,
42 .Nm svc_fdset ,
43 .Nm svc_getargs ,
44 .Nm svc_getcaller ,
45 .Nm svc_getreg ,
46 .Nm svc_getregset ,
47 .Nm svc_getrpccaller ,
48 .Nm svc_register ,
49 .Nm svc_run ,
50 .Nm svc_sendreply ,
51 .Nm svc_unregister ,
52 .Nm svcerr_auth ,
53 .Nm svcerr_decode ,
54 .Nm svcerr_noproc ,
55 .Nm svcerr_noprog ,
56 .Nm svcerr_progvers ,
57 .Nm svcerr_systemerr ,
58 .Nm svcerr_weakauth ,
59 .Nm svcfd_create ,
60 .Nm svcraw_create ,
61 .Nm xdr_accepted_reply ,
62 .Nm xdr_authunix_parms ,
63 .Nm xdr_callhdr ,
64 .Nm xdr_callmsg ,
65 .Nm xdr_opaque_auth ,
66 .Nm xdr_pmap ,
67 .Nm xdr_pmaplist ,
68 .Nm xdr_rejected_reply ,
69 .Nm xdr_replymsg ,
70 .Nm xprt_register ,
71 .Nm xprt_unregister
72 .Nd library routines for remote procedure calls
73 .Sh SYNOPSIS
74 .In rpc/rpc.h
75 .Ft void
76 .Fn auth_destroy "AUTH *auth"
77 .Ft AUTH *
78 .Fn authnone_create "void"
79 .Ft AUTH *
80 .Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids"
81 .Ft AUTH *
82 .Fn authunix_create_default "void"
83 .Ft int
84 .Fn callrpc "char *host" "u_long prognum" "u_long versnum" \
85 "u_long procnum" "xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out"
86 .Ft enum clnt_stat
87 .Fn clnt_broadcast "u_long prognum" "u_long versnum" "u_long procnum" \
88 "xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out" \
89 "resultproc_t eachresult"
90 .Ft enum clnt_stat
91 .Fn clnt_call "CLIENT *clnt" "u_long procnum" "xdrproc_t inproc" \
92 "char *in" "xdrproc_t outproc" "char *out" "struct timeval tout"
93 .Ft int
94 .Fn clnt_destroy "CLIENT *clnt"
95 .Ft CLIENT *
96 .Fn clnt_create "char *host" "u_long prog" "u_long vers" "char *proto"
97 .Ft bool_t
98 .Fn clnt_control "CLIENT *cl" "u_int req" "char *info"
99 .Ft int
100 .Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
101 .Ft void
102 .Fn clnt_geterr "CLIENT *clnt" "struct rpc_err errp"
103 .Ft void
104 .Fn clnt_pcreateerror "char *s"
105 .Ft void
106 .Fn clnt_perrno "enum clnt_stat stat"
107 .Ft int
108 .Fn clnt_perror "CLIENT *clnt" "char *s"
109 .Ft char *
110 .Fn clnt_spcreateerror "const char *s"
111 .Ft char *
112 .Fn clnt_sperrno "enum clnt_stat stat"
113 .Ft char *
114 .Fn clnt_sperror "CLIENT *rpch" "char *s"
115 .Ft CLIENT *
116 .Fn clntraw_create "u_long prognum" "u_long versnum"
117 .Ft CLIENT *
118 .Fn clnttcp_create "struct sockaddr_in *addr" "u_long prognum" \
119 "u_long versnum" "int *sockp" "u_int sendsz" "u_int recvsz"
120 .Ft CLIENT *
121 .Fn clntudp_create "struct sockaddr_in *addr" "u_long prognum" \
122 "u_long versnum" "struct timeval wait" "int *sockp"
123 .Ft CLIENT *
124 .Fn clntudp_bufcreate "struct sockaddr_in *addr" "u_long prognum" \
125 "u_long versnum" "struct timeval wait" "int *sockp" \
126 "unsigned int sendsize" "unsigned int recosize"
127 .Ft int
128 .Fn get_myaddress "struct sockaddr_in *addr"
129 .Ft struct pmaplist *
130 .Fn pmap_getmaps "struct sockaddr_in *addr"
131 .Ft u_short
132 .Fn pmap_getport "struct sockaddr_in *addr" "u_long prognum" \
133 "u_long versnum" "u_long protocol"
134 .Ft enum clnt_stat
135 .Fo pmap_rmtcall
136 .Fa "struct sockaddr_in *addr"
137 .Fa "u_long prognum"
138 .Fa "u_long versnum"
139 .Fa "u_long procnum"
140 .Fa "xdrproc_t inproc"
141 .Fa "char *in"
142 .Fa "xdrpoc_t outproc"
143 .Fa "char *out"
144 .Fa "struct timeval tout"
145 .Fa "u_long *portp"
146 .Fc
147 .Ft int
148 .Fn pmap_set "u_long prognum" "u_long versnum" "int protocol" \
149 "int port"
150 .Ft int
151 .Fn pmap_unset "u_long prognum" "u_long versnum"
152 .Ft int
153 .Fn registerrpc "u_long prognum" "u_long versnum" "u_long procnum" \
154 "char *(*procname)()" "xdrproc_t inproc" "xdrproc_t outproc"
155 .Fd struct rpc_createerr rpc_createerr;
156 .Ft int
157 .Fn svc_destroy "SVCXPRT *xprt"
158 .Fd fd_set svc_fdset;
159 .Fd int svc_fds;
160 .Ft int
161 .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
162 .Ft int
163 .Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
164 .Ft struct sockaddr_in *
165 .Fn svc_getcaller "SVCXPRT *xprt"
166 .Ft int
167 .Fn svc_getreqset "fd_set *rdfds"
168 .Ft int
169 .Fn svc_getreq "int rdfds"
170 .Ft struct netbuf *
171 .Fn svc_getrpccaller "SVCXPRT *xprt"
172 .Ft int
173 .Fn svc_register "SVCXPRT *xprt" "u_long prognum" "u_long versnum" \
174 "void (*dispatch)()" "u_long protocol"
175 .Ft int
176 .Fn svc_run "void"
177 .Ft int
178 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
179 .Ft void
180 .Fn svc_unregister "u_long prognum" "u_long versnum"
181 .Ft void
182 .Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
183 .Ft void
184 .Fn svcerr_decode "SVCXPRT *xprt"
185 .Ft void
186 .Fn svcerr_noproc "SVCXPRT *xprt"
187 .Ft void
188 .Fn svcerr_noprog "SVCXPRT *xprt"
189 .Ft void
190 .Fn svcerr_progvers "SVCXPRT *xprt"
191 .Ft void
192 .Fn svcerr_systemerr "SVCXPRT *xprt"
193 .Ft void
194 .Fn svcerr_weakauth "SVCXPRT *xprt"
195 .Ft SVCXPRT *
196 .Fn svcraw_create "void"
197 .Ft SVCXPRT *
198 .Fn svctcp_create "int sock" "u_int send_buf_size" \
199 "u_int recv_buf_size"
200 .Ft SVCXPRT *
201 .Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
202 .Ft SVCXPRT *
203 .Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recosize"
204 .Ft SVCXPRT *
205 .Fn svcudp_create "int sock"
206 .Ft int
207 .Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
208 .Ft int
209 .Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
210 .Ft void
211 .Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
212 .Ft int
213 .Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
214 .Ft int
215 .Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
216 .Ft int
217 .Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
218 .Ft int
219 .Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
220 .Ft int
221 .Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
222 .Ft int
223 .Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
224 .Ft bool_t
225 .Fn xprt_register "SVCXPRT *xprt"
226 .Ft void
227 .Fn xprt_unregister "SVCXPRT *xprt"
228 .Sh DESCRIPTION
229 .Em "The svc and clnt functions described in this page are the old, TS-RPC"
230 .Em "interface to the XDR and RPC library, and exist for backward compatibility."
231 .Em "The new interface is described in the pages referenced from"
232 .Xr rpc 3 .
233 .Pp
234 These routines allow C programs to make procedure
235 calls on other machines across the network.
236 First, the client calls a procedure to send a
237 data packet to the server.
238 Upon receipt of the packet, the server calls a dispatch routine
239 to perform the requested service, and then sends back a
240 reply.
241 Finally, the procedure call returns to the client.
242 .\" XXX: NOTYET
243 .\".Pp
244 .\"Routines that are used for Secure RPC (DES authentication) are described in
245 .\".Xr rpc_secure 3 .
246 .\"Secure RPC can be used only if DES encryption is available.
247 .Pp
248 .Bl -tag -width xxx
249 .It Fn auth_destroy
250 A macro that destroys the authentication information associated with
251 .Fa auth .
252 Destruction usually involves deallocation of private data structures.
253 The use of
254 .Fa auth
255 is undefined after calling
256 .Fn auth_destroy .
257 .It Fn authnone_create
258 Create and returns an RPC authentication handle that passes nonusable
259 authentication information with each remote procedure call.
260 This is the default authentication used by RPC.
261 .It Fn authunix_create
262 Create and return an RPC authentication handle that contains
263 .\" XXX: .UX ?
264 authentication information.
265 The parameter
266 .Fa host
267 is the name of the machine on which the information was
268 created;
269 .Fa uid
270 is the user's user ID;
271 .Fa gid
272 is the user's current group id;
273 .Fa len
274 and
275 .Fa aup_gids
276 refer to a counted array of groups to which the user belongs.
277 It is easy to impersonate a user.
278 .It Fn authunix_create_default
279 Calls
280 .Fn authunix_create
281 with the appropriate parameters.
282 .It Fn callrpc
283 Call the remote procedure associated with
284 .Fa prognum ,
285 .Fa versnum ,
286 and
287 .Fa procnum
288 on the machine,
289 .Fa host .
290 The parameter
291 .Fa in
292 is the address of the procedure's argument(s), and
293 .Fa out
294 is the address of where to place the result(s);
295 .Fa inproc
296 is used to encode the procedure's parameters, and
297 .Fa outproc
298 is used to decode the procedure's results.
299 This routine returns zero if it succeeds, or the value of
300 .Va "enum clnt_stat"
301 cast to an integer if it fails.
302 The routine
303 .Fn clnt_perrno
304 is handy for translating failure statuses into messages.
305 .Pp
306 Warning: calling remote procedures with this routine
307 uses UDP/IP as a transport; see
308 .Fn clntudp_create
309 for restrictions.
310 You do not have control of timeouts or authentication using
311 this routine.
312 .It Fn clnt_broadcast
313 Like
314 .Fn callrpc ,
315 except the call message is broadcast to all locally
316 connected broadcast nets.
317 Each time it receives a response, this routine calls
318 .Fn eachresult ,
319 whose form is
320 .Ft int
321 .Fn eachresult "char *out" "struct sockaddr_in *addr"
322 where
323 .Fa out
324 is the same as
325 .Fa out
326 passed to
327 .Fn clnt_broadcast ,
328 except that the remote procedure's output is decoded there;
329 .Fa addr
330 points to the address of the machine that sent the results.
331 If
332 .Fn eachresult
333 returns zero,
334 .Fn clnt_broadcast
335 waits for more replies; otherwise it returns with appropriate
336 status.
337 .Pp
338 Warning: broadcast sockets are limited in size to the
339 maximum transfer unit of the data link.
340 For ethernet, this value is 1500 bytes.
341 .It Fn clnt_call
342 A macro that calls the remote procedure
343 .Fa procnum
344 associated with the client handle,
345 .Fa clnt ,
346 which is obtained with an RPC client creation routine such as
347 .Fn clnt_create .
348 The parameter
349 .Fa in
350 is the address of the procedure's argument(s), and
351 .Fa out
352 is the address of where to place the result(s);
353 .Fa inproc
354 is used to encode the procedure's parameters, and
355 .Fa outproc
356 is used to decode the procedure's results;
357 .Fa tout
358 is the time allowed for results to come back.
359 .It Fn clnt_destroy
360 A macro that destroys the client's RPC handle.
361 Destruction usually involves deallocation
362 of private data structures, including
363 .Fa clnt
364 itself.
365 Use of
366 .Fa clnt
367 is undefined after calling
368 .Fn clnt_destroy .
369 If the RPC library opened the associated socket, it will close it
370 also.
371 Otherwise, the socket remains open.
372 .It Fn clnt_create
373 Generic client creation routine.
374 .Fa host
375 identifies the name of the remote host where the server
376 is located.
377 .Fa proto
378 indicates which kind of transport protocol to use.
379 The currently supported values for this field are
380 .Dq udp
381 and
382 .Dq tcp .
383 Default timeouts are set, but can be modified using
384 .Fn clnt_control .
385 .Pp
386 .Em Warning :
387 Using UDP has its shortcomings.
388 Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded
389 data, this transport cannot be used for procedures that take
390 large arguments or return huge results.
391 .It Fn clnt_control
392 A macro used to change or retrieve various information
393 about a client object.
394 .Fa req
395 indicates the type of operation, and
396 .Fa info
397 is a pointer to the information.
398 For both UDP and TCP the supported values of
399 .Fa req
400 and their argument types and what they do are:
401 .Bl -tag -width CLSET_RETRY_TIMEOUTX
402 .It CLSET_TIMEOUT
403 .Vt struct timeval ;
404 set total timeout.
405 .It CLGET_TIMEOUT
406 .Vt struct timeval ;
407 get total timeout.
408 .Pp
409 Note: if you set the timeout using
410 .Fn clnt_control ,
411 the timeout parameter passed to
412 .Fn clnt_call
413 will be ignored in all future calls.
414 .It CLGET_SERVER_ADDR
415 .Vt struct sockaddr_in ;
416 get server's address.
417 .El
418 .Pp
419 The following operations are valid for UDP only:
420 .Bl -tag -width CLSET_RETRY_TIMEOUT
421 .It CLSET_RETRY_TIMEOUT
422 .Vt struct timeval ;
423 set the retry timeout.
424 .It CLGET_RETRY_TIMEOUT
425 .Vt struct timeval ;
426 get the retry timeout.
427 .Pp
428 The retry timeout is the time that UDP RPC waits for the server to
429 reply before retransmitting the request.
430 .El
431 .It Fn clnt_freeres
432 A macro that frees any data allocated by the RPC/XDR system when it
433 decoded the results of an RPC call.
434 The parameter
435 .Fa out
436 is the address of the results, and
437 .Fa outproc
438 is the XDR routine describing the results.
439 This routine returns one if the results were successfully freed,
440 and zero otherwise.
441 .It Fn clnt_geterr
442 A macro that copies the error structure out of the client
443 handle to the structure at address
444 .Fa errp .
445 .It Fn clnt_pcreateerror
446 Print a message to standard error indicating why a client RPC handle
447 could not be created.
448 The message is prepended with string
449 .Fa s
450 and a colon.
451 A newline character is appended at the end of the message.
452 Used when a
453 .Fn clnt_create ,
454 .Fn clntraw_create ,
455 .Fn clnttcp_create ,
456 or
457 .Fn clntudp_create
458 call fails.
459 .It Fn clnt_perrno
460 Print a message to standard error corresponding
461 to the condition indicated by
462 .Fa stat .
463 A newline character is appended at the end of the message.
464 Used after
465 .Fn callrpc .
466 .It Fn clnt_perror
467 Print a message to standard error indicating why an RPC call failed;
468 .Fa clnt
469 is the handle used to do the call.
470 The message is prepended with string
471 .Fa s
472 and a colon.
473 A newline character is appended at the end of the message.
474 Used after
475 .Fn clnt_call .
476 .It Fn clnt_spcreateerror
477 Like
478 .Fn clnt_pcreateerror ,
479 except that it returns a string
480 instead of printing to the standard error.
481 .Pp
482 Bugs: returns pointer to static data that is overwritten
483 on each call.
484 .It Fn clnt_sperrno
485 Take the same arguments as
486 .Fn clnt_perrno ,
487 but instead of sending a message to the standard error
488 indicating why an RPC call failed, return a pointer to a string which
489 contains the message.
490 .Pp
491 .Fn clnt_sperrno
492 is used instead of
493 .Fn clnt_perrno
494 if the program does not have a standard error (as a program
495 running as a server quite likely does not), or if the
496 programmer does not want the message to be output with
497 .Xr printf 3 ,
498 or if a message format different than that supported by
499 .Fn clnt_perrno
500 is to be used.
501 Note: unlike
502 .Fn clnt_sperror
503 and
504 .Fn clnt_spcreateerror ,
505 .Fn clnt_sperrno
506 returns a pointer to static data, but the
507 result will not get overwritten on each call.
508 .It Fn clnt_sperror
509 Like
510 .Fn clnt_perror ,
511 except that (like
512 .Fn clnt_sperrno )
513 it returns a string instead of printing to standard error.
514 .Pp
515 Bugs: returns pointer to static data that is overwritten
516 on each call.
517 .It Fn clntraw_create
518 This routine creates a toy RPC client for the remote program
519 .Fa prognum ,
520 version
521 .Fa versnum .
522 The transport used to pass messages to the service is
523 actually a buffer within the process's address space, so the
524 corresponding RPC server should live in the same address space; see
525 .Fn svcraw_create .
526 This allows simulation of RPC and acquisition of RPC overheads, such
527 as round trip times, without any kernel interference.
528 This routine returns
529 .Dv NULL
530 if it fails.
531 .It Fn clnttcp_create
532 This routine creates an RPC client for the remote program
533 .Fa prognum ,
534 version
535 .Fa versnum ;
536 the client uses TCP/IP as a transport.
537 The remote program is located at Internet address
538 .Fa *addr .
539 If
540 .Fa addr-\*[Gt]sin_port
541 is zero, then it is set to the actual port that the remote
542 program is listening on (the remote
543 .Xr rpcbind 8
544 or
545 .Cm portmap
546 service is consulted for this information).
547 The parameter
548 .Fa sockp
549 is a socket; if it is
550 .Dv RPC_ANYSOCK ,
551 then this routine opens a new one and sets
552 .Fa sockp .
553 Since TCP-based RPC uses buffered I/O ,
554 the user may specify the size of the send and receive buffers
555 with the parameters
556 .Fa sendsz
557 and
558 .Fa recvsz ;
559 values of zero choose suitable defaults.
560 This routine returns
561 .Dv NULL
562 if it fails.
563 .It Fn clntudp_create
564 This routine creates an RPC client for the remote program
565 .Fa prognum ,
566 version
567 .Fa versnum ;
568 the client uses UDP/IP as a transport.
569 The remote program is located at Internet address
570 .Fa addr .
571 If
572 .Fa addr-\*[Gt]sin_port
573 is zero, then it is set to actual port that the remote
574 program is listening on (the remote
575 .Xr rpcbind 8
576 or
577 .Cm portmap
578 service is consulted for this information).
579 The parameter
580 .Fa sockp
581 is a socket; if it is
582 .Dv RPC_ANYSOCK ,
583 then this routine opens a new one and sets
584 .Fa sockp .
585 The UDP transport resends the call message in intervals of
586 .Fa wait
587 time until a response is received or until the call times out.
588 The total time for the call to time out is specified by
589 .Fa clnt_call .
590 .Pp
591 Warning: since UDP-based RPC messages can only hold up to 8 Kbytes
592 of encoded data, this transport cannot be used for procedures
593 that take large arguments or return huge results.
594 .It Fn clntudp_bufcreate
595 This routine creates an RPC client for the remote program
596 .Fa prognum ,
597 on
598 .Fa versnum ;
599 the client uses UDP/IP as a transport.
600 The remote program is located at Internet address
601 .Fa addr .
602 If
603 .Fa addr-\*[Gt]sin_port
604 is zero, then it is set to actual port that the remote
605 program is listening on (the remote
606 .Xr rpcbind 8
607 or
608 .Cm portmap
609 service is consulted for this information).
610 The parameter
611 .Fa sockp
612 is a socket; if it is
613 .Dv RPC_ANYSOCK ,
614 then this routine opens a new one and sets
615 .Fa sockp .
616 The UDP transport resends the call message in intervals of
617 .Fa wait
618 time until a response is received or until the call times out.
619 The total time for the call to time out is specified by
620 .Fa clnt_call .
621 .Pp
622 This allows the user to specify the maximum packet size for sending and
623 receiving UDP-based RPC messages.
624 .It Fn get_myaddress
625 Stuff the machine's IP address into
626 .Fa *addr ,
627 without consulting the library routines that deal with
628 .Pa /etc/hosts .
629 The port number is always set to
630 .Fn htons "PMAPPORT" .
631 Returns zero on success, non-zero on failure.
632 .It Fn pmap_getmaps
633 A user interface to the
634 .Xr rpcbind 8
635 service, which returns a list of the current RPC program-to-port
636 mappings on the host located at IP address
637 .Fa *addr .
638 This routine can return
639 .Dv NULL .
640 The command
641 .Dl Cm rpcinfo Fl p
642 uses this routine.
643 .It Fn pmap_getport
644 A user interface to the
645 .Xr rpcbind 8
646 service, which returns the port number
647 on which waits a service that supports program number
648 .Fa prognum ,
649 version
650 .Fa versnum ,
651 and speaks the transport protocol associated with
652 .Fa protocol .
653 The value of
654 .Fa protocol
655 is most likely
656 .Dv IPPROTO_UDP
657 or
658 .Dv IPPROTO_TCP .
659 A return value of zero means that the mapping does not exist
660 or that the RPC system failured to contact the remote
661 .Xr rpcbind 8
662 service.
663 In the latter case, the global variable
664 .Fn rpc_createerr
665 contains the RPC status.
666 .It Fn pmap_rmtcall
667 A user interface to the
668 .Xr rpcbind 8
669 service, which instructs
670 .Xr rpcbind 8
671 on the host at IP address
672 .Fa *addr
673 to make an RPC call on your behalf to a procedure on that host.
674 The parameter
675 .Fa *portp
676 will be modified to the program's port number if the
677 procedure succeeds.
678 The definitions of other parameters are discussed in
679 .Fn callrpc
680 and
681 .Fn clnt_call .
682 This procedure should be used for a
683 .Dq ping
684 and nothing else.
685 See also
686 .Fn clnt_broadcast .
687 .It Fn pmap_set
688 A user interface to the
689 .Xr rpcbind 8
690 service, which establishes a mapping between the triple
691 .Fa [ prognum ,
692 .Fa versnum ,
693 .Fa protocol ]
694 and
695 .Fa port
696 on the machine's
697 .Xr rpcbind 8
698 service.
699 The value of
700 .Fa protocol
701 is most likely
702 .Dv IPPROTO_UDP
703 or
704 .Dv IPPROTO_TCP .
705 This routine returns one if it succeeds, zero otherwise.
706 Automatically done by
707 .Fn svc_register .
708 .It Fn pmap_unset
709 A user interface to the
710 .Xr rpcbind 8
711 service, which destroys all mapping between the triple
712 .Fa [ prognum ,
713 .Fa versnum ,
714 .Fa * ]
715 and
716 .Fa ports
717 on the machine's
718 .Xr rpcbind 8
719 service.
720 This routine returns one if it succeeds, zero otherwise.
721 .It Fn registerrpc
722 Register procedure
723 .Fa procname
724 with the RPC service package.
725 If a request arrives for program
726 .Fa prognum ,
727 version
728 .Fa versnum ,
729 and procedure
730 .Fa procnum ,
731 .Fa procname
732 is called with a pointer to its parameter(s);
733 .Fa progname
734 should return a pointer to its static result(s);
735 .Fa inproc
736 is used to decode the parameters while
737 .Fa outproc
738 is used to encode the results.
739 This routine returns zero if the registration succeeded, \-1
740 otherwise.
741 .Pp
742 Warning: remote procedures registered in this form
743 are accessed using the UDP/IP transport; see
744 .Fn svcudp_bufcreate
745 for restrictions.
746 .It struct rpc_createerr rpc_createerr ;
747 A global variable whose value is set by any RPC
748 client creation routine that does not succeed.
749 Use the routine
750 .Fn clnt_pcreateerror
751 to print the reason why.
752 .It Fn svc_destroy
753 A macro that destroys the RPC service transport handle,
754 .Fa xprt .
755 Destruction usually involves deallocation
756 of private data structures, including
757 .Fa xprt
758 itself.
759 Use of
760 .Fa xprt
761 is undefined after calling this routine.
762 .It fd_set svc_fdset ;
763 A global variable reflecting the RPC service side's read file
764 descriptor bit mask; it is suitable as a parameter to the
765 .Xr select 2
766 system call.
767 This is only of interest if a service implementor does not call
768 .Fn svc_run ,
769 but rather does his own asynchronous event processing.
770 This variable is read-only (do not pass its address to
771 .Xr select 2 ! ) ,
772 yet it may change after calls to
773 .Fn svc_getreqset
774 or any creation routines.
775 .It int svc_fds;
776 Similar to
777 .Fn svc_fedset ,
778 but limited to 32 descriptors.
779 This interface is obsoleted by
780 .Fn svc_fdset .
781 .It Fn svc_freeargs
782 A macro that frees any data allocated by the RPC/XDR
783 system when it decoded the arguments to a service procedure using
784 .Fn svc_getargs .
785 This routine returns 1 if the results were successfully freed,
786 and zero otherwise.
787 .It Fn svc_getargs
788 A macro that decodes the arguments of an RPC request associated with
789 the RPC service transport handle,
790 .Fa xprt .
791 The parameter
792 .Fa in
793 is the address where the arguments will be placed;
794 .Fa inproc
795 is the XDR routine used to decode the arguments.
796 This routine returns one if decoding succeeds, and zero otherwise.
797 .It Fn svc_getcaller
798 The obsolete way of getting the network address of the caller
799 of a procedure associated with the RPC service transport handle,
800 .Fa xprt ,
801 use
802 .Fn svc_getrpccaller .
803 .It Fn svc_getreqset
804 This routine is only of interest if a service implementor
805 does not call
806 .Fn svc_run ,
807 but instead implements custom asynchronous event processing.
808 It is called when the
809 .Xr select 2
810 system call has determined that an RPC request has arrived on some
811 RPC socket(s) ;
812 .Fa rdfds
813 is the resultant read file descriptor bit mask.
814 The routine returns when all sockets associated with the
815 value of
816 .Fa rdfds
817 have been serviced.
818 .It Fn svc_getreq
819 Similar to
820 .Fn svc_getreqset ,
821 but limited to 32 descriptors.
822 This interface is obsoleted by
823 .Fn svc_getreqset .
824 .It Fn svc_getrpccaller
825 The approved way of getting the network address of the caller
826 of a procedure associated with the RPC service transport handle,
827 .Fa xprt .
828 .It Fn svc_register
829 Associates
830 .Fa prognum
831 and
832 .Fa versnum
833 with the service dispatch procedure,
834 .Fa dispatch .
835 If
836 .Fa protocol
837 is zero, the service is not registered with the
838 .Xr rpcbind 8
839 service.
840 If
841 .Fa protocol
842 is non-zero, then a mapping of the triple
843 .Fa [ prognum ,
844 .Fa versnum ,
845 .Fa protocol ]
846 to
847 .Fa xprt-\*[Gt]xp_port
848 is established with the local
849 .Xr rpcbind 8
850 service (generally
851 .Fa protocol
852 is zero,
853 .Dv IPPROTO_UDP
854 or
855 .Dv IPPROTO_TCP ) .
856 The procedure
857 .Fa dispatch
858 has the following form:
859 .Ft int
860 .Fn dispatch "struct svc_req *request" "SVCXPRT *xprt" .
861 .Pp
862 The
863 .Fn svc_register
864 routine returns one if it succeeds, and zero otherwise.
865 .It Fn svc_run
866 This routine never returns.
867 It waits for RPC requests to arrive, and calls the appropriate service
868 procedure using
869 .Fn svc_getreq
870 when one arrives.
871 This procedure is usually waiting for a
872 .Xr select 2
873 system call to return.
874 .It Fn svc_sendreply
875 Called by an RPC service's dispatch routine to send the results of a
876 remote procedure call.
877 The parameter
878 .Fa xprt
879 is the request's associated transport handle;
880 .Fa outproc
881 is the XDR routine which is used to encode the results; and
882 .Fa out
883 is the address of the results.
884 This routine returns one if it succeeds, zero otherwise.
885 .It Fn svc_unregister
886 Remove all mapping of the double
887 .Fa [ prognum ,
888 .Fa versnum ]
889 to dispatch routines, and of the triple
890 .Fa [ prognum ,
891 .Fa versnum ,
892 .Fa * ]
893 to port number.
894 .It Fn svcerr_auth
895 Called by a service dispatch routine that refuses to perform
896 a remote procedure call due to an authentication error.
897 .It Fn svcerr_decode
898 Called by a service dispatch routine that cannot successfully
899 decode its parameters.
900 See also
901 .Fn svc_getargs .
902 .It Fn svcerr_noproc
903 Called by a service dispatch routine that does not implement
904 the procedure number that the caller requests.
905 .It Fn svcerr_noprog
906 Called when the desired program is not registered with the RPC
907 package.
908 Service implementors usually do not need this routine.
909 .It Fn svcerr_progvers
910 Called when the desired version of a program is not registered
911 with the RPC package.
912 Service implementors usually do not need this routine.
913 .It Fn svcerr_systemerr
914 Called by a service dispatch routine when it detects a system error
915 not covered by any particular protocol.
916 For example, if a service can no longer allocate storage,
917 it may call this routine.
918 .It Fn svcerr_weakauth
919 Called by a service dispatch routine that refuses to perform
920 a remote procedure call due to insufficient
921 authentication parameters.
922 The routine calls
923 .Fn svcerr_auth "xprt" "AUTH_TOOWEAK" .
924 .It Fn svcraw_create
925 This routine creates a toy RPC service transport, to which it returns
926 a pointer.
927 The transport is really a buffer within the process's address space,
928 so the corresponding RPC client should live in the same address space;
929 see
930 .Fn clntraw_create .
931 This routine allows simulation of RPC and acquisition of RPC overheads
932 (such as round trip times), without any kernel interference.
933 This routine returns
934 .Dv NULL
935 if it fails.
936 .It Fn svctcp_create
937 This routine creates a TCP/IP-based RPC service transport, to which it
938 returns a pointer.
939 The transport is associated with the socket
940 .Fa sock ,
941 which may be
942 .Dv RPC_ANYSOCK ,
943 in which case a new socket is created.
944 If the socket is not bound to a local TCP
945 port, then this routine binds it to an arbitrary port.
946 Upon completion,
947 .Fa xprt-\*[Gt]xp_sock
948 is the transport's socket descriptor, and
949 .Fa xprt-\*[Gt]xp_port
950 is the transport's port number.
951 This routine returns
952 .Dv NULL
953 if it fails.
954 Since TCP-based RPC uses buffered I/O ,
955 users may specify the size of buffers; values of zero
956 choose suitable defaults.
957 .It Fn svcfd_create
958 Create a service on top of any open descriptor.
959 Typically, this descriptor is a connected socket
960 for a stream protocol such as TCP.
961 .Fa sendsize
962 and
963 .Fa recvsize
964 indicate sizes for the send and receive buffers.
965 If they are zero, a reasonable default is chosen.
966 .It Fn svcudp_bufcreate
967 This routine creates a UDP/IP-based RPC
968 service transport, to which it returns a pointer.
969 The transport is associated with the socket
970 .Fa sock ,
971 which may be
972 .Dv RPC_ANYSOCK ,
973 in which case a new socket is created.
974 If the socket is not bound to a local UDP
975 port, then this routine binds it to an arbitrary port.
976 Upon completion,
977 .Fa xprt-\*[Gt]xp_sock
978 is the transport's socket descriptor, and
979 .Fa xprt-\*[Gt]xp_port
980 is the transport's port number.
981 This routine returns
982 .Dv NULL
983 if it fails.
984 .Pp
985 This allows the user to specify the maximum packet size for sending and
986 receiving UDP-based RPC messages.
987 .It Fn svcudp_create
988 This acts as
989 .Fn svcudp_bufcreate with
990 predefined sizes for the maximum packet sizes.
991 .It Fn xdr_accepted_reply
992 Used for encoding RPC reply messages.
993 This routine is useful for users who wish to generate RPC-style
994 messages without using the RPC package.
995 .It Fn xdr_authunix_parms
996 Used for describing UNIX credentials.
997 This routine is useful for users who wish to generate these
998 credentials without using the RPC authentication package.
999 .It Fn xdr_callhdr
1000 Used for describing RPC call header messages.
1001 This routine is useful for users who wish to generate RPC-style
1002 messages without using the RPC package.
1003 .It Fn xdr_callmsg
1004 Used for describing RPC call messages.
1005 This routine is useful for users who wish to generate RPC-style
1006 messages without using the RPC package.
1007 .It Fn xdr_opaque_auth
1008 Used for describing RPC authentication information messages.
1009 This routine is useful for users who wish to generate RPC-style
1010 messages without using the RPC package.
1011 .It Fn xdr_pmap
1012 Used for describing parameters to various
1013 .Xr rpcbind 8
1014 procedures, externally.
1015 This routine is useful for users who wish to generate
1016 these parameters without using the
1017 .Em pmap
1018 interface.
1019 .It Fn xdr_pmaplist
1020 Used for describing a list of port mappings, externally.
1021 This routine is useful for users who wish to generate
1022 these parameters without using the
1023 .Em pmap
1024 interface.
1025 .It Fn xdr_rejected_reply
1026 Used for describing RPC reply messages.
1027 This routine is useful for users who wish to generate RPC-style
1028 messages without using the RPC package.
1029 .It Fn xdr_replymsg
1030 Used for describing RPC reply messages.
1031 This routine is useful for users who wish to generate RPC-style
1032 messages without using the RPC package.
1033 .It Fn xprt_register
1034 After RPC service transport handles are created,
1035 they should register themselves with the RPC service package.
1036 This routine modifies the global variable
1037 .Va svc_fds .
1038 Service implementors usually do not need this routine.
1039 .It Fn xprt_unregister
1040 Before an RPC service transport handle is destroyed,
1041 it should unregister itself with the RPC service package.
1042 This routine modifies the global variable
1043 .Va svc_fds .
1044 Service implementors usually do not need this routine.
1045 .El
1046 .Sh SEE ALSO
1047 .\".Xr rpc_secure 3 ,
1048 .Xr xdr 3
1049 .Pp
1050 The following manuals:
1051 .Rs
1052 .%B Remote Procedure Calls: Protocol Specification
1053 .Re
1054 .Rs
1055 .%B Remote Procedure Call Programming Guide
1056 .Re
1057 .Rs
1058 .%B rpcgen Programming Guide
1059 .Re
1060 .Pp
1061 .Rs
1062 .%A Sun Microsystems, Inc., USC-ISI
1063 .%T "RPC: Remote Procedure Call Protocol Specification"
1064 .%J RFC
1065 .%V 1050
1066 .Re