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