xref: /dragonfly/lib/libc/rpc/rpc_svc_create.3 (revision d4ef6694) 
1.\" @(#)rpc_svc_create.3n 1.26 93/08/26 SMI; from SVr4
2.\" Copyright 1989 AT&T
3.\" @(#)rpc_svc_create 1.3 89/06/28 SMI;
4.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
5.\" $FreeBSD: src/lib/libc/rpc/rpc_svc_create.3,v 1.7 2003/09/08 19:57:15 ru Exp $
6.Dd May 3, 1993
7.Dt RPC_SVC_CREATE 3
8.Os
9.Sh NAME
10.Nm rpc_svc_create ,
11.\".Nm svc_control ,
12.Nm svc_create ,
13.Nm svc_destroy ,
14.Nm svc_dg_create ,
15.Nm svc_fd_create ,
16.Nm svc_raw_create ,
17.Nm svc_tli_create ,
18.Nm svc_tp_create ,
19.Nm svc_vc_create
20.Nd library routines for the creation of server handles
21.Sh LIBRARY
22.Lb libc
23.Sh SYNOPSIS
24.In rpc/rpc.h
25.\".Ft bool_t
26.\".Fn svc_control "SVCXPRT *svc" "const u_int req" "void *info"
27.Ft int
28.Fn svc_create "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype"
29.Ft SVCXPRT *
30.Fn svc_dg_create "const int fildes" "const u_int sendsz" "const u_int recvsz"
31.Ft void
32.Fn svc_destroy "SVCXPRT *xprt"
33.Ft "SVCXPRT *"
34.Fn svc_fd_create "const int fildes" "const u_int sendsz" "const u_int recvsz"
35.Ft "SVCXPRT *"
36.Fn svc_raw_create "void"
37.Ft "SVCXPRT *"
38.Fn svc_tli_create "const int fildes" "const struct netconfig *netconf" "const struct t_bind *bindaddr" "const u_int sendsz" "const u_int recvsz"
39.Ft "SVCXPRT *"
40.Fn svc_tp_create "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
41.Ft "SVCXPRT *"
42.Fn svc_vc_create "const int fildes" "const u_int sendsz" "const u_int recvsz"
43.Sh DESCRIPTION
44These routines are part of the RPC
45library which allows C language programs to make procedure
46calls on servers across the network.
47These routines deal with the creation of service handles.
48Once the handle is created, the server can be invoked by calling
49.Fn svc_run .
50.Sh Routines
51See
52.Xr rpc 3
53for the definition of the
54.Vt SVCXPRT
55data structure.
56.Bl -tag -width XXXXX
57.\".It Fn svc_control
58.\"A function to change or retrieve various information
59.\"about a service object.
60.\"The
61.\".Fa req
62.\"argument
63.\"indicates the type of operation and
64.\".Fa info
65.\"is a pointer to the information.
66.\"The supported values of
67.\".Fa req ,
68.\"their argument types, and what they do are:
69.\".Bl -tag -width SVCGET_XID
70.\".It Dv SVCGET_VERSQUIET
71.\"If a request is received for a program number
72.\"served by this server but the version number
73.\"is outside the range registered with the server,
74.\"an
75.\".Dv RPC_PROGVERSMISMATCH
76.\"error will normally
77.\"be returned.
78.\"The
79.\".Fa info
80.\"argument
81.\"should be a pointer to an
82.\"integer.
83.\"Upon successful completion of the
84.\".Dv SVCGET_VERSQUIET
85.\"request,
86.\".Fa *info
87.\"contains an
88.\"integer which describes the server's current
89.\"behavior: 0 indicates normal server behavior
90.\"(that is, an
91.\".Dv RPC_PROGVERSMISMATCH
92.\"error
93.\"will be returned); 1 indicates that the out of
94.\"range request will be silently ignored.
95.\".It Dv SVCSET_VERSQUIET
96.\"If a request is received for a program number
97.\"served by this server but the version number
98.\"is outside the range registered with the server,
99.\"an
100.\".Dv RPC_PROGVERSMISMATCH
101.\"error will normally
102.\"be returned.
103.\"It is sometimes desirable to
104.\"change this behavior.
105.\"The
106.\".Fa info
107.\"argument
108.\"should be a
109.\"pointer to an integer which is either 0
110.\"(indicating normal server behavior - an
111.\".Dv RPC_PROGVERSMISMATCH
112.\"error will be returned),
113.\"or 1 (indicating that the out of range request
114.\"should be silently ignored).
115.\".El
116.It Fn svc_create
117The
118.Fn svc_create
119function
120creates server handles for all the transports
121belonging to the class
122.Fa nettype .
123The
124.Fa nettype
125argument
126defines a class of transports which can be used
127for a particular application.
128The transports are tried in left to right order in
129.Ev NETPATH
130variable or in top to bottom order in the netconfig database.
131If
132.Fa nettype
133is
134.Dv NULL ,
135it defaults to
136.Qq netpath .
137.Pp
138The
139.Fn svc_create
140function
141registers itself with the rpcbind
142service (see
143.Xr rpcbind 8 ) .
144The
145.Fa dispatch
146function
147is called when there is a remote procedure call for the given
148.Fa prognum
149and
150.Fa versnum ;
151this requires calling
152.Fn svc_run
153(see
154.Fn svc_run
155in
156.Xr rpc_svc_reg 3 ) .
157If
158.Fn svc_create
159succeeds, it returns the number of server
160handles it created,
161otherwise it returns 0 and an error message is logged.
162.It Fn svc_destroy
163A function macro that destroys the RPC
164service handle
165.Fa xprt .
166Destruction usually involves deallocation
167of private data structures,
168including
169.Fa xprt
170itself.
171Use of
172.Fa xprt
173is undefined after calling this routine.
174.It Fn svc_dg_create
175This routine creates a connectionless RPC
176service handle, and returns a pointer to it.
177This routine returns
178.Dv NULL
179if it fails, and an error message is logged.
180The
181.Fa sendsz
182and
183.Fa recvsz
184arguments
185are arguments used to specify the size of the buffers.
186If they are 0, suitable defaults are chosen.
187The file descriptor
188.Fa fildes
189should be open and bound.
190The server is not registered with
191.Xr rpcbind 8 .
192.Pp
193Warning:
194since connectionless-based RPC
195messages can only hold limited amount of encoded data,
196this transport cannot be used for procedures
197that take large arguments or return huge results.
198.It Fn svc_fd_create
199This routine creates a service on top of an open and bound file descriptor,
200and returns the handle to it.
201Typically, this descriptor is a connected file descriptor for a
202connection-oriented transport.
203The
204.Fa sendsz
205and
206.Fa recvsz
207arguments
208indicate sizes for the send and receive buffers.
209If they are 0, reasonable defaults are chosen.
210This routine returns
211.Dv NULL
212if it fails, and an error message is logged.
213.It Fn svc_raw_create
214This routine creates an RPC
215service handle and returns a pointer to it.
216The transport is really a buffer within the process's
217address space, so the corresponding RPC
218client should live in the same address space;
219(see
220.Fn clnt_raw_create
221in
222.Xr rpc_clnt_create 3 ) .
223This routine allows simulation of RPC and acquisition of
224RPC overheads (such as round trip times),
225without any kernel and networking interference.
226This routine returns
227.Dv NULL
228if it fails, and an error message is logged.
229.Pp
230Note:
231.Fn svc_run
232should not be called when the raw interface is being used.
233.It Fn svc_tli_create
234This routine creates an RPC
235server handle, and returns a pointer to it.
236The
237.Fa fildes
238argument
239is the file descriptor on which the service is listening.
240If
241.Fa fildes
242is
243.Dv RPC_ANYFD ,
244it opens a file descriptor on the transport specified by
245.Fa netconf .
246If the file descriptor is unbound and
247.Fa bindaddr
248is not
249.Dv NULL ,
250.Fa fildes
251is bound to the address specified by
252.Fa bindaddr ,
253otherwise
254.Fa fildes
255is bound to a default address chosen by the transport.
256.Pp
257Note: the
258.Vt t_bind
259structure comes from the TLI/XTI SysV interface, which
260.Nx
261does not use.
262The structure is defined in
263.In rpc/types.h
264for compatibility as:
265.Bd -literal
266struct t_bind {
267    struct netbuf addr;	/* network address, see rpc(3) */
268    unsigned int  qlen;	/* queue length (for listen(2)) */
269};
270.Ed
271.Pp
272In the case where the default address is chosen,
273the number of outstanding connect requests is set to 8
274for connection-oriented transports.
275The user may specify the size of the send and receive buffers
276with the arguments
277.Fa sendsz
278and
279.Fa recvsz ;
280values of 0 choose suitable defaults.
281This routine returns
282.Dv NULL
283if it fails,
284and an error message is logged.
285The server is not registered with the
286.Xr rpcbind 8
287service.
288.It Fn svc_tp_create
289The
290.Fn svc_tp_create
291function
292creates a server handle for the network
293specified by
294.Fa netconf ,
295and registers itself with the rpcbind service.
296The
297.Fa dispatch
298function
299is called when there is a remote procedure call
300for the given
301.Fa prognum
302and
303.Fa versnum ;
304this requires calling
305.Fn svc_run .
306The
307.Fn svc_tp_create
308function
309returns the service handle if it succeeds,
310otherwise a
311.Dv NULL
312is returned and an error message is logged.
313.It Fn svc_vc_create
314This routine creates a connection-oriented RPC
315service and returns a pointer to it.
316This routine returns
317.Dv NULL
318if it fails, and an error message is logged.
319The users may specify the size of the send and receive buffers
320with the arguments
321.Fa sendsz
322and
323.Fa recvsz ;
324values of 0 choose suitable defaults.
325The file descriptor
326.Fa fildes
327should be open and bound.
328The server is not registered with the
329.Xr rpcbind 8
330service.
331.El
332.Sh SEE ALSO
333.Xr rpc 3 ,
334.Xr rpc_svc_calls 3 ,
335.Xr rpc_svc_err 3 ,
336.Xr rpc_svc_reg 3 ,
337.Xr rpcbind 8
338