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$ 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 58A function to change or retrieve various information 59about a service object. 60The 61.Fa req 62argument 63indicates the type of operation and 64.Fa info 65is a pointer to the information. 66The supported values of 67.Fa req , 68their argument types, and what they do are: 69.Bl -tag -width SVCGET_XID 70.It Dv SVCGET_VERSQUIET 71If a request is received for a program number 72served by this server but the version number 73is outside the range registered with the server, 74an 75.Dv RPC_PROGVERSMISMATCH 76error will normally 77be returned. 78The 79.Fa info 80argument 81should be a pointer to an 82integer. 83Upon successful completion of the 84.Dv SVCGET_VERSQUIET 85request, 86.Fa *info 87contains an 88integer which describes the server's current 89behavior: 0 indicates normal server behavior 90(that is, an 91.Dv RPC_PROGVERSMISMATCH 92error 93will be returned); 1 indicates that the out of 94range request will be silently ignored. 95.It Dv SVCSET_VERSQUIET 96If a request is received for a program number 97served by this server but the version number 98is outside the range registered with the server, 99an 100.Dv RPC_PROGVERSMISMATCH 101error will normally 102be returned. 103It is sometimes desirable to 104change this behavior. 105The 106.Fa info 107argument 108should be a 109pointer to an integer which is either 0 110(indicating normal server behavior - an 111.Dv RPC_PROGVERSMISMATCH 112error will be returned), 113or 1 (indicating that the out of range request 114should 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