+++ /dev/null
-.\" @(#)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
projects / reactos.git / blobdiff