1rpc_clnt_calls(3NSL) Networking Services Library Functionsrpc_clnt_calls(3NSL)
2
3
4

NAME

6       rpc_clnt_calls,   clnt_call,   clnt_send,   clnt_freeres,  clnt_geterr,
7       clnt_perrno, clnt_perror,  clnt_sperrno,  clnt_sperror,  rpc_broadcast,
8       rpc_broadcast_exp, rpc_call - library routines for client side calls
9

SYNOPSIS

11       #include <rpc/rpc.h>
12
13       enum  clnt_stat clnt_call(CLIENT *clnt, const rpcproc_t procnum,
14            const xdrproc_t inproc, const caddr_t in, const xdrproc_t outproc,
15            caddr_t out, const struct timeval tout);
16
17
18       enum clnt_stat clnt_send (CLIENT *clnt, const u_long
19            procnum, const xdrproc_t proc, const caddr_t in);
20
21
22       bool_t clnt_freeres(CLIENT *clnt, const xdrproc_t outproc,
23            caddr_t out);
24
25
26       void clnt_geterr(const CLIENT *clnt, struct rpc_err *errp);
27
28
29       void clnt_perrno(const enum clnt_stat stat);
30
31
32       void clnt_perror(const CLIENT *clnt, const char *s);
33
34
35       char *clnt_sperrno(const enum clnt_stat stat);
36
37
38       char *clnt_sperror(const CLIENT *clnt, const char *s);
39
40
41       enum clnt_stat rpc_broadcast(const rpcprog_t prognum,
42            const rpcvers_t versnum, const rpcproc_t procnum,
43            const xdrproc_tinproc, const caddr_t in,
44            const xdrproc_t outproc, caddr_t out,
45            const resultproc_t eachresult, const char *nettype);
46
47
48       enum clnt_stat rpc_broadcast_exp(const rpcprog_t prognum,
49            const rpcvers_t versnum,const rpcproc_t procnum,
50            const xdrproc_txargs, caddr_t argsp, const xdrproc_txresults,
51            caddr_t resultsp, const resultproc_t eachresult, const int inittime,
52            const int waittime, const char *nettype);
53
54
55       enum clnt_stat rpc_call(const char *host, const rpcprog_t prognum,
56            const rpcvers_t versnum, const rpcproc_t procnum, const xdrproc_t inproc,
57            const char *in, const xdrproc_t outproc, char *out, const char *nettype);
58
59

DESCRIPTION

