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 $
9 .Nd "library routines for remote procedure calls"
17 for function declarations.
19 These routines allow C programs to make procedure
20 calls on other machines across the network.
21 First, the client calls a procedure to send a
22 data packet to the server.
23 Upon receipt of the packet, the server calls a dispatch routine
24 to perform the requested service, and then sends back a
26 Finally, the procedure call returns to the client.
28 Routines that are used for Secure
30 authentication) are described in
36 encryption is available.
37 .Bl -tag -width indent -compact
43 .Fn auth_destroy "AUTH *auth"
46 A macro that destroys the authentication information associated with
48 Destruction usually involves deallocation of private data
52 is undefined after calling
64 authentication handle that passes nonusable authentication
65 information with each remote procedure call.
67 default authentication used by
74 .Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids"
79 authentication handle that contains
81 authentication information.
84 is the name of the machine on which the information was
87 is the user's user ID;
89 is the user's current group ID;
93 refer to a counted array of groups to which the user belongs.
94 It is easy to impersonate a user.
100 .Fn authunix_create_default
105 with the appropriate parameters.
113 .Fa "xdrproc_t inproc"
115 .Fa "xdrproc_t outproc"
120 Call the remote procedure associated with
129 is the address of the procedure's argument(s), and
131 is the address of where to place the result(s);
133 is used to encode the procedure's parameters, and
135 is used to decode the procedure's results.
136 This routine returns zero if it succeeds, or the value of
138 cast to an integer if it fails.
141 is handy for translating failure statuses into messages.
143 Warning: calling remote procedures with this routine
149 You do not have control of timeouts or authentication using
160 .Fa "xdrproc_t inproc"
162 .Fa "xdrproc_t outproc"
164 .Fa "bool_t (*eachresult)(caddr_t, struct sockaddr_in *)
170 except the call message is broadcast to all locally
171 connected broadcast nets.
172 Each time it receives a
173 response, this routine calls
176 .Bd -ragged -offset indent
178 .Fn eachresult "caddr_t out" "struct sockaddr_in *addr"
187 except that the remote procedure's output is decoded there;
189 points to the address of the machine that sent the results.
194 waits for more replies; otherwise it returns with appropriate
197 Warning: broadcast sockets are limited in size to the
198 maximum transfer unit of the data link.
200 this value is 1500 bytes.
209 .Fa "xdrproc_t inproc"
211 .Fa "xdrproc_t outproc"
213 .Fa "struct timeval tout"
217 A macro that calls the remote procedure
219 associated with the client handle,
221 which is obtained with an
223 client creation routine such as
227 is the address of the procedure's argument(s), and
229 is the address of where to place the result(s);
231 is used to encode the procedure's parameters, and
233 is used to decode the procedure's results;
235 is the time allowed for results to come back.
239 .Fn clnt_destroy "CLIENT *clnt"
242 A macro that destroys the client's
245 Destruction usually involves deallocation
246 of private data structures, including
251 is undefined after calling
255 library opened the associated socket, it will close it also.
256 Otherwise, the socket remains open.
262 .Fn clnt_create "char *host" "u_long prog" "u_long vers" "char *proto"
265 Generic client creation routine.
267 identifies the name of the remote host where the server
270 indicates which kind of transport protocol to use.
272 currently supported values for this field are
276 Default timeouts are set, but can be modified using
281 has its shortcomings.
285 messages can only hold up to 8 Kbytes of encoded data,
286 this transport cannot be used for procedures that take
287 large arguments or return huge results.
293 .Fn clnt_control "CLIENT *cl" "u_int req" "char *info"
296 A macro used to change or retrieve various information
297 about a client object.
299 indicates the type of operation, and
301 is a pointer to the information.
306 the supported values of
308 and their argument types and what they do are:
309 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
310 .It Dv CLSET_TIMEOUT Ta Xo
311 .Vt "struct timeval" Ta "set total timeout"
313 .It Dv CLGET_TIMEOUT Ta Xo
314 .Vt "struct timeval" Ta "get total timeout"
318 Note: if you set the timeout using
320 the timeout parameter passed to
322 will be ignored in all future calls.
323 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
324 .It Dv CLGET_SERVER_ADDR Ta Xo
325 .Vt "struct sockaddr_in" Ta "get server's address"
329 The following operations are valid for
332 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
333 .It Dv CLSET_RETRY_TIMEOUT Ta Xo
334 .Vt "struct timeval" Ta "set the retry timeout"
336 .It Dv CLGET_RETRY_TIMEOUT Ta Xo
337 .Vt "struct timeval" Ta "get the retry timeout"
339 .It Dv CLSET_CONNECT Ta Vt "int" Ta use Xr connect 2
342 The retry timeout is the time that
344 waits for the server to reply before
345 retransmitting the request.
349 .Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
352 A macro that frees any data allocated by the
354 system when it decoded the results of an
359 is the address of the results, and
363 routine describing the results.
364 This routine returns one if the results were successfully
372 .Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp"
375 A macro that copies the error structure out of the client
377 to the structure at address
384 .Fn clnt_pcreateerror "char *s"
387 prints a message to standard error indicating
390 handle could not be created.
391 The message is prepended with string
406 .Fn clnt_perrno "enum clnt_stat stat"
409 Print a message to standard error corresponding
410 to the condition indicated by
417 .Fn clnt_perror "CLIENT *clnt" "char *s"
420 Print a message to standard error indicating why an
424 is the handle used to do the call.
425 The message is prepended with string
435 .Fn clnt_spcreateerror "char *s"
439 .Fn clnt_pcreateerror ,
440 except that it returns a string
441 instead of printing to the standard error.
443 Bugs: returns pointer to static data that is overwritten
450 .Fn clnt_sperrno "enum clnt_stat stat"
453 Take the same arguments as
455 but instead of sending a message to the standard error
458 call failed, return a pointer to a string which contains
460 The string ends with a newline
466 if the program does not have a standard error (as a program
467 running as a server quite likely does not), or if the
469 does not want the message to be output with
471 or if a message format different from that supported by
478 .Fn clnt_spcreaterror ,
480 returns pointer to static data, but the
481 result will not get overwritten on each call.
487 .Fn clnt_sperror "CLIENT *rpch" "char *s"
494 it returns a string instead of printing to standard error.
496 Bugs: returns pointer to static data that is overwritten
503 .Fn clntraw_create "u_long prognum" "u_long versnum"
506 This routine creates a toy
508 client for the remote program
512 The transport used to pass messages to the service is
513 actually a buffer within the process's address space, so the
516 server should live in the same address space; see
518 This allows simulation of
522 overheads, such as round trip times, without any
533 .Fa "struct sockaddr_in *addr"
542 This routine creates an
544 client for the remote program
551 The remote program is located at Internet
556 is zero, then it is set to the actual port that the remote
557 program is listening on (the remote
559 service is consulted for this information).
562 is a socket; if it is
564 then this routine opens a new one and sets
571 the user may specify the size of the send and receive buffers
576 values of zero choose suitable defaults.
586 .Fa "struct sockaddr_in *addr"
589 .Fa "struct timeval wait"
594 This routine creates an
596 client for the remote program
603 The remote program is located at Internet
608 is zero, then it is set to actual port that the remote
609 program is listening on (the remote
611 service is consulted for this information).
614 is a socket; if it is
616 then this routine opens a new one and sets
620 transport resends the call message in intervals of
622 time until a response is received or until the call times
624 The total time for the call to time out is specified by
630 messages can only hold up to 8 Kbytes
631 of encoded data, this transport cannot be used for procedures
632 that take large arguments or return huge results.
638 .Fo clntudp_bufcreate
639 .Fa "struct sockaddr_in *addr"
642 .Fa "struct timeval wait"
644 .Fa "unsigned int sendsize"
645 .Fa "unsigned int recosize"
649 This routine creates an
651 client for the remote program
658 The remote program is located at Internet
663 is zero, then it is set to actual port that the remote
664 program is listening on (the remote
666 service is consulted for this information).
669 is a socket; if it is
671 then this routine opens a new one and sets
675 transport resends the call message in intervals of
677 time until a response is received or until the call times
679 The total time for the call to time out is specified by
682 This allows the user to specify the maximum packet size
683 for sending and receiving
692 .Fn get_myaddress "struct sockaddr_in *addr"
699 without consulting the library routines that deal with
701 The port number is always set to
703 Returns zero on success, non-zero on failure.
706 .Ft "struct pmaplist *"
709 .Fn pmap_getmaps "struct sockaddr_in *addr"
712 A user interface to the
714 service, which returns a list of the current
716 program\-to\-port mappings
717 on the host located at
721 This routine can return
732 .Fa "struct sockaddr_in *addr"
735 .Fa "u_long protocol"
739 A user interface to the
741 service, which returns the port number
742 on which waits a service that supports program number
746 and speaks the transport protocol associated with
754 A return value of zero means that the mapping does not exist
758 system failed to contact the remote
761 In the latter case, the global variable
772 .Fa "struct sockaddr_in *addr"
776 .Fa "xdrproc_t inproc"
778 .Fa "xdrproc_t outproc"
780 .Fa "struct timeval tout"
785 A user interface to the
787 service, which instructs
795 call on your behalf to a procedure on that host.
798 will be modified to the program's port number if the
801 The definitions of other parameters are discussed
806 This procedure should be used for a
815 .Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port"
818 A user interface to the
820 service, which establishes a mapping between the triple
821 .Pq Fa prognum , versnum , protocol
833 This routine returns one if it succeeds, zero otherwise.
834 Automatically done by
839 .Fn pmap_unset "u_long prognum" "u_long versnum"
842 A user interface to the
844 service, which destroys all mapping between the triple
845 .Pq Fa prognum , versnum , *
851 This routine returns one if it succeeds, zero
860 .Fa "char *(*procname)(void)"
861 .Fa "xdrproc_t inproc"
862 .Fa "xdrproc_t outproc"
871 If a request arrives for program
878 is called with a pointer to its parameter(s);
880 should return a pointer to its static result(s);
882 is used to decode the parameters while
884 is used to encode the results.
885 This routine returns zero if the registration succeeded, \-1
888 Warning: remote procedures registered in this form
889 are accessed using the
896 .Vt "struct rpc_createerr" rpc_createerr ;
899 A global variable whose value is set by any
901 client creation routine
902 that does not succeed.
904 .Fn clnt_pcreateerror
905 to print the reason why.
909 .Fn svc_destroy "SVCXPRT * xprt"
912 A macro that destroys the
914 service transport handle,
916 Destruction usually involves deallocation
917 of private data structures, including
922 is undefined after calling this routine.
925 .Vt fd_set svc_fdset ;
928 A global variable reflecting the
931 read file descriptor bit mask; it is suitable as a template parameter
935 This is only of interest
936 if a service implementor does not call
938 but rather does his own asynchronous event processing.
939 This variable is read\-only (do not pass its address to
941 yet it may change after calls to
943 or any creation routines.
944 As well, note that if the process has descriptor limits
945 which are extended beyond
947 this variable will only be usable for the first
957 but limited to 32 descriptors.
959 interface is obsoleted by
964 .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
967 A macro that frees any data allocated by the
969 system when it decoded the arguments to a service procedure
972 This routine returns 1 if the results were successfully
978 .Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
981 A macro that decodes the arguments of an
986 service transport handle,
990 is the address where the arguments will be placed;
994 routine used to decode the arguments.
995 This routine returns one if decoding succeeds, and zero
999 .Ft "struct sockaddr_in *"
1002 .Fn svc_getcaller "SVCXPRT *xprt"
1005 The approved way of getting the network address of the caller
1006 of a procedure associated with the
1008 service transport handle,
1013 .Fn svc_getreqset "fd_set *rdfds"
1016 This routine is only of interest if a service implementor
1019 but instead implements custom asynchronous event processing.
1020 It is called when the
1022 system call has determined that an
1024 request has arrived on some
1028 is the resultant read file descriptor bit mask.
1029 The routine returns when all sockets associated with the
1036 .Fn svc_getreq "int rdfds"
1041 but limited to 32 descriptors.
1042 This interface is obsoleted by
1049 .Fa "u_long prognum"
1050 .Fa "u_long versnum"
1051 .Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)"
1060 with the service dispatch procedure,
1064 is zero, the service is not registered with the
1069 is non-zero, then a mapping of the triple
1070 .Pq Fa prognum , versnum , protocol
1073 is established with the local
1083 has the following form:
1084 .Bd -ragged -offset indent
1086 .Fn dispatch "struct svc_req *request" "SVCXPRT *xprt"
1091 routine returns one if it succeeds, and zero otherwise.
1097 This routine never returns.
1100 requests to arrive, and calls the appropriate service
1104 This procedure is usually waiting for a
1106 system call to return.
1110 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
1115 service's dispatch routine to send the results of a
1116 remote procedure call.
1119 is the request's associated transport handle;
1123 routine which is used to encode the results; and
1125 is the address of the results.
1126 This routine returns one if it succeeds, zero otherwise.
1132 .Fn svc_unregister "u_long prognum" "u_long versnum"
1135 Remove all mapping of the double
1136 .Pq Fa prognum , versnum
1137 to dispatch routines, and of the triple
1138 .Pq Fa prognum , versnum , *
1145 .Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
1148 Called by a service dispatch routine that refuses to perform
1149 a remote procedure call due to an authentication error.
1155 .Fn svcerr_decode "SVCXPRT *xprt"
1158 Called by a service dispatch routine that cannot successfully
1159 decode its parameters.
1167 .Fn svcerr_noproc "SVCXPRT *xprt"
1170 Called by a service dispatch routine that does not implement
1171 the procedure number that the caller requests.
1177 .Fn svcerr_noprog "SVCXPRT *xprt"
1180 Called when the desired program is not registered with the
1183 Service implementors usually do not need this routine.
1189 .Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
1192 Called when the desired version of a program is not registered
1196 Service implementors usually do not need this routine.
1202 .Fn svcerr_systemerr "SVCXPRT *xprt"
1205 Called by a service dispatch routine when it detects a system
1207 not covered by any particular protocol.
1208 For example, if a service can no longer allocate storage,
1209 it may call this routine.
1215 .Fn svcerr_weakauth "SVCXPRT *xprt"
1218 Called by a service dispatch routine that refuses to perform
1219 a remote procedure call due to insufficient
1220 authentication parameters.
1222 .Fn svcerr_auth xprt AUTH_TOOWEAK .
1228 .Fn svcraw_create void
1231 This routine creates a toy
1233 service transport, to which it returns a pointer.
1235 is really a buffer within the process's address space,
1236 so the corresponding
1238 client should live in the same
1241 .Fn clntraw_create .
1242 This routine allows simulation of
1246 overheads (such as round trip times), without any kernel
1248 This routine returns
1256 .Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size"
1259 This routine creates a
1260 .Tn TCP/IP Ns \-based
1262 service transport, to which it returns a pointer.
1263 The transport is associated with the socket
1267 in which case a new socket is created.
1268 If the socket is not bound to a local
1270 port, then this routine binds it to an arbitrary port.
1273 is the transport's socket descriptor, and
1275 is the transport's port number.
1276 This routine returns
1284 users may specify the size of buffers; values of zero
1285 choose suitable defaults.
1291 .Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
1294 Create a service on top of any open descriptor.
1297 descriptor is a connected socket for a stream protocol such
1303 indicate sizes for the send and receive buffers.
1305 zero, a reasonable default is chosen.
1311 .Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize"
1314 This routine creates a
1315 .Tn UDP/IP Ns \-based
1317 service transport, to which it returns a pointer.
1318 The transport is associated with the socket
1322 in which case a new socket is created.
1323 If the socket is not bound to a local
1325 port, then this routine binds it to an arbitrary port.
1329 is the transport's socket descriptor, and
1331 is the transport's port number.
1332 This routine returns
1336 This allows the user to specify the maximum packet size for sending and
1344 .Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
1350 This routine is useful for users who
1353 messages without using the
1359 .Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
1365 This routine is useful for users
1366 who wish to generate these credentials without using the
1368 authentication package.
1375 .Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
1380 call header messages.
1381 This routine is useful for users who wish to generate
1383 messages without using the
1389 .Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
1395 This routine is useful for users who wish to generate
1397 messages without using the
1403 .Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
1408 authentication information messages.
1409 This routine is useful for users who wish to generate
1411 messages without using the
1420 .Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
1423 Used for describing parameters to various
1425 procedures, externally.
1426 This routine is useful for users who wish to generate
1427 these parameters without using the
1433 .Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
1436 Used for describing a list of port mappings, externally.
1437 This routine is useful for users who wish to generate
1438 these parameters without using the
1444 .Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
1450 This routine is useful for users who wish to generate
1452 messages without using the
1458 .Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
1464 This routine is useful for users who wish to generate
1466 style messages without using the
1474 .Fn xprt_register "SVCXPRT *xprt"
1479 service transport handles are created,
1480 they should register themselves with the
1483 This routine modifies the global variable
1485 Service implementors usually do not need this routine.
1491 .Fn xprt_unregister "SVCXPRT *xprt"
1496 service transport handle is destroyed,
1497 it should unregister itself with the
1500 This routine modifies the global variable
1502 Service implementors usually do not need this routine.
1508 .%T "Remote Procedure Calls: Protocol Specification"
1511 .%T "Remote Procedure Call Programming Guide"
1514 .%T "rpcgen Programming Guide"
1517 .%T "RPC: Remote Procedure Call Protocol Specification"
1519 .%Q "Sun Microsystems, Inc., USC-ISI"