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