61       RPC library routines allow  C language programs to make procedure calls
62       on other machines across the network. First, the client calls a  proce‐
63       dure  to send a request to the server. Upon receipt of the request, the
64       server calls a dispatch routine to perform the  requested  service  and
65       then sends back a reply.
66
67
68       The  clnt_call(),  rpc_call(),  and rpc_broadcast() routines handle the
69       client side of the procedure call. The  remaining  routines  deal  with
70       error handling.
71
72
73       Some  of  the routines take a CLIENT handle as one of the parameters. A
74       CLIENT handle can be created  by  an   RPC  creation  routine  such  as
75       clnt_create(). See rpc_clnt_create(3NSL).
76
77
78       These  routines  are safe for use in multithreaded applications. CLIENT
79       handles can be shared between threads; however, in this  implementation
80       requests by different threads are serialized. In other words, the first
81       request will receive its results before the second request is sent.
82
83   Routines
84       See rpc(3NSL) for the definition of the CLIENT data structure.
85
86       clnt_call()            A function macro that calls the remote procedure
87                              procnum associated with the client handle, clnt,
88                              which is obtained with an  RPC  client  creation
89                              routine such as clnt_create(). See rpc_clnt_cre‐
90                              ate(3NSL). The  parameter  inproc  is  the   XDR
91                              function  used to encode the procedure's parame‐
92                              ters, and outproc is the  XDR function  used  to
93                              decode   the  procedure's  results.  in  is  the
94                              address of the procedure's argument(s), and  out
95                              is  the address of where to place the result(s).
96                              tout is the  time  allowed  for  results  to  be
97                              returned,  which is overridden by a time-out set
98                              explicitly    through    clnt_control().     See
99                              rpc_clnt_create(3NSL).
100
101                              If the remote call succeeds, the status returned
102                              is RPC_SUCCESS. Otherwise, an appropriate status
103                              is returned.
104
105
106       clnt_send()            Use  the  clnt_send()  function to call a remote
107                              asynchronous function.
108
109                              The clnt_send() function calls the remote  func‐
110                              tion  procnum()  associated with the client han‐
111                              dle, clnt, which is obtained with an RPC  client
112                              creation  routine  such  as  clnt_create().  See
113                              rpc_clnt_create(3NSL). The parameter proc is the
114                              XDR  function  used  to  encode  the procedure's
115                              parameters. The parameter in is the  address  of
116                              the procedure's argument(s).
117
118                              By  default,  the blocking I/O mode is used. See
119                              the clnt_control(3NSL) man page for more  infor‐
120                              mation on I/O modes.
121
122                              The  clnt_send()  function does not check if the
123                              program version number supplied to clnt_create()
124                              is  registered  with  the  rpcbind  service. Use
125                              clnt_create_vers() instead of  clnt_create()  to
126                              check  on incorrect version number registration.
127                              clnt_create_vers() will return a valid handle to
128                              the  client  only  if a version within the range
129                              supplied to clnt_create_vers() is  supported  by
130                              the server.
131
132                              RPC_SUCCESS  is  returned when a request is suc‐
133                              cessfully delivered to the transport layer. This
134                              does  not mean that the request was received. If
135                              an error is  returned,  use  the  clnt_getterr()
136                              routine  to  find  the  failure  status  or  the
137                              clnt_perrno() routine to translate  the  failure
138                              status into error messages.
139
140
141       clnt_freeres()         A  function  macro that frees any data allocated
142                              by  the  RPC/XDR  system  when  it  decoded  the
143                              results  of  an   RPC call. The parameter out is
144                              the address of the results, and outproc  is  the
145                              XDR routine describing the results. This routine
146                              returns  1  if  the  results  were  successfully
147                              freed; otherwise it returns 0.
148
149
150       clnt_geterr()          A function macro that copies the error structure
151                              out of the client handle  to  the  structure  at
152                              address errp.
153
154
155       clnt_perrno()          Prints a message to standard error corresponding
156                              to the condition indicated by stat. A newline is
157                              appended.  It is normally used after a procedure
158                              call fails for a routine for which a client han‐
159                              dle is not needed, for instance rpc_call()
160
161
162       clnt_perror()          Prints  a message to the standard error indicat‐
163                              ing why an RPC call failed; clnt is  the  handle
164                              used  to  do  the call. The message is prepended
165                              with  string  s  and  a  colon.  A  newline   is
166                              appended.  This routine is normally used after a
167                              remote procedure call fails for a  routine  that
168                              requires   a   client   handle,   for   instance
169                              clnt_call().
170
171
172       clnt_sperrno()         Takes the same arguments as  clnt_perrno(),  but
173                              instead  of  sending  a  message to the standard
174                              error indicating why an RPC call failed, returns
175                              a pointer to a string that contains the message.
176
177                              clnt_sperrno()   is  normally  used  instead  of
178                              clnt_perrno() when the program does not  have  a
179                              standard error, as a program running as a server
180                              quite likely does not.  clnt_sperrno()  is  also
181                              used if the programmer does not want the message
182                              to be output with printf(), or if a message for‐
183                              mat  different  than that supported by clnt_per‐
184                              rno() is to  be  used.  See  printf(3C).  Unlike
185                              clnt_sperror()      and     clnt_spcreaterror(),
186                              clnt_sperrno() does  not  return  a  pointer  to
187                              static  data. Therefore, the result is not over‐
188                              written on each call. See rpc_clnt_create(3NSL).
189
190
191       clnt_sperror()         Similar  to  clnt_perror(),  except  that   like
192                              clnt_sperrno(),  it  returns a string instead of
193                              printing to standard error. However,  clnt_sper‐
194                              ror()  does  not  append a newline at the end of
195                              the message.
196
197                              clnt_sperror() returns a  pointer  to  a  buffer
198                              that  is  overwritten  on  each  call. In multi‐
199                              threaded applications,  this  buffer  is  imple‐
200                              mented as thread-specific data.
201
202
203       rpc_broadcast()        Similar to rpc_call(), except that the call mes‐
204                              sage is  broadcast  to  all  the  connectionless
205                              transports  specified  by nettype. If nettype is
206                              NULL, it  defaults  to  netpath.  Each  time  it
207                              receives  a response, this routine calls eachre‐
208                              sult(), whose form is:
209
210                                bool_t eachresult(caddr_t out,  const struct netbuf *addr,
211                                const struct netconfig *netconf);
212
213                              where  out  is  the  same  as  out   passed   to
214                              rpc_broadcast(),  except  that the remote proce‐
215                              dure's output is decoded there. addr  points  to
216                              the   address  of  the  machine  that  sent  the
217                              results, and netconf is the netconfig  structure
218                              of  the  transport  on  which  the remote server
219                              responded. If eachresult() returns 0, rpc_broad‐
220                              cast()  waits  for  more  replies; otherwise, it
221                              returns with appropriate status.
222
223                              The broadcast file descriptors  are  limited  in
224                              size to the maximum transfer size of that trans‐
225                              port. For Ethernet, this value  is  1500  bytes.
226                              rpc_broadcast()  uses  AUTH_SYS  credentials  by
227                              default. See rpc_clnt_auth(3NSL).
228
229
230       rpc_broadcast_exp()    Similar to rpc_broadcast(), except that the ini‐
231                              tial  timeout, inittime and the maximum timeout,
232                              waittime, are specified in milliseconds.
233
234                              inittime is the  initial  time  that  rpc_broad‐
235                              cast_exp()  waits  before resending the request.
236                              After  the  first  resend,  the   retransmission
237                              interval   increases   exponentially   until  it
238                              exceeds waittime.
239
240
241       rpc_call()             Calls  the  remote  procedure  associated   with
242                              prognum,  versnum,  and  procnum on the machine,
243                              host. The parameter inproc is used to encode the
244                              procedure's  parameters,  and outproc is used to
245                              decode  the  procedure's  results.  in  is   the
246                              address  of the procedure's argument(s), and out
247                              is the address of where to place the  result(s).
248                              nettype  can  be  any  of  the  values listed on
249                              rpc(3NSL). This routine returns  RPC_SUCCESS  if
250                              it  succeeds,  or it returns an appropriate sta‐
251                              tus. Use the clnt_perrno() routine to  translate
252                              failure status into error messages.
253
254                              The rpc_call() function uses the first available
255                              transport belonging  to  the  class  nettype  on
256                              which  it  can  create  a connection. You do not
257                              have control of timeouts or authentication using
258                              this routine.
259
260

ATTRIBUTES

262       See attributes(5) for descriptions of the following attributes:
263
264
265
266
267       ┌─────────────────────────────┬─────────────────────────────┐
268       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
269       ├─────────────────────────────┼─────────────────────────────┤
270       │Architecture                 │All                          │
271       ├─────────────────────────────┼─────────────────────────────┤
272       │Availability                 │SUNWcsl (32-bit)             │
273       ├─────────────────────────────┼─────────────────────────────┤
274       │                             │SUNWcslx (64-bit)            │
275       ├─────────────────────────────┼─────────────────────────────┤
276       │Interface Stability          │Evolving                     │
277       ├─────────────────────────────┼─────────────────────────────┤
278       │MT-Level                     │MT-Safe                      │
279       └─────────────────────────────┴─────────────────────────────┘
280

SEE ALSO

282       printf(3C),   rpc(3NSL),   rpc_clnt_auth(3NSL),  rpc_clnt_create(3NSL),
283       attributes(5)
284
285
286
287SunOS 5.11                        1 Aug 2001              rpc_clnt_calls(3NSL)
Impressum