| .\" @(#)rpc_clnt_calls.3n 1.30 93/08/31 SMI; from SVr4 |
| .\" Copyright 1989 AT&T |
| .\" @(#)rpc_clnt_calls 1.4 89/07/20 SMI; |
| .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. |
| .\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_calls.3,v 1.7 2002/12/19 09:40:23 ru Exp $ |
| .Dd May 7, 1993 |
| .Dt RPC_CLNT_CALLS 3 |
| .Os |
| .Sh NAME |
| .Nm rpc_clnt_calls , |
| .Nm clnt_call , |
| .Nm clnt_freeres , |
| .Nm clnt_geterr , |
| .Nm clnt_perrno , |
| .Nm clnt_perror , |
| .Nm clnt_sperrno , |
| .Nm clnt_sperror , |
| .Nm rpc_broadcast , |
| .Nm rpc_broadcast_exp , |
| .Nm rpc_call |
| .Nd library routines for client side calls |
| .Sh LIBRARY |
| .Lb libc |
| .Sh SYNOPSIS |
| .In rpc/rpc.h |
| .Ft "enum clnt_stat" |
| .Fn clnt_call "CLIENT *clnt" "const rpcproc_t procnum" "const xdrproc_t inproc" "const caddr_t in" "const xdrproc_t outproc" "caddr_t out" "const struct timeval tout" |
| .Ft bool_t |
| .Fn clnt_freeres "CLIENT *clnt" "const xdrproc_t outproc" "caddr_t out" |
| .Ft void |
| .Fn clnt_geterr "const CLIENT * clnt" "struct rpc_err * errp" |
| .Ft void |
| .Fn clnt_perrno "const enum clnt_stat stat" |
| .Ft void |
| .Fn clnt_perror "CLIENT *clnt" "const char *s" |
| .Ft "char *" |
| .Fn clnt_sperrno "const enum clnt_stat stat" |
| .Ft "char *" |
| .Fn clnt_sperror "CLIENT *clnt" "const char * s" |
| .Ft "enum clnt_stat" |
| .Fo rpc_broadcast |
| .Fa "const rpcprog_t prognum" "const rpcvers_t versnum" |
| .Fa "const rpcproc_t procnum" "const xdrproc_t inproc" |
| .Fa "const caddr_t in" "const xdrproc_t outproc" "caddr_t out" |
| .Fa "const resultproc_t eachresult" "const char *nettype" |
| .Fc |
| .Ft "enum clnt_stat" |
| .Fo rpc_broadcast_exp |
| .Fa "const rpcprog_t prognum" "const rpcvers_t versnum" |
| .Fa "const rpcproc_t procnum" "const xdrproc_t xargs" |
| .Fa "caddr_t argsp" "const xdrproc_t xresults" |
| .Fa "caddr_t resultsp" "const resultproc_t eachresult" |
| .Fa "const int inittime" "const int waittime" |
| .Fa "const char * nettype" |
| .Fc |
| .Ft "enum clnt_stat" |
| .Fo rpc_call |
| .Fa "const char *host" "const rpcprog_t prognum" |
| .Fa "const rpcvers_t versnum" "const rpcproc_t procnum" |
| .Fa "const xdrproc_t inproc" "const char *in" |
| .Fa "const xdrproc_t outproc" "char *out" "const char *nettype" |
| .Fc |
| .Sh DESCRIPTION |
| RPC library routines allow C language programs to make procedure |
| calls on other machines across the network. |
| First, the client calls a procedure to send a request to the server. |
| Upon receipt of the request, the server calls a dispatch routine |
| to perform the requested service, and then sends back a reply. |
| .Pp |
| The |
| .Fn clnt_call , |
| .Fn rpc_call , |
| and |
| .Fn rpc_broadcast |
| routines handle the client side of the procedure call. |
| The remaining routines deal with error handling in the case of errors. |
| .Pp |
| Some of the routines take a |
| .Vt CLIENT |
| handle as one of the arguments. |
| A |
| .Vt CLIENT |
| handle can be created by an RPC creation routine such as |
| .Fn clnt_create |
| (see |
| .Xr rpc_clnt_create 3 ) . |
| .Pp |
| These routines are safe for use in multithreaded applications. |
| .Vt CLIENT |
| handles can be shared between threads, however in this implementation |
| requests by different threads are serialized (that is, the first request will |
| receive its results before the second request is sent). |
| .Sh Routines |
| See |
| .Xr rpc 3 |
| for the definition of the |
| .Vt CLIENT |
| data structure. |
| .Bl -tag -width XXXXX |
| .It Fn clnt_call |
| A function macro that calls the remote procedure |
| .Fa procnum |
| associated with the client handle, |
| .Fa clnt , |
| which is obtained with an RPC |
| client creation routine such as |
| .Fn clnt_create |
| (see |
| .Xr rpc_clnt_create 3 ) . |
| The |
| .Fa inproc |
| argument |
| is the XDR function used to encode the procedure's arguments, and |
| .Fa outproc |
| is the XDR function used to decode the procedure's results; |
| .Fa in |
| is the address of the procedure's argument(s), and |
| .Fa out |
| is the address of where to place the result(s). |
| The |
| .Fa tout |
| argument |
| is the time allowed for results to be returned, which is overridden by |
| a time-out set explicitly through |
| .Fn clnt_control , |
| see |
| .Xr rpc_clnt_create 3 . |
| If the remote call succeeds, the status returned is |
| .Dv RPC_SUCCESS , |
| otherwise an appropriate status is returned. |
| .It Fn clnt_freeres |
| A function macro that frees any data allocated by the |
| RPC/XDR system when it decoded the results of an RPC call. |
| The |
| .Fa out |
| argument |
| is the address of the results, and |
| .Fa outproc |
| is the XDR routine describing the results. |
| This routine returns 1 if the results were successfully freed, |
| and 0 otherwise. |
| .It Fn clnt_geterr |
| A function macro that copies the error structure out of the client |
| handle to the structure at address |
| .Fa errp . |
| .It Fn clnt_perrno |
| Print a message to standard error corresponding |
| to the condition indicated by |
| .Fa stat . |
| A newline is appended. |
| Normally used after a procedure call fails for a routine |
| for which a client handle is not needed, for instance |
| .Fn rpc_call . |
| .It Fn clnt_perror |
| Print a message to the standard error indicating why an |
| RPC call failed; |
| .Fa clnt |
| is the handle used to do the call. |
| The message is prepended with string |
| .Fa s |
| and a colon. |
| A newline is appended. |
| Normally used after a remote procedure call fails |
| for a routine which requires a client handle, |
| for instance |
| .Fn clnt_call . |
| .It Fn clnt_sperrno |
| Take the same arguments as |
| .Fn clnt_perrno , |
| but instead of sending a message to the standard error |
| indicating why an RPC |
| call failed, return a pointer to a string which contains the message. |
| The |
| .Fn clnt_sperrno |
| function |
| is normally used instead of |
| .Fn clnt_perrno |
| when the program does not have a standard error (as a program |
| running as a server quite likely does not), or if the programmer |
| does not want the message to be output with |
| .Fn printf |
| (see |
| .Xr printf 3 ) , |
| or if a message format different than that supported by |
| .Fn clnt_perrno |
| is to be used. |
| Note: |
| unlike |
| .Fn clnt_sperror |
| and |
| .Fn clnt_spcreateerror |
| (see |
| .Xr rpc_clnt_create 3 ) , |
| .Fn clnt_sperrno |
| does not return pointer to static data so the |
| result will not get overwritten on each call. |
| .It Fn clnt_sperror |
| Like |
| .Fn clnt_perror , |
| except that (like |
| .Fn clnt_sperrno ) |
| it returns a string instead of printing to standard error. |
| However, |
| .Fn clnt_sperror |
| does not append a newline at the end of the message. |
| Warning: |
| returns pointer to a buffer that is overwritten |
| on each call. |
| .It Fn rpc_broadcast |
| Like |
| .Fn rpc_call , |
| except the call message is broadcast to |
| all the connectionless transports specified by |
| .Fa nettype . |
| If |
| .Fa nettype |
| is |
| .Dv NULL , |
| it defaults to |
| .Qq netpath . |
| Each time it receives a response, |
| this routine calls |
| .Fn eachresult , |
| whose form is: |
| .Ft bool_t |
| .Fn eachresult "caddr_t out" "const struct netbuf * addr" "const struct netconfig * netconf" |
| where |
| .Fa out |
| is the same as |
| .Fa out |
| passed to |
| .Fn rpc_broadcast , |
| except that the remote procedure's output is decoded there; |
| .Fa addr |
| points to the address of the machine that sent the results, and |
| .Fa netconf |
| is the netconfig structure of the transport on which the remote |
| server responded. |
| If |
| .Fn eachresult |
| returns 0, |
| .Fn rpc_broadcast |
| waits for more replies; |
| otherwise it returns with appropriate status. |
| Warning: |
| broadcast file descriptors are limited in size to the |
| maximum transfer size of that transport. |
| For Ethernet, this value is 1500 bytes. |
| The |
| .Fn rpc_broadcast |
| function |
| uses |
| .Dv AUTH_SYS |
| credentials by default (see |
| .Xr rpc_clnt_auth 3 ) . |
| .It Fn rpc_broadcast_exp |
| Like |
| .Fn rpc_broadcast , |
| except that the initial timeout, |
| .Fa inittime |
| and the maximum timeout, |
| .Fa waittime |
| are specified in milliseconds. |
| The |
| .Fa inittime |
| argument |
| is the initial time that |
| .Fn rpc_broadcast_exp |
| waits before resending the request. |
| After the first resend, the re-transmission interval |
| increases exponentially until it exceeds |
| .Fa waittime . |
| .It Fn rpc_call |
| Call the remote procedure associated with |
| .Fa prognum , |
| .Fa versnum , |
| and |
| .Fa procnum |
| on the machine, |
| .Fa host . |
| The |
| .Fa inproc |
| argument |
| is used to encode the procedure's arguments, and |
| .Fa outproc |
| is used to decode the procedure's results; |
| .Fa in |
| is the address of the procedure's argument(s), and |
| .Fa out |
| is the address of where to place the result(s). |
| The |
| .Fa nettype |
| argument |
| can be any of the values listed on |
| .Xr rpc 3 . |
| This routine returns |
| .Dv RPC_SUCCESS |
| if it succeeds, |
| or an appropriate status is returned. |
| Use the |
| .Fn clnt_perrno |
| routine to translate failure status into error messages. |
| Warning: |
| .Fn rpc_call |
| uses the first available transport belonging |
| to the class |
| .Fa nettype , |
| on which it can create a connection. |
| You do not have control of timeouts or authentication |
| using this routine. |
| .El |
| .Sh SEE ALSO |
| .Xr printf 3 , |
| .Xr rpc 3 , |
| .Xr rpc_clnt_auth 3 , |
| .Xr rpc_clnt_create 3 |