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.2.5 2001/12/14 18:33:56 ru Exp $
3 .\" $DragonFly: src/lib/libc/rpc/rpc.3,v 1.5 2006/10/26 16:50:42 swildner Exp $
10 .Nd "library routines for remote procedure calls"
18 for function declarations.
20 These routines allow C programs to make procedure
21 calls on other machines across the network.
22 First, the client calls a procedure to send a
23 data packet to the server.
24 Upon receipt of the packet, the server calls a dispatch routine
25 to perform the requested service, and then sends back a
27 Finally, the procedure call returns to the client.
29 Routines that are used for Secure
31 authentication) are described in
37 encryption is available.
38 .Bl -tag -width indent -compact
44 .Fn auth_destroy "AUTH *auth"
47 A macro that destroys the authentication information associated with
49 Destruction usually involves deallocation of private data
53 is undefined after calling
65 authentication handle that passes nonusable authentication
66 information with each remote procedure call.
68 default authentication used by
75 .Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids"
80 authentication handle that contains
82 authentication information.
85 is the name of the machine on which the information was
88 is the user's user ID;
90 is the user's current group ID;
94 refer to a counted array of groups to which the user belongs.
95 It is easy to impersonate a user.
101 .Fn authunix_create_default
106 with the appropriate parameters.
114 .Fa "xdrproc_t inproc"
116 .Fa "xdrproc_t outproc"
121 Call the remote procedure associated with
130 is the address of the procedure's argument(s), and
132 is the address of where to place the result(s);
134 is used to encode the procedure's parameters, and
136 is used to decode the procedure's results.
137 This routine returns zero if it succeeds, or the value of
139 cast to an integer if it fails.
142 is handy for translating failure statuses into messages.
144 Warning: calling remote procedures with this routine
150 You do not have control of timeouts or authentication using
161 .Fa "xdrproc_t inproc"
163 .Fa "xdrproc_t outproc"
165 .Fa "bool_t (*eachresult)(caddr_t, struct sockaddr_in *)
171 except the call message is broadcast to all locally
172 connected broadcast nets.
173 Each time it receives a
174 response, this routine calls
177 .Bd -ragged -offset indent
179 .Fn eachresult "caddr_t out" "struct sockaddr_in *addr"
188 except that the remote procedure's output is decoded there;
190 points to the address of the machine that sent the results.
195 waits for more replies; otherwise it returns with appropriate
198 Warning: broadcast sockets are limited in size to the
199 maximum transfer unit of the data link.
201 this value is 1500 bytes.
210 .Fa "xdrproc_t inproc"
212 .Fa "xdrproc_t outproc"
214 .Fa "struct timeval tout"
218 A macro that calls the remote procedure
220 associated with the client handle,
222 which is obtained with an
224 client creation routine such as
228 is the address of the procedure's argument(s), and
230 is the address of where to place the result(s);
232 is used to encode the procedure's parameters, and
234 is used to decode the procedure's results;
236 is the time allowed for results to come back.
240 .Fn clnt_destroy "CLIENT *clnt"
243 A macro that destroys the client's
246 Destruction usually involves deallocation
247 of private data structures, including
252 is undefined after calling
256 library opened the associated socket, it will close it also.
257 Otherwise, the socket remains open.
263 .Fn clnt_create "const char *host" "u_long prog" "u_long vers" "const char *proto"
266 Generic client creation routine.
268 identifies the name of the remote host where the server
271 indicates which kind of transport protocol to use.
273 currently supported values for this field are
277 Default timeouts are set, but can be modified using
282 has its shortcomings.
286 messages can only hold up to 8 Kbytes of encoded data,
287 this transport cannot be used for procedures that take
288 large arguments or return huge results.
294 .Fn clnt_control "CLIENT *cl" "u_int req" "char *info"
297 A macro used to change or retrieve various information
298 about a client object.
300 indicates the type of operation, and
302 is a pointer to the information.
307 the supported values of
309 and their argument types and what they do are:
310 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
311 .It Dv CLSET_TIMEOUT Ta Xo
312 .Vt "struct timeval" Ta "set total timeout"
314 .It Dv CLGET_TIMEOUT Ta Xo
315 .Vt "struct timeval" Ta "get total timeout"
319 Note: if you set the timeout using
321 the timeout parameter passed to
323 will be ignored in all future calls.
324 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
325 .It Dv CLGET_SERVER_ADDR Ta Xo
326 .Vt "struct sockaddr_in" Ta "get server's address"
330 The following operations are valid for
333 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
334 .It Dv CLSET_RETRY_TIMEOUT Ta Xo
335 .Vt "struct timeval" Ta "set the retry timeout"
337 .It Dv CLGET_RETRY_TIMEOUT Ta Xo
338 .Vt "struct timeval" Ta "get the retry timeout"
340 .It Dv CLSET_CONNECT Ta Vt "int" Ta use Xr connect 2
343 The retry timeout is the time that
345 waits for the server to reply before
346 retransmitting the request.
350 .Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
353 A macro that frees any data allocated by the
355 system when it decoded the results of an
360 is the address of the results, and
364 routine describing the results.
365 This routine returns one if the results were successfully
373 .Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp"
376 A macro that copies the error structure out of the client
378 to the structure at address
385 .Fn clnt_pcreateerror "const char *s"
388 prints a message to standard error indicating
391 handle could not be created.
392 The message is prepended with string
407 .Fn clnt_perrno "enum clnt_stat stat"
410 Print a message to standard error corresponding
411 to the condition indicated by
418 .Fn clnt_perror "CLIENT *clnt" "const char *s"
421 Print a message to standard error indicating why an
425 is the handle used to do the call.
426 The message is prepended with string
436 .Fn clnt_spcreateerror "const char *s"
440 .Fn clnt_pcreateerror ,
441 except that it returns a string
442 instead of printing to the standard error.
444 Bugs: returns pointer to static data that is overwritten
451 .Fn clnt_sperrno "enum clnt_stat stat"
454 Take the same arguments as
456 but instead of sending a message to the standard error
459 call failed, return a pointer to a string which contains
461 The string ends with a newline
467 if the program does not have a standard error (as a program
468 running as a server quite likely does not), or if the
470 does not want the message to be output with
472 or if a message format different from that supported by
479 .Fn clnt_spcreateerror ,
481 returns pointer to static data, but the
482 result will not get overwritten on each call.
488 .Fn clnt_sperror "CLIENT *rpch" "const char *s"
495 it returns a string instead of printing to standard error.
497 Bugs: returns pointer to static data that is overwritten
504 .Fn clntraw_create "u_long prognum" "u_long versnum"
507 This routine creates a toy
509 client for the remote program
513 The transport used to pass messages to the service is
514 actually a buffer within the process's address space, so the
517 server should live in the same address space; see
519 This allows simulation of
523 overheads, such as round trip times, without any
534 .Fa "struct sockaddr_in *addr"
543 This routine creates an
545 client for the remote program
552 The remote program is located at Internet
557 is zero, then it is set to the actual port that the remote
558 program is listening on (the remote
560 service is consulted for this information).
563 is a socket; if it is
565 then this routine opens a new one and sets
572 the user may specify the size of the send and receive buffers
577 values of zero choose suitable defaults.
587 .Fa "struct sockaddr_in *addr"
590 .Fa "struct timeval wait"
595 This routine creates an
597 client for the remote program
604 The remote program is located at Internet
609 is zero, then it is set to actual port that the remote
610 program is listening on (the remote
612 service is consulted for this information).
615 is a socket; if it is
617 then this routine opens a new one and sets
621 transport resends the call message in intervals of
623 time until a response is received or until the call times
625 The total time for the call to time out is specified by
631 messages can only hold up to 8 Kbytes
632 of encoded data, this transport cannot be used for procedures
633 that take large arguments or return huge results.
639 .Fo clntudp_bufcreate
640 .Fa "struct sockaddr_in *addr"
643 .Fa "struct timeval wait"
645 .Fa "unsigned int sendsize"
646 .Fa "unsigned int recosize"
650 This routine creates an
652 client for the remote program
659 The remote program is located at Internet
664 is zero, then it is set to actual port that the remote
665 program is listening on (the remote
667 service is consulted for this information).
670 is a socket; if it is
672 then this routine opens a new one and sets
676 transport resends the call message in intervals of
678 time until a response is received or until the call times
680 The total time for the call to time out is specified by
683 This allows the user to specify the maximum packet size
684 for sending and receiving
693 .Fn get_myaddress "struct sockaddr_in *addr"
700 without consulting the library routines that deal with
702 The port number is always set to
704 Returns zero on success, non-zero on failure.
707 .Ft "struct pmaplist *"
710 .Fn pmap_getmaps "struct sockaddr_in *addr"
713 A user interface to the
715 service, which returns a list of the current
717 program\-to\-port mappings
718 on the host located at
722 This routine can return
733 .Fa "struct sockaddr_in *addr"
736 .Fa "u_long protocol"
740 A user interface to the
742 service, which returns the port number
743 on which waits a service that supports program number
747 and speaks the transport protocol associated with
755 A return value of zero means that the mapping does not exist
759 system failed to contact the remote
762 In the latter case, the global variable
773 .Fa "struct sockaddr_in *addr"
777 .Fa "xdrproc_t inproc"
779 .Fa "xdrproc_t outproc"
781 .Fa "struct timeval tout"
786 A user interface to the
788 service, which instructs
796 call on your behalf to a procedure on that host.
799 will be modified to the program's port number if the
802 The definitions of other parameters are discussed
807 This procedure should be used for a
816 .Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port"
819 A user interface to the
821 service, which establishes a mapping between the triple
822 .Pq Fa prognum , versnum , protocol
834 This routine returns one if it succeeds, zero otherwise.
835 Automatically done by
840 .Fn pmap_unset "u_long prognum" "u_long versnum"
843 A user interface to the
845 service, which destroys all mapping between the triple
846 .Pq Fa prognum , versnum , *
852 This routine returns one if it succeeds, zero
861 .Fa "char *(*procname)(void)"
862 .Fa "xdrproc_t inproc"
863 .Fa "xdrproc_t outproc"
872 If a request arrives for program
879 is called with a pointer to its parameter(s);
881 should return a pointer to its static result(s);
883 is used to decode the parameters while
885 is used to encode the results.
886 This routine returns zero if the registration succeeded, \-1
889 Warning: remote procedures registered in this form
890 are accessed using the
897 .Vt "struct rpc_createerr" rpc_createerr ;
900 A global variable whose value is set by any
902 client creation routine
903 that does not succeed.
905 .Fn clnt_pcreateerror
906 to print the reason why.
910 .Fn svc_destroy "SVCXPRT * xprt"
913 A macro that destroys the
915 service transport handle,
917 Destruction usually involves deallocation
918 of private data structures, including
923 is undefined after calling this routine.
926 .Vt fd_set svc_fdset ;
929 A global variable reflecting the
932 read file descriptor bit mask; it is suitable as a template parameter
936 This is only of interest
937 if a service implementor does not call
939 but rather does his own asynchronous event processing.
940 This variable is read\-only (do not pass its address to
942 yet it may change after calls to
944 or any creation routines.
945 As well, note that if the process has descriptor limits
946 which are extended beyond
948 this variable will only be usable for the first
958 but limited to 32 descriptors.
960 interface is obsoleted by
965 .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
968 A macro that frees any data allocated by the
970 system when it decoded the arguments to a service procedure
973 This routine returns 1 if the results were successfully
979 .Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
982 A macro that decodes the arguments of an
987 service transport handle,
991 is the address where the arguments will be placed;
995 routine used to decode the arguments.
996 This routine returns one if decoding succeeds, and zero
1000 .Ft "struct sockaddr_in *"
1003 .Fn svc_getcaller "SVCXPRT *xprt"
1006 The approved way of getting the network address of the caller
1007 of a procedure associated with the
1009 service transport handle,
1014 .Fn svc_getreqset "fd_set *rdfds"
1017 This routine is only of interest if a service implementor
1020 but instead implements custom asynchronous event processing.
1021 It is called when the
1023 system call has determined that an
1025 request has arrived on some
1029 is the resultant read file descriptor bit mask.
1030 The routine returns when all sockets associated with the
1037 .Fn svc_getreq "int rdfds"
1042 but limited to 32 descriptors.
1043 This interface is obsoleted by
1050 .Fa "u_long prognum"
1051 .Fa "u_long versnum"
1052 .Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)"
1061 with the service dispatch procedure,
1065 is zero, the service is not registered with the
1070 is non-zero, then a mapping of the triple
1071 .Pq Fa prognum , versnum , protocol
1074 is established with the local
1084 has the following form:
1085 .Bd -ragged -offset indent
1087 .Fn dispatch "struct svc_req *request" "SVCXPRT *xprt"
1092 routine returns one if it succeeds, and zero otherwise.
1098 This routine never returns.
1101 requests to arrive, and calls the appropriate service
1105 This procedure is usually waiting for a
1107 system call to return.
1111 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
1116 service's dispatch routine to send the results of a
1117 remote procedure call.
1120 is the request's associated transport handle;
1124 routine which is used to encode the results; and
1126 is the address of the results.
1127 This routine returns one if it succeeds, zero otherwise.
1133 .Fn svc_unregister "u_long prognum" "u_long versnum"
1136 Remove all mapping of the double
1137 .Pq Fa prognum , versnum
1138 to dispatch routines, and of the triple
1139 .Pq Fa prognum , versnum , *
1146 .Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
1149 Called by a service dispatch routine that refuses to perform
1150 a remote procedure call due to an authentication error.
1156 .Fn svcerr_decode "SVCXPRT *xprt"
1159 Called by a service dispatch routine that cannot successfully
1160 decode its parameters.
1168 .Fn svcerr_noproc "SVCXPRT *xprt"
1171 Called by a service dispatch routine that does not implement
1172 the procedure number that the caller requests.
1178 .Fn svcerr_noprog "SVCXPRT *xprt"
1181 Called when the desired program is not registered with the
1184 Service implementors usually do not need this routine.
1190 .Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
1193 Called when the desired version of a program is not registered
1197 Service implementors usually do not need this routine.
1203 .Fn svcerr_systemerr "SVCXPRT *xprt"
1206 Called by a service dispatch routine when it detects a system
1208 not covered by any particular protocol.
1209 For example, if a service can no longer allocate storage,
1210 it may call this routine.
1216 .Fn svcerr_weakauth "SVCXPRT *xprt"
1219 Called by a service dispatch routine that refuses to perform
1220 a remote procedure call due to insufficient
1221 authentication parameters.
1223 .Fn svcerr_auth xprt AUTH_TOOWEAK .
1229 .Fn svcraw_create void
1232 This routine creates a toy
1234 service transport, to which it returns a pointer.
1236 is really a buffer within the process's address space,
1237 so the corresponding
1239 client should live in the same
1242 .Fn clntraw_create .
1243 This routine allows simulation of
1247 overheads (such as round trip times), without any kernel
1249 This routine returns
1257 .Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size"
1260 This routine creates a
1261 .Tn TCP/IP Ns \-based
1263 service transport, to which it returns a pointer.
1264 The transport is associated with the socket
1268 in which case a new socket is created.
1269 If the socket is not bound to a local
1271 port, then this routine binds it to an arbitrary port.
1274 is the transport's socket descriptor, and
1276 is the transport's port number.
1277 This routine returns
1285 users may specify the size of buffers; values of zero
1286 choose suitable defaults.
1292 .Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
1295 Create a service on top of any open descriptor.
1298 descriptor is a connected socket for a stream protocol such
1304 indicate sizes for the send and receive buffers.
1306 zero, a reasonable default is chosen.
1312 .Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize"
1315 This routine creates a
1316 .Tn UDP/IP Ns \-based
1318 service transport, to which it returns a pointer.
1319 The transport is associated with the socket
1323 in which case a new socket is created.
1324 If the socket is not bound to a local
1326 port, then this routine binds it to an arbitrary port.
1330 is the transport's socket descriptor, and
1332 is the transport's port number.
1333 This routine returns
1337 This allows the user to specify the maximum packet size for sending and
1345 .Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
1351 This routine is useful for users who
1354 messages without using the
1360 .Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
1366 This routine is useful for users
1367 who wish to generate these credentials without using the
1369 authentication package.
1376 .Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
1381 call header messages.
1382 This routine is useful for users who wish to generate
1384 messages without using the
1390 .Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
1396 This routine is useful for users who wish to generate
1398 messages without using the
1404 .Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
1409 authentication information messages.
1410 This routine is useful for users who wish to generate
1412 messages without using the
1421 .Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
1424 Used for describing parameters to various
1426 procedures, externally.
1427 This routine is useful for users who wish to generate
1428 these parameters without using the
1434 .Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
1437 Used for describing a list of port mappings, externally.
1438 This routine is useful for users who wish to generate
1439 these parameters without using the
1445 .Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
1451 This routine is useful for users who wish to generate
1453 messages without using the
1459 .Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
1465 This routine is useful for users who wish to generate
1467 style messages without using the
1475 .Fn xprt_register "SVCXPRT *xprt"
1480 service transport handles are created,
1481 they should register themselves with the
1484 This routine modifies the global variable
1486 Service implementors usually do not need this routine.
1492 .Fn xprt_unregister "SVCXPRT *xprt"
1497 service transport handle is destroyed,
1498 it should unregister itself with the
1501 This routine modifies the global variable
1503 Service implementors usually do not need this routine.
1509 .%T "Remote Procedure Calls: Protocol Specification"
1512 .%T "Remote Procedure Call Programming Guide"
1515 .%T "rpcgen Programming Guide"
1518 .%T "RPC: Remote Procedure Call Protocol Specification"
1520 .%Q "Sun Microsystems, Inc., USC-ISI"