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 $
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" "u_int uid" "u_int gid" "int len" "u_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 "char *host" "u_long prog" "u_long vers" "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
398 .Vt "struct timeval" Ta "set total timeout"
399 .It Dv CLGET_TIMEOUT Ta
400 .Vt "struct timeval" Ta "get total timeout"
403 Note: if you set the timeout using
405 the timeout argument passed to
407 will be ignored in all future calls.
408 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
409 .It Dv CLGET_SERVER_ADDR Ta
410 .Vt "struct sockaddr_in" Ta "get server's address"
413 The following operations are valid for
416 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
417 .It Dv CLSET_RETRY_TIMEOUT Ta
418 .Vt "struct timeval" Ta "set the retry timeout"
419 .It Dv CLGET_RETRY_TIMEOUT Ta
420 .Vt "struct timeval" Ta "get the retry timeout"
423 The retry timeout is the time that
425 waits for the server to reply before
426 retransmitting the request.
430 .Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
433 A macro that frees any data allocated by the
435 system when it decoded the results of an
441 is the address of the results, and
445 routine describing the results.
446 This routine returns one if the results were successfully
454 .Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp"
457 A macro that copies the error structure out of the client
459 to the structure at address
466 .Fn clnt_pcreateerror "char *s"
469 prints a message to standard error indicating
472 handle could not be created.
473 The message is prepended with string
476 A newline is appended at the end of the message.
489 .Fn clnt_perrno "enum clnt_stat stat"
492 Print a message to standard error corresponding
493 to the condition indicated by
495 A newline is appended at the end of the message.
501 .Fn clnt_perror "CLIENT *clnt" "char *s"
504 Print a message to standard error indicating why an
508 is the handle used to do the call.
509 The message is prepended with string
512 A newline is appended at the end of the message.
520 .Fn clnt_spcreateerror "char *s"
524 .Fn clnt_pcreateerror ,
525 except that it returns a string
526 instead of printing to the standard error.
528 Bugs: returns pointer to static data that is overwritten
535 .Fn clnt_sperrno "enum clnt_stat stat"
538 Take the same arguments as
540 but instead of sending a message to the standard error
543 call failed, return a pointer to a string which contains
551 if the program does not have a standard error (as a program
552 running as a server quite likely does not), or if the
554 does not want the message to be output with
556 or if a message format different from that supported by
563 .Fn clnt_spcreateerror ,
565 returns pointer to static data, but the
566 result will not get overwritten on each call.
572 .Fn clnt_sperror "CLIENT *rpch" "char *s"
579 it returns a string instead of printing to standard error.
581 Bugs: returns pointer to static data that is overwritten
588 .Fn clntraw_create "u_long prognum" "u_long versnum"
591 This routine creates a toy
593 client for the remote program
597 The transport used to pass messages to the service is
598 actually a buffer within the process's address space, so the
601 server should live in the same address space; see
603 This allows simulation of
607 overheads, such as round trip times, without any
618 .Fa "struct sockaddr_in *addr"
627 This routine creates an
629 client for the remote program
636 The remote program is located at Internet
641 is zero, then it is set to the actual port that the remote
642 program is listening on (the remote
644 service is consulted for this information).
648 is a socket; if it is
650 then this routine opens a new one and sets
657 the user may specify the size of the send and receive buffers
663 values of zero choose suitable defaults.
673 .Fa "struct sockaddr_in *addr"
676 .Fa "struct timeval wait"
681 This routine creates an
683 client for the remote program
690 The remote program is located at Internet
695 is zero, then it is set to actual port that the remote
696 program is listening on (the remote
698 service is consulted for this information).
702 is a socket; if it is
704 then this routine opens a new one and sets
708 transport resends the call message in intervals of
710 time until a response is received or until the call times
712 The total time for the call to time out is specified by
718 messages can only hold up to 8 Kbytes
719 of encoded data, this transport cannot be used for procedures
720 that take large arguments or return huge results.
726 .Fo clntudp_bufcreate
727 .Fa "struct sockaddr_in *addr"
730 .Fa "struct timeval wait"
732 .Fa "unsigned int sendsize"
733 .Fa "unsigned int recosize"
737 This routine creates an
739 client for the remote program
746 The remote program is located at Internet
751 is zero, then it is set to actual port that the remote
752 program is listening on (the remote
754 service is consulted for this information).
758 is a socket; if it is
760 then this routine opens a new one and sets
764 transport resends the call message in intervals of
766 time until a response is received or until the call times
768 The total time for the call to time out is specified by
771 This allows the user to specify the maximum packet size
772 for sending and receiving
782 .Fa "struct sockaddr_un *raddr"
791 This routine creates an
800 sockets as a transport.
801 The local program is located at the
806 is a socket; if it is
808 then this routine opens a new one and sets
815 the user may specify the size of the send and receive buffers
821 values of zero choose suitable defaults.
830 .Fn get_myaddress "struct sockaddr_in *addr"
837 without consulting the library routines that deal with
839 The port number is always set to
841 Returns zero on success, non-zero on failure.
844 .Ft "struct pmaplist *"
847 .Fn pmap_getmaps "struct sockaddr_in *addr"
850 A user interface to the
852 service, which returns a list of the current
854 program\-to\-port mappings
855 on the host located at
859 This routine can return
870 .Fa "struct sockaddr_in *addr"
873 .Fa "u_long protocol"
877 A user interface to the
879 service, which returns the port number
880 on which waits a service that supports program number
884 and speaks the transport protocol associated with
892 A return value of zero means that the mapping does not exist
896 system failed to contact the remote
899 In the latter case, the global variable
910 .Fa "struct sockaddr_in *addr"
914 .Fa "xdrproc_t inproc"
916 .Fa "xdrproc_t outproc"
918 .Fa "struct timeval tout"
923 A user interface to the
925 service, which instructs
933 call on your behalf to a procedure on that host.
937 will be modified to the program's port number if the
940 The definitions of other arguments are discussed
945 This procedure should be used for a
954 .Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port"
957 A user interface to the
959 service, which establishes a mapping between the triple
960 .Pq Fa prognum , versnum , protocol
972 This routine returns one if it succeeds, zero otherwise.
973 Automatically done by
978 .Fn pmap_unset "u_long prognum" "u_long versnum"
981 A user interface to the
983 service, which destroys all mapping between the triple
984 .Pq Fa prognum , versnum , *
990 This routine returns one if it succeeds, zero
999 .Fa "char *(*procname)(void)"
1000 .Fa "xdrproc_t inproc"
1001 .Fa "xdrproc_t outproc"
1010 If a request arrives for program
1017 is called with a pointer to its argument(s);
1019 should return a pointer to its static result(s);
1021 is used to decode the arguments while
1023 is used to encode the results.
1024 This routine returns zero if the registration succeeded, \-1
1027 Warning: remote procedures registered in this form
1028 are accessed using the
1035 .Vt "struct rpc_createerr" rpc_createerr ;
1038 A global variable whose value is set by any
1040 client creation routine
1041 that does not succeed.
1043 .Fn clnt_pcreateerror
1044 to print the reason why.
1048 .Fn svc_destroy "SVCXPRT * xprt"
1051 A macro that destroys the
1053 service transport handle,
1055 Destruction usually involves deallocation
1056 of private data structures, including
1061 is undefined after calling this routine.
1064 .Vt fd_set svc_fdset ;
1067 A global variable reflecting the
1070 read file descriptor bit mask; it is suitable as a template argument
1074 This is only of interest
1075 if a service implementor does not call
1077 but rather does his own asynchronous event processing.
1078 This variable is read\-only (do not pass its address to
1080 yet it may change after calls to
1082 or any creation routines.
1083 As well, note that if the process has descriptor limits
1084 which are extended beyond
1086 this variable will only be usable for the first
1096 but limited to 32 descriptors.
1098 interface is obsoleted by
1103 .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
1106 A macro that frees any data allocated by the
1108 system when it decoded the arguments to a service procedure
1111 This routine returns 1 if the results were successfully
1117 .Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
1120 A macro that decodes the arguments of an
1125 service transport handle,
1130 is the address where the arguments will be placed;
1134 routine used to decode the arguments.
1135 This routine returns one if decoding succeeds, and zero
1139 .Ft "struct sockaddr_in *"
1142 .Fn svc_getcaller "SVCXPRT *xprt"
1145 The approved way of getting the network address of the caller
1146 of a procedure associated with the
1148 service transport handle,
1153 .Fn svc_getreqset "fd_set *rdfds"
1156 This routine is only of interest if a service implementor
1159 but instead implements custom asynchronous event processing.
1160 It is called when the
1162 system call has determined that an
1164 request has arrived on some
1168 is the resultant read file descriptor bit mask.
1169 The routine returns when all sockets associated with the
1176 .Fn svc_getreq "int rdfds"
1181 but limited to 32 descriptors.
1182 This interface is obsoleted by
1189 .Fa "u_long prognum"
1190 .Fa "u_long versnum"
1191 .Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)"
1200 with the service dispatch procedure,
1204 is zero, the service is not registered with the
1209 is non-zero, then a mapping of the triple
1210 .Pq Fa prognum , versnum , protocol
1213 is established with the local
1223 has the following form:
1224 .Bd -ragged -offset indent
1226 .Fn dispatch "struct svc_req *request" "SVCXPRT *xprt"
1231 routine returns one if it succeeds, and zero otherwise.
1237 This routine never returns.
1240 requests to arrive, and calls the appropriate service
1244 This procedure is usually waiting for a
1246 system call to return.
1250 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
1255 service's dispatch routine to send the results of a
1256 remote procedure call.
1260 is the request's associated transport handle;
1264 routine which is used to encode the results; and
1266 is the address of the results.
1267 This routine returns one if it succeeds, zero otherwise.
1273 .Fn svc_unregister "u_long prognum" "u_long versnum"
1276 Remove all mapping of the double
1277 .Pq Fa prognum , versnum
1278 to dispatch routines, and of the triple
1279 .Pq Fa prognum , versnum , *
1286 .Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
1289 Called by a service dispatch routine that refuses to perform
1290 a remote procedure call due to an authentication error.
1296 .Fn svcerr_decode "SVCXPRT *xprt"
1299 Called by a service dispatch routine that cannot successfully
1300 decode its arguments.
1308 .Fn svcerr_noproc "SVCXPRT *xprt"
1311 Called by a service dispatch routine that does not implement
1312 the procedure number that the caller requests.
1318 .Fn svcerr_noprog "SVCXPRT *xprt"
1321 Called when the desired program is not registered with the
1324 Service implementors usually do not need this routine.
1330 .Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
1333 Called when the desired version of a program is not registered
1337 Service implementors usually do not need this routine.
1343 .Fn svcerr_systemerr "SVCXPRT *xprt"
1346 Called by a service dispatch routine when it detects a system
1348 not covered by any particular protocol.
1349 For example, if a service can no longer allocate storage,
1350 it may call this routine.
1356 .Fn svcerr_weakauth "SVCXPRT *xprt"
1359 Called by a service dispatch routine that refuses to perform
1360 a remote procedure call due to insufficient
1361 authentication arguments.
1363 .Fn svcerr_auth xprt AUTH_TOOWEAK .
1369 .Fn svcraw_create void
1372 This routine creates a toy
1374 service transport, to which it returns a pointer.
1376 is really a buffer within the process's address space,
1377 so the corresponding
1379 client should live in the same
1382 .Fn clntraw_create .
1383 This routine allows simulation of
1387 overheads (such as round trip times), without any kernel
1389 This routine returns
1397 .Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size"
1400 This routine creates a
1401 .Tn TCP/IP Ns \-based
1403 service transport, to which it returns a pointer.
1404 The transport is associated with the socket
1408 in which case a new socket is created.
1409 If the socket is not bound to a local
1411 port, then this routine binds it to an arbitrary port.
1414 is the transport's socket descriptor, and
1416 is the transport's port number.
1417 This routine returns
1425 users may specify the size of buffers; values of zero
1426 choose suitable defaults.
1432 .Fn svcunix_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" "char *path"
1435 This routine creates a
1438 service transport, to which it returns a pointer.
1439 The transport is associated with the socket
1443 in which case a new socket is created.
1447 is a variable-length file system pathname of
1448 at most 104 characters.
1451 removed when the socket is closed.
1454 system call must be used to remove the file.
1457 is the transport's socket descriptor.
1458 This routine returns
1466 users may specify the size of buffers; values of zero
1467 choose suitable defaults.
1473 .Fn svcunixfd_create "int fd" "u_int sendsize" "u_int recvsize"
1476 Create a service on top of any open descriptor.
1482 indicate sizes for the send and receive buffers.
1484 zero, a reasonable default is chosen.
1490 .Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
1493 Create a service on top of any open descriptor.
1496 descriptor is a connected socket for a stream protocol such
1504 indicate sizes for the send and receive buffers.
1506 zero, a reasonable default is chosen.
1512 .Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize"
1515 This routine creates a
1516 .Tn UDP/IP Ns \-based
1518 service transport, to which it returns a pointer.
1519 The transport is associated with the socket
1523 in which case a new socket is created.
1524 If the socket is not bound to a local
1526 port, then this routine binds it to an arbitrary port.
1530 is the transport's socket descriptor, and
1532 is the transport's port number.
1533 This routine returns
1537 This allows the user to specify the maximum packet size for sending and
1545 .Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
1551 This routine is useful for users who
1554 messages without using the
1560 .Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
1566 This routine is useful for users
1567 who wish to generate these credentials without using the
1569 authentication package.
1576 .Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
1581 call header messages.
1582 This routine is useful for users who wish to generate
1584 messages without using the
1590 .Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
1596 This routine is useful for users who wish to generate
1598 messages without using the
1604 .Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
1609 authentication information messages.
1610 This routine is useful for users who wish to generate
1612 messages without using the
1621 .Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
1624 Used for describing arguments to various
1626 procedures, externally.
1627 This routine is useful for users who wish to generate
1628 these arguments without using the
1634 .Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
1637 Used for describing a list of port mappings, externally.
1638 This routine is useful for users who wish to generate
1639 these arguments without using the
1645 .Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
1651 This routine is useful for users who wish to generate
1653 messages without using the
1659 .Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
1665 This routine is useful for users who wish to generate
1667 style messages without using the
1675 .Fn xprt_register "SVCXPRT *xprt"
1680 service transport handles are created,
1681 they should register themselves with the
1684 This routine modifies the global variable
1686 Service implementors usually do not need this routine.
1692 .Fn xprt_unregister "SVCXPRT *xprt"
1697 service transport handle is destroyed,
1698 it should unregister itself with the
1701 This routine modifies the global variable
1703 Service implementors usually do not need this routine.
1709 .%T "Remote Procedure Calls: Protocol Specification"
1712 .%T "Remote Procedure Call Programming Guide"
1715 .%T "rpcgen Programming Guide"
1718 .%T "RPC: Remote Procedure Call Protocol Specification"
1720 .%Q "Sun Microsystems, Inc., USC-ISI"