1/*	$NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $	*/
  2
  3/*-
  4 * SPDX-License-Identifier: BSD-3-Clause
  5 *
  6 * Copyright (c) 2010, Oracle America, Inc.
  7 * All rights reserved.
  8 *
  9 * Redistribution and use in source and binary forms, with or without
 10 * modification, are permitted provided that the following conditions are met:
 11 * - Redistributions of source code must retain the above copyright notice,
 12 *   this list of conditions and the following disclaimer.
 13 * - Redistributions in binary form must reproduce the above copyright notice,
 14 *   this list of conditions and the following disclaimer in the documentation
 15 *   and/or other materials provided with the distribution.
 16 * - Neither the name of the "Oracle America, Inc." nor the names of its
 17 *   contributors may be used to endorse or promote products derived
 18 *   from this software without specific prior written permission.
 19 *
 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 30 * POSSIBILITY OF SUCH DAMAGE.
 31 *
 32 *	from: @(#)clnt.h 1.31 94/04/29 SMI
 33 *	from: @(#)clnt.h	2.1 88/07/29 4.0 RPCSRC
 34 */
 35
 36/*
 37 * clnt.h - Client side remote procedure call interface.
 38 */
 39
 40#ifndef _RPC_CLNT_H_
 41#define _RPC_CLNT_H_
 42#include <rpc/clnt_stat.h>
 43#include <sys/cdefs.h>
 44#include <netconfig.h>
 45#include <sys/un.h>
 46
 47/*
 48 * Well-known IPV6 RPC broadcast address.
 49 */
 50#define RPCB_MULTICAST_ADDR "ff02::202"
 51
 52/*
 53 * the following errors are in general unrecoverable.  The caller
 54 * should give up rather than retry.
 55 */
 56#define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
 57	((s) == RPC_CANTENCODEARGS) || \
 58	((s) == RPC_CANTDECODERES) || \
 59	((s) == RPC_VERSMISMATCH) || \
 60	((s) == RPC_PROCUNAVAIL) || \
 61	((s) == RPC_PROGUNAVAIL) || \
 62	((s) == RPC_PROGVERSMISMATCH) || \
 63	((s) == RPC_CANTDECODEARGS))
 64
 65/*
 66 * Error info.
 67 */
 68struct rpc_err {
 69	enum clnt_stat re_status;
 70	union {
 71		int RE_errno;		/* related system error */
 72		enum auth_stat RE_why;	/* why the auth error occurred */
 73		struct {
 74			rpcvers_t low;	/* lowest version supported */
 75			rpcvers_t high;	/* highest version supported */
 76		} RE_vers;
 77		struct {		/* maybe meaningful if RPC_FAILED */
 78			int32_t s1;
 79			int32_t s2;
 80		} RE_lb;		/* life boot & debugging only */
 81	} ru;
 82#define	re_errno	ru.RE_errno
 83#define	re_why		ru.RE_why
 84#define	re_vers		ru.RE_vers
 85#define	re_lb		ru.RE_lb
 86};
 87
 88
 89/*
 90 * Client rpc handle.
 91 * Created by individual implementations
 92 * Client is responsible for initializing auth, see e.g. auth_none.c.
 93 */
 94typedef struct __rpc_client {
 95	AUTH	*cl_auth;			/* authenticator */
 96	struct clnt_ops {
 97		/* call remote procedure */
 98		enum clnt_stat	(*cl_call)(struct __rpc_client *,
 99				    rpcproc_t, xdrproc_t, void *, xdrproc_t,
100				        void *, struct timeval);
101		/* abort a call */
102		void		(*cl_abort)(struct __rpc_client *);
103		/* get specific error code */
104		void		(*cl_geterr)(struct __rpc_client *,
105					struct rpc_err *);
106		/* frees results */
107		bool_t		(*cl_freeres)(struct __rpc_client *,
108					xdrproc_t, void *);
109		/* destroy this structure */
110		void		(*cl_destroy)(struct __rpc_client *);
111		/* the ioctl() of rpc */
112		bool_t          (*cl_control)(struct __rpc_client *, u_int,
113				    void *);
114	} *cl_ops;
115	void 			*cl_private;	/* private stuff */
116	char			*cl_netid;	/* network token */
117	char			*cl_tp;		/* device name */
118} CLIENT;
119
120
121/*
122 * Timers used for the pseudo-transport protocol when using datagrams
123 */
124struct rpc_timers {
125	u_short		rt_srtt;	/* smoothed round-trip time */
126	u_short		rt_deviate;	/* estimated deviation */
127	u_long		rt_rtxcur;	/* current (backed-off) rto */
128};
129
130/*      
131 * Feedback values used for possible congestion and rate control
132 */
133#define FEEDBACK_REXMIT1	1	/* first retransmit */
134#define FEEDBACK_OK		2	/* no retransmits */    
135
136/* Used to set version of portmapper used in broadcast */
137  
138#define CLCR_SET_LOWVERS	3
139#define CLCR_GET_LOWVERS	4
140 
141#define RPCSMALLMSGSIZE 400	/* a more reasonable packet size */
142
143/*
144 * client side rpc interface ops
145 *
146 * Parameter types are:
147 *
148 */
149
150/*
151 * enum clnt_stat
152 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
153 * 	CLIENT *rh;
154 *	rpcproc_t proc;
155 *	xdrproc_t xargs;
156 *	void *argsp;
157 *	xdrproc_t xres;
158 *	void *resp;
159 *	struct timeval timeout;
160 */
161#define	CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
162	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
163		argsp, xres, resp, secs))
164#define	clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
165	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
166		argsp, xres, resp, secs))
167
168/*
169 * void
170 * CLNT_ABORT(rh);
171 * 	CLIENT *rh;
172 */
173#define	CLNT_ABORT(rh)	((*(rh)->cl_ops->cl_abort)(rh))
174#define	clnt_abort(rh)	((*(rh)->cl_ops->cl_abort)(rh))
175
176/*
177 * struct rpc_err
178 * CLNT_GETERR(rh);
179 * 	CLIENT *rh;
180 */
181#define	CLNT_GETERR(rh,errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
182#define	clnt_geterr(rh,errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
183
184
185/*
186 * bool_t
187 * CLNT_FREERES(rh, xres, resp);
188 * 	CLIENT *rh;
189 *	xdrproc_t xres;
190 *	void *resp;
191 */
192#define	CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
193#define	clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
194
195/*
196 * bool_t
197 * CLNT_CONTROL(cl, request, info)
198 *      CLIENT *cl;
199 *      u_int request;
200 *      char *info;
201 */
202#define	CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
203#define	clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
204
205/*
206 * control operations that apply to both udp and tcp transports
207 */
208#define CLSET_TIMEOUT		1	/* set timeout (timeval) */
209#define CLGET_TIMEOUT		2	/* get timeout (timeval) */
210#define CLGET_SERVER_ADDR	3	/* get server's address (sockaddr) */
211#define CLGET_FD		6	/* get connections file descriptor */
212#define CLGET_SVC_ADDR		7	/* get server's address (netbuf) */
213#define CLSET_FD_CLOSE		8	/* close fd while clnt_destroy */
214#define CLSET_FD_NCLOSE		9	/* Do not close fd while clnt_destroy */
215#define CLGET_XID 		10	/* Get xid */
216#define CLSET_XID		11	/* Set xid */
217#define CLGET_VERS		12	/* Get version number */
218#define CLSET_VERS		13	/* Set version number */
219#define CLGET_PROG		14	/* Get program number */
220#define CLSET_PROG		15	/* Set program number */
221#define CLSET_SVC_ADDR		16	/* get server's address (netbuf) */
222#define CLSET_PUSH_TIMOD	17	/* push timod if not already present */
223#define CLSET_POP_TIMOD		18	/* pop timod */
224/*
225 * Connectionless only control operations
226 */
227#define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
228#define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
229#define CLSET_ASYNC		19
230#define CLSET_CONNECT		20	/* Use connect() for UDP. (int) */
231
232/*
233 * void
234 * CLNT_DESTROY(rh);
235 * 	CLIENT *rh;
236 */
237#define	CLNT_DESTROY(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
238#define	clnt_destroy(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
239
240
241/*
242 * RPCTEST is a test program which is accessible on every rpc
243 * transport/port.  It is used for testing, performance evaluation,
244 * and network administration.
245 */
246
247#define RPCTEST_PROGRAM		((rpcprog_t)1)
248#define RPCTEST_VERSION		((rpcvers_t)1)
249#define RPCTEST_NULL_PROC	((rpcproc_t)2)
250#define RPCTEST_NULL_BATCH_PROC	((rpcproc_t)3)
251
252/*
253 * By convention, procedure 0 takes null arguments and returns them
254 */
255
256#define NULLPROC ((rpcproc_t)0)
257
258/*
259 * Below are the client handle creation routines for the various
260 * implementations of client side rpc.  They can return NULL if a
261 * creation failure occurs.
262 */
263
264/*
265 * Generic client creation routine. Supported protocols are those that
266 * belong to the nettype namespace (/etc/netconfig).
267 */
268__BEGIN_DECLS
269extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
270			   const char *);
271/*
272 *
273 * 	const char *hostname;			-- hostname
274 *	const rpcprog_t prog;			-- program number
275 *	const rpcvers_t vers;			-- version number
276 *	const char *nettype;			-- network type
277 */
278
279 /*
280 * Generic client creation routine. Just like clnt_create(), except
281 * it takes an additional timeout parameter.
282 */
283extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
284	const rpcvers_t, const char *, const struct timeval *);
285/*
286 *
287 *	const char *hostname;			-- hostname
288 *	const rpcprog_t prog;			-- program number
289 *	const rpcvers_t vers;			-- version number
290 *	const char *nettype;			-- network type
291 *	const struct timeval *tp;		-- timeout
292 */
293
294/*
295 * Generic client creation routine. Supported protocols are which belong
296 * to the nettype name space.
297 */
298extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
299				const rpcvers_t, const rpcvers_t,
300				const char *);
301/*
302 *	const char *host;		-- hostname
303 *	const rpcprog_t prog;		-- program number
304 *	rpcvers_t *vers_out;		-- servers highest available version
305 *	const rpcvers_t vers_low;	-- low version number
306 *	const rpcvers_t vers_high;	-- high version number
307 *	const char *nettype;		-- network type
308 */
309
310/*
311 * Generic client creation routine. Supported protocols are which belong
312 * to the nettype name space.
313 */
314extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
315	rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
316	const struct timeval *);
317/*
318 *	const char *host;		-- hostname
319 *	const rpcprog_t prog;		-- program number
320 *	rpcvers_t *vers_out;		-- servers highest available version
321 *	const rpcvers_t vers_low;	-- low version number
322 *	const rpcvers_t vers_high;	-- high version number
323 *	const char *nettype;		-- network type
324 *	const struct timeval *tp	-- timeout
325 */
326
327/*
328 * Generic client creation routine. It takes a netconfig structure
329 * instead of nettype
330 */
331extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
332			      const rpcvers_t, const struct netconfig *);
333/*
334 *	const char *hostname;			-- hostname
335 *	const rpcprog_t prog;			-- program number
336 *	const rpcvers_t vers;			-- version number
337 *	const struct netconfig *netconf; 	-- network config structure
338 */
339
340/*
341 * Generic client creation routine. Just like clnt_tp_create(), except
342 * it takes an additional timeout parameter.
343 */
344extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
345	const rpcvers_t, const struct netconfig *, const struct timeval *);
346/*
347 *	const char *hostname;			-- hostname
348 *	const rpcprog_t prog;			-- program number
349 *	const rpcvers_t vers;			-- version number
350 *	const struct netconfig *netconf; 	-- network config structure
351 *	const struct timeval *tp		-- timeout
352 */
353
354/*
355 * Generic TLI create routine. Only provided for compatibility.
356 */
357
358extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
359			       struct netbuf *, const rpcprog_t,
360			       const rpcvers_t, const u_int, const u_int);
361/*
362 *	const register int fd;		-- fd
363 *	const struct netconfig *nconf;	-- netconfig structure
364 *	struct netbuf *svcaddr;		-- servers address
365 *	const u_long prog;			-- program number
366 *	const u_long vers;			-- version number
367 *	const u_int sendsz;			-- send size
368 *	const u_int recvsz;			-- recv size
369 */
370
371/*
372 * Low level clnt create routine for connectionful transports, e.g. tcp.
373 */
374extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
375			      const rpcprog_t, const rpcvers_t,
376			      u_int, u_int);
377/*
378 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
379 */
380extern CLIENT *clntunix_create(struct sockaddr_un *,
381			       u_long, u_long, int *, u_int, u_int);
382/*
383 *	const int fd;				-- open file descriptor
384 *	const struct netbuf *svcaddr;		-- servers address
385 *	const rpcprog_t prog;			-- program number
386 *	const rpcvers_t vers;			-- version number
387 *	const u_int sendsz;			-- buffer recv size
388 *	const u_int recvsz;			-- buffer send size
389 */
390
391/*
392 * Low level clnt create routine for connectionless transports, e.g. udp.
393 */
394extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
395			      const rpcprog_t, const rpcvers_t,
396			      const u_int, const u_int);
397/*
398 *	const int fd;				-- open file descriptor
399 *	const struct netbuf *svcaddr;		-- servers address
400 *	const rpcprog_t program;		-- program number
401 *	const rpcvers_t version;		-- version number
402 *	const u_int sendsz;			-- buffer recv size
403 *	const u_int recvsz;			-- buffer send size
404 */
405
406/*
407 * Memory based rpc (for speed check and testing)
408 * CLIENT *
409 * clnt_raw_create(prog, vers)
410 *	u_long prog;
411 *	u_long vers;
412 */
413extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
414
415__END_DECLS
416
417
418/*
419 * Print why creation failed
420 */
421__BEGIN_DECLS
422extern void clnt_pcreateerror(const char *);			/* stderr */
423extern char *clnt_spcreateerror(const char *);			/* string */
424__END_DECLS
425
426/*
427 * Like clnt_perror(), but is more verbose in its output
428 */
429__BEGIN_DECLS
430extern void clnt_perrno(enum clnt_stat);		/* stderr */
431extern char *clnt_sperrno(enum clnt_stat);		/* string */
432__END_DECLS
433
434/*
435 * Print an English error message, given the client error code
436 */
437__BEGIN_DECLS
438extern void clnt_perror(CLIENT *, const char *);	 	/* stderr */
439extern char *clnt_sperror(CLIENT *, const char *);		/* string */
440__END_DECLS
441
442
443/*
444 * If a creation fails, the following allows the user to figure out why.
445 */
446struct rpc_createerr {
447	enum clnt_stat cf_stat;
448	struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
449};
450
451__BEGIN_DECLS
452extern struct rpc_createerr	*__rpc_createerr(void);
453__END_DECLS
454#define rpc_createerr		(*(__rpc_createerr()))
455
456/*
457 * The simplified interface:
458 * enum clnt_stat
459 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
460 *	const char *host;
461 *	const rpcprog_t prognum;
462 *	const rpcvers_t versnum;
463 *	const rpcproc_t procnum;
464 *	const xdrproc_t inproc, outproc;
465 *	const char *in;
466 *	char *out;
467 *	const char *nettype;
468 */
469__BEGIN_DECLS
470extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
471			       const rpcvers_t, const rpcproc_t,
472			       const xdrproc_t, const char *,
473			       const xdrproc_t, char *, const char *);
474__END_DECLS
475
476/*
477 * RPC broadcast interface
478 * The call is broadcasted to all locally connected nets.
479 *
480 * extern enum clnt_stat
481 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
482 *			eachresult, nettype)
483 *	const rpcprog_t		prog;		-- program number
484 *	const rpcvers_t		vers;		-- version number
485 *	const rpcproc_t		proc;		-- procedure number
486 *	const xdrproc_t	xargs;		-- xdr routine for args
487 *	caddr_t		argsp;		-- pointer to args
488 *	const xdrproc_t	xresults;	-- xdr routine for results
489 *	caddr_t		resultsp;	-- pointer to results
490 *	const resultproc_t	eachresult;	-- call with each result
491 *	const char		*nettype;	-- Transport type
492 *
493 * For each valid response received, the procedure eachresult is called.
494 * Its form is:
495 *		done = eachresult(resp, raddr, nconf)
496 *			bool_t done;
497 *			caddr_t resp;
498 *			struct netbuf *raddr;
499 *			struct netconfig *nconf;
500 * where resp points to the results of the call and raddr is the
501 * address if the responder to the broadcast.  nconf is the transport
502 * on which the response was received.
503 *
504 * extern enum clnt_stat
505 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
506 *			eachresult, inittime, waittime, nettype)
507 *	const rpcprog_t		prog;		-- program number
508 *	const rpcvers_t		vers;		-- version number
509 *	const rpcproc_t		proc;		-- procedure number
510 *	const xdrproc_t	xargs;		-- xdr routine for args
511 *	caddr_t		argsp;		-- pointer to args
512 *	const xdrproc_t	xresults;	-- xdr routine for results
513 *	caddr_t		resultsp;	-- pointer to results
514 *	const resultproc_t	eachresult;	-- call with each result
515 *	const int 		inittime;	-- how long to wait initially
516 *	const int 		waittime;	-- maximum time to wait
517 *	const char		*nettype;	-- Transport type
518 */
519
520typedef bool_t (*resultproc_t)(caddr_t, ...);
521
522__BEGIN_DECLS
523extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
524				    const rpcproc_t, const xdrproc_t,
525				    caddr_t, const xdrproc_t, caddr_t,
526				    const resultproc_t, const char *);
527extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
528					const rpcproc_t, const xdrproc_t,
529					caddr_t, const xdrproc_t, caddr_t,
530					const resultproc_t, const int,
531					const int, const char *);
532__END_DECLS
533
534/* For backward compatibility */
535#include <rpc/clnt_soc.h>
536
537#endif /* !_RPC_CLNT_H_ */