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