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.2 2000/06/07 13:39:43 simonb Exp $
3 .\" $FreeBSD: src/lib/libc/rpc/rpc_soc.3,v 1.12 2003/02/06 11:04:47 charnier Exp $
13 .Nm authunix_create_default ,
22 .Nm clnt_pcreateerror ,
25 .Nm clnt_spcreateerror ,
30 .Nm clntudp_bufcreate ,
57 .Nm svcerr_systemerr ,
60 .Nm svcunixfd_create ,
63 .Nm xdr_accepted_reply ,
64 .Nm xdr_authunix_parms ,
70 .Nm xdr_rejected_reply ,
74 .Nd "library routines for remote procedure calls"
82 for function declarations.
89 functions described in this page are the old, TS-RPC
90 interface to the XDR and RPC library, and exist for backward compatibility.
91 The new interface is described in the pages
96 These routines allow C programs to make procedure
97 calls on other machines across the network.
98 First, the client calls a procedure to send a
99 data packet to the server.
100 Upon receipt of the packet, the server calls a dispatch routine
101 to perform the requested service, and then sends back a
103 Finally, the procedure call returns to the client.
105 Routines that are used for Secure
107 authentication) are described in
113 encryption is available.
115 .Bl -tag -width indent -compact
120 .Fn auth_destroy "AUTH *auth"
123 A macro that destroys the authentication information associated with
125 Destruction usually involves deallocation of private data
129 is undefined after calling
141 authentication handle that passes nonusable authentication
142 information with each remote procedure call.
144 default authentication used by
151 .Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids"
156 authentication handle that contains
158 authentication information.
162 is the name of the machine on which the information was
165 is the user's user ID;
167 is the user's current group ID;
171 refer to a counted array of groups to which the user belongs.
172 It is easy to impersonate a user.
178 .Fn authunix_create_default
183 with the appropriate arguments.
192 .Fa "xdrproc_t inproc"
194 .Fa "xdrproc_t outproc"
199 Call the remote procedure associated with
209 is the address of the procedure's argument(s), and
211 is the address of where to place the result(s);
213 is used to encode the procedure's arguments, and
215 is used to decode the procedure's results.
216 This routine returns zero if it succeeds, or the value of
218 cast to an integer if it fails.
221 is handy for translating failure statuses into messages.
223 Warning: calling remote procedures with this routine
229 You do not have control of timeouts or authentication using
240 .Fa "xdrproc_t inproc"
242 .Fa "xdrproc_t outproc"
244 .Fa "bool_t (*eachresult)(caddr_t, struct sockaddr_in *)"
250 except the call message is broadcast to all locally
251 connected broadcast nets.
252 Each time it receives a
253 response, this routine calls
256 .Bd -ragged -offset indent
258 .Fn eachresult "caddr_t out" "struct sockaddr_in *addr"
267 except that the remote procedure's output is decoded there;
269 points to the address of the machine that sent the results.
274 waits for more replies; otherwise it returns with appropriate
277 Warning: broadcast sockets are limited in size to the
278 maximum transfer unit of the data link.
280 this value is 1500 bytes.
289 .Fa "xdrproc_t inproc"
291 .Fa "xdrproc_t outproc"
293 .Fa "struct timeval tout"
297 A macro that calls the remote procedure
299 associated with the client handle,
301 which is obtained with an
303 client creation routine such as
308 is the address of the procedure's argument(s), and
310 is the address of where to place the result(s);
312 is used to encode the procedure's arguments, and
314 is used to decode the procedure's results;
316 is the time allowed for results to come back.
320 .Fn clnt_destroy "CLIENT *clnt"
323 A macro that destroys the client's
326 Destruction usually involves deallocation
327 of private data structures, including
332 is undefined after calling
336 library opened the associated socket, it will close it also.
337 Otherwise, the socket remains open.
343 .Fn clnt_create "const char *host" "u_long prog" "u_long vers" "const char *proto"
346 Generic client creation routine.
350 identifies the name of the remote host where the server
355 indicates which kind of transport protocol to use.
357 currently supported values for this field are
361 Default timeouts are set, but can be modified using
366 has its shortcomings.
370 messages can only hold up to 8 Kbytes of encoded data,
371 this transport cannot be used for procedures that take
372 large arguments or return huge results.
378 .Fn clnt_control "CLIENT *cl" "u_int req" "char *info"
381 A macro used to change or retrieve various information
382 about a client object.
386 indicates the type of operation, and
388 is a pointer to the information.
393 the supported values of
395 and their argument types and what they do are:
396 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
397 .It Dv CLSET_TIMEOUT Ta Xo
398 .Vt "struct timeval" Ta "set total timeout"
400 .It Dv CLGET_TIMEOUT Ta Xo
401 .Vt "struct timeval" Ta "get total timeout"
405 Note: if you set the timeout using
407 the timeout argument passed to
409 will be ignored in all future calls.
410 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
411 .It Dv CLGET_SERVER_ADDR Ta Xo
412 .Vt "struct sockaddr_in" Ta "get server's address"
416 The following operations are valid for
419 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
420 .It Dv CLSET_RETRY_TIMEOUT Ta Xo
421 .Vt "struct timeval" Ta "set the retry timeout"
423 .It Dv CLGET_RETRY_TIMEOUT Ta Xo
424 .Vt "struct timeval" Ta "get the retry timeout"
428 The retry timeout is the time that
430 waits for the server to reply before
431 retransmitting the request.
435 .Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
438 A macro that frees any data allocated by the
440 system when it decoded the results of an
446 is the address of the results, and
450 routine describing the results.
451 This routine returns one if the results were successfully
459 .Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp"
462 A macro that copies the error structure out of the client
464 to the structure at address
471 .Fn clnt_pcreateerror "const char *s"
474 prints a message to standard error indicating
477 handle could not be created.
478 The message is prepended with string
481 A newline is appended at the end of the message.
494 .Fn clnt_perrno "enum clnt_stat stat"
497 Print a message to standard error corresponding
498 to the condition indicated by
500 A newline is appended at the end of the message.
506 .Fn clnt_perror "CLIENT *clnt" "const char *s"
509 Print a message to standard error indicating why an
513 is the handle used to do the call.
514 The message is prepended with string
517 A newline is appended at the end of the message.
525 .Fn clnt_spcreateerror "const char *s"
529 .Fn clnt_pcreateerror ,
530 except that it returns a string
531 instead of printing to the standard error.
533 Bugs: returns pointer to static data that is overwritten
540 .Fn clnt_sperrno "enum clnt_stat stat"
543 Take the same arguments as
545 but instead of sending a message to the standard error
548 call failed, return a pointer to a string which contains
556 if the program does not have a standard error (as a program
557 running as a server quite likely does not), or if the
559 does not want the message to be output with
561 or if a message format different from that supported by
568 .Fn clnt_spcreateerror ,
570 returns pointer to static data, but the
571 result will not get overwritten on each call.
577 .Fn clnt_sperror "CLIENT *rpch" "const char *s"
584 it returns a string instead of printing to standard error.
586 Bugs: returns pointer to static data that is overwritten
593 .Fn clntraw_create "u_long prognum" "u_long versnum"
596 This routine creates a toy
598 client for the remote program
602 The transport used to pass messages to the service is
603 actually a buffer within the process's address space, so the
606 server should live in the same address space; see
608 This allows simulation of
612 overheads, such as round trip times, without any
623 .Fa "struct sockaddr_in *addr"
632 This routine creates an
634 client for the remote program
641 The remote program is located at Internet
646 is zero, then it is set to the actual port that the remote
647 program is listening on (the remote
649 service is consulted for this information).
653 is a socket; if it is
655 then this routine opens a new one and sets
662 the user may specify the size of the send and receive buffers
668 values of zero choose suitable defaults.
678 .Fa "struct sockaddr_in *addr"
681 .Fa "struct timeval wait"
686 This routine creates an
688 client for the remote program
695 The remote program is located at Internet
700 is zero, then it is set to actual port that the remote
701 program is listening on (the remote
703 service is consulted for this information).
707 is a socket; if it is
709 then this routine opens a new one and sets
713 transport resends the call message in intervals of
715 time until a response is received or until the call times
717 The total time for the call to time out is specified by
723 messages can only hold up to 8 Kbytes
724 of encoded data, this transport cannot be used for procedures
725 that take large arguments or return huge results.
731 .Fo clntudp_bufcreate
732 .Fa "struct sockaddr_in *addr"
735 .Fa "struct timeval wait"
737 .Fa "unsigned int sendsize"
738 .Fa "unsigned int recosize"
742 This routine creates an
744 client for the remote program
751 The remote program is located at Internet
756 is zero, then it is set to actual port that the remote
757 program is listening on (the remote
759 service is consulted for this information).
763 is a socket; if it is
765 then this routine opens a new one and sets
769 transport resends the call message in intervals of
771 time until a response is received or until the call times
773 The total time for the call to time out is specified by
776 This allows the user to specify the maximum packet size
777 for sending and receiving
787 .Fa "struct sockaddr_un *raddr"
796 This routine creates an
805 sockets as a transport.
806 The local program is located at the
811 is a socket; if it is
813 then this routine opens a new one and sets
820 the user may specify the size of the send and receive buffers
826 values of zero choose suitable defaults.
835 .Fn get_myaddress "struct sockaddr_in *addr"
842 without consulting the library routines that deal with
844 The port number is always set to
846 Returns zero on success, non-zero on failure.
849 .Ft "struct pmaplist *"
852 .Fn pmap_getmaps "struct sockaddr_in *addr"
855 A user interface to the
857 service, which returns a list of the current
859 program\-to\-port mappings
860 on the host located at
864 This routine can return
875 .Fa "struct sockaddr_in *addr"
878 .Fa "u_long protocol"
882 A user interface to the
884 service, which returns the port number
885 on which waits a service that supports program number
889 and speaks the transport protocol associated with
897 A return value of zero means that the mapping does not exist
901 system failed to contact the remote
904 In the latter case, the global variable
915 .Fa "struct sockaddr_in *addr"
919 .Fa "xdrproc_t inproc"
921 .Fa "xdrproc_t outproc"
923 .Fa "struct timeval tout"
928 A user interface to the
930 service, which instructs
938 call on your behalf to a procedure on that host.
942 will be modified to the program's port number if the
945 The definitions of other arguments are discussed
950 This procedure should be used for a
959 .Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port"
962 A user interface to the
964 service, which establishes a mapping between the triple
965 .Pq Fa prognum , versnum , protocol
977 This routine returns one if it succeeds, zero otherwise.
978 Automatically done by
983 .Fn pmap_unset "u_long prognum" "u_long versnum"
986 A user interface to the
988 service, which destroys all mapping between the triple
989 .Pq Fa prognum , versnum , *
995 This routine returns one if it succeeds, zero
1001 .Fa "u_long prognum"
1002 .Fa "u_long versnum"
1003 .Fa "u_long procnum"
1004 .Fa "char *(*procname)(void)"
1005 .Fa "xdrproc_t inproc"
1006 .Fa "xdrproc_t outproc"
1015 If a request arrives for program
1022 is called with a pointer to its argument(s);
1024 should return a pointer to its static result(s);
1026 is used to decode the arguments while
1028 is used to encode the results.
1029 This routine returns zero if the registration succeeded, \-1
1032 Warning: remote procedures registered in this form
1033 are accessed using the
1040 .Vt "struct rpc_createerr" rpc_createerr ;
1043 A global variable whose value is set by any
1045 client creation routine
1046 that does not succeed.
1048 .Fn clnt_pcreateerror
1049 to print the reason why.
1053 .Fn svc_destroy "SVCXPRT * xprt"
1056 A macro that destroys the
1058 service transport handle,
1060 Destruction usually involves deallocation
1061 of private data structures, including
1066 is undefined after calling this routine.
1069 .Vt fd_set svc_fdset ;
1072 A global variable reflecting the
1075 read file descriptor bit mask; it is suitable as a template argument
1079 This is only of interest
1080 if a service implementor does not call
1082 but rather does his own asynchronous event processing.
1083 This variable is read\-only (do not pass its address to
1085 yet it may change after calls to
1087 or any creation routines.
1088 As well, note that if the process has descriptor limits
1089 which are extended beyond
1091 this variable will only be usable for the first
1101 but limited to 32 descriptors.
1103 interface is obsoleted by
1108 .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
1111 A macro that frees any data allocated by the
1113 system when it decoded the arguments to a service procedure
1116 This routine returns 1 if the results were successfully
1122 .Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
1125 A macro that decodes the arguments of an
1130 service transport handle,
1135 is the address where the arguments will be placed;
1139 routine used to decode the arguments.
1140 This routine returns one if decoding succeeds, and zero
1144 .Ft "struct sockaddr_in *"
1147 .Fn svc_getcaller "SVCXPRT *xprt"
1150 The approved way of getting the network address of the caller
1151 of a procedure associated with the
1153 service transport handle,
1158 .Fn svc_getreqset "fd_set *rdfds"
1161 This routine is only of interest if a service implementor
1164 but instead implements custom asynchronous event processing.
1165 It is called when the
1167 system call has determined that an
1169 request has arrived on some
1173 is the resultant read file descriptor bit mask.
1174 The routine returns when all sockets associated with the
1181 .Fn svc_getreq "int rdfds"
1186 but limited to 32 descriptors.
1187 This interface is obsoleted by
1194 .Fa "u_long prognum"
1195 .Fa "u_long versnum"
1196 .Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)"
1205 with the service dispatch procedure,
1209 is zero, the service is not registered with the
1214 is non-zero, then a mapping of the triple
1215 .Pq Fa prognum , versnum , protocol
1218 is established with the local
1228 has the following form:
1229 .Bd -ragged -offset indent
1231 .Fn dispatch "struct svc_req *request" "SVCXPRT *xprt"
1236 routine returns one if it succeeds, and zero otherwise.
1242 This routine never returns.
1245 requests to arrive, and calls the appropriate service
1249 This procedure is usually waiting for a
1251 system call to return.
1255 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
1260 service's dispatch routine to send the results of a
1261 remote procedure call.
1265 is the request's associated transport handle;
1269 routine which is used to encode the results; and
1271 is the address of the results.
1272 This routine returns one if it succeeds, zero otherwise.
1278 .Fn svc_unregister "u_long prognum" "u_long versnum"
1281 Remove all mapping of the double
1282 .Pq Fa prognum , versnum
1283 to dispatch routines, and of the triple
1284 .Pq Fa prognum , versnum , *
1291 .Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
1294 Called by a service dispatch routine that refuses to perform
1295 a remote procedure call due to an authentication error.
1301 .Fn svcerr_decode "SVCXPRT *xprt"
1304 Called by a service dispatch routine that cannot successfully
1305 decode its arguments.
1313 .Fn svcerr_noproc "SVCXPRT *xprt"
1316 Called by a service dispatch routine that does not implement
1317 the procedure number that the caller requests.
1323 .Fn svcerr_noprog "SVCXPRT *xprt"
1326 Called when the desired program is not registered with the
1329 Service implementors usually do not need this routine.
1335 .Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
1338 Called when the desired version of a program is not registered
1342 Service implementors usually do not need this routine.
1348 .Fn svcerr_systemerr "SVCXPRT *xprt"
1351 Called by a service dispatch routine when it detects a system
1353 not covered by any particular protocol.
1354 For example, if a service can no longer allocate storage,
1355 it may call this routine.
1361 .Fn svcerr_weakauth "SVCXPRT *xprt"
1364 Called by a service dispatch routine that refuses to perform
1365 a remote procedure call due to insufficient
1366 authentication arguments.
1368 .Fn svcerr_auth xprt AUTH_TOOWEAK .
1374 .Fn svcraw_create void
1377 This routine creates a toy
1379 service transport, to which it returns a pointer.
1381 is really a buffer within the process's address space,
1382 so the corresponding
1384 client should live in the same
1387 .Fn clntraw_create .
1388 This routine allows simulation of
1392 overheads (such as round trip times), without any kernel
1394 This routine returns
1402 .Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size"
1405 This routine creates a
1406 .Tn TCP/IP Ns \-based
1408 service transport, to which it returns a pointer.
1409 The transport is associated with the socket
1413 in which case a new socket is created.
1414 If the socket is not bound to a local
1416 port, then this routine binds it to an arbitrary port.
1419 is the transport's socket descriptor, and
1421 is the transport's port number.
1422 This routine returns
1430 users may specify the size of buffers; values of zero
1431 choose suitable defaults.
1437 .Fn svcunix_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" "char *path"
1440 This routine creates a
1443 service transport, to which it returns a pointer.
1444 The transport is associated with the socket
1448 in which case a new socket is created.
1452 is a variable-length file system pathname of
1453 at most 104 characters.
1456 removed when the socket is closed.
1459 system call must be used to remove the file.
1462 is the transport's socket descriptor.
1463 This routine returns
1471 users may specify the size of buffers; values of zero
1472 choose suitable defaults.
1478 .Fn svcunixfd_create "int fd" "u_int sendsize" "u_int recvsize"
1481 Create a service on top of any open descriptor.
1487 indicate sizes for the send and receive buffers.
1489 zero, a reasonable default is chosen.
1495 .Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
1498 Create a service on top of any open descriptor.
1501 descriptor is a connected socket for a stream protocol such
1509 indicate sizes for the send and receive buffers.
1511 zero, a reasonable default is chosen.
1517 .Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize"
1520 This routine creates a
1521 .Tn UDP/IP Ns \-based
1523 service transport, to which it returns a pointer.
1524 The transport is associated with the socket
1528 in which case a new socket is created.
1529 If the socket is not bound to a local
1531 port, then this routine binds it to an arbitrary port.
1535 is the transport's socket descriptor, and
1537 is the transport's port number.
1538 This routine returns
1542 This allows the user to specify the maximum packet size for sending and
1550 .Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
1556 This routine is useful for users who
1559 messages without using the
1565 .Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
1571 This routine is useful for users
1572 who wish to generate these credentials without using the
1574 authentication package.
1581 .Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
1586 call header messages.
1587 This routine is useful for users who wish to generate
1589 messages without using the
1595 .Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
1601 This routine is useful for users who wish to generate
1603 messages without using the
1609 .Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
1614 authentication information messages.
1615 This routine is useful for users who wish to generate
1617 messages without using the
1626 .Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
1629 Used for describing arguments to various
1631 procedures, externally.
1632 This routine is useful for users who wish to generate
1633 these arguments without using the
1639 .Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
1642 Used for describing a list of port mappings, externally.
1643 This routine is useful for users who wish to generate
1644 these arguments without using the
1650 .Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
1656 This routine is useful for users who wish to generate
1658 messages without using the
1664 .Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
1670 This routine is useful for users who wish to generate
1672 style messages without using the
1680 .Fn xprt_register "SVCXPRT *xprt"
1685 service transport handles are created,
1686 they should register themselves with the
1689 This routine modifies the global variable
1691 Service implementors usually do not need this routine.
1697 .Fn xprt_unregister "SVCXPRT *xprt"
1702 service transport handle is destroyed,
1703 it should unregister itself with the
1706 This routine modifies the global variable
1708 Service implementors usually do not need this routine.
1714 .%T "Remote Procedure Calls: Protocol Specification"
1717 .%T "Remote Procedure Call Programming Guide"
1720 .%T "rpcgen Programming Guide"
1723 .%T "RPC: Remote Procedure Call Protocol Specification"
1725 .%Q "Sun Microsystems, Inc., USC-ISI"