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.11 2010/03/22 19:30:54 joerg 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 "const 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 "const void (*dispatch)(const struct svc_reg *, const 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.Dv SVCXPRT 55data structure. 56.Pp 57.Bl -tag -width XXXXX 58.It Fn svc_control 59A function to change or retrieve various information 60about a service object. 61.Fa req 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. 77.Fa info 78should be a pointer to an integer. 79Upon successful completion of the 80.Dv SVCGET_VERSQUIET 81request, 82.Fa *info 83contains an 84integer which describes the server's current 85behavior: 0 indicates normal server behavior 86(that is, an 87.Dv RPC_PROGVERSMISMATCH 88error 89will be returned); 1 indicates that the out of 90range request will be silently ignored. 91.Pp 92.It Dv SVCSET_VERSQUIET 93If a request is received for a program number 94served by this server but the version number 95is outside the range registered with the server, 96an 97.Dv RPC_PROGVERSMISMATCH 98error will normally be returned. 99It is sometimes desirable to change 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. 158Use of 159.Fa xprt 160is undefined after calling this routine. 161.Pp 162.It Fn svc_dg_create 163This routine creates a connectionless RPC 164service handle, and returns a pointer to it. 165This routine returns 166.Dv NULL 167if it fails, and an error message is logged. 168.Fa sendsz 169and 170.Fa recvsz 171are parameters used to specify the size of the buffers. 172If they are 0, suitable defaults are chosen. 173The file descriptor 174.Fa fildes 175should be open and bound. 176The server is not registered with 177.Xr rpcbind 8 . 178.Em Warning : 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.Em Note : 215.Fn svc_run 216should not be called when the raw interface is being used. 217.Pp 218.It Fn svc_tli_create 219This routine creates an RPC 220server handle, and returns a pointer to it. 221.Fa fildes 222is the file descriptor on which the service is listening. 223If 224.Fa fildes 225is 226.Dv RPC_ANYFD , 227it opens a file descriptor on the transport specified by 228.Fa netconf . 229If the file descriptor is unbound and 230.Fa bindaddr 231is non-null 232.Fa fildes 233is bound to the address specified by 234.Fa bindaddr , 235otherwise 236.Fa fildes 237is bound to a default address chosen by the transport. 238.Pp 239Note: the 240.Vt t_bind 241structure comes from the TLI/XTI SysV interface, which 242.Nx 243does not use. 244The structure is defined in 245.In rpc/types.h 246for compatibility as: 247.Bd -literal 248struct t_bind { 249 struct netbuf addr; /* network address, see rpc(3) */ 250 unsigned int qlen; /* queue length (for listen(2)) */ 251}; 252.Ed 253.Pp 254In the case where the default address is chosen, 255the number of outstanding connect requests is set to 8 256for connection-oriented transports. 257The user may specify the size of the send and receive buffers 258with the parameters 259.Fa sendsz 260and 261.Fa recvsz ; 262values of 0 choose suitable defaults. 263This routine returns 264.Dv NULL 265if it fails, 266and an error message is logged. 267The server is not registered with the 268.Xr rpcbind 8 269service. 270.Pp 271.It Fn svc_tp_create 272.Fn svc_tp_create 273creates a server handle for the network 274specified by 275.Fa netconf , 276and registers itself with the rpcbind service. 277.Fa dispatch 278is called when there is a remote procedure call 279for the given 280.Fa prognum 281and 282.Fa versnum ; 283this requires calling 284.Fn svc_run . 285.Fn svc_tp_create 286returns the service handle if it succeeds, 287otherwise a 288.Dv NULL 289is returned and an error message is logged. 290.Pp 291.It Fn svc_vc_create 292This routine creates a connection-oriented RPC 293service and returns a pointer to it. 294This routine returns 295.Dv NULL 296if it fails, and an error message is logged. 297The users may specify the size of the send and receive buffers 298with the parameters 299.Fa sendsz 300and 301.Fa recvsz ; 302values of 0 choose suitable defaults. 303The file descriptor 304.Fa fildes 305should be open and bound. 306The server is not registered with the 307.Xr rpcbind 8 308service. 309.El 310.Sh SEE ALSO 311.Xr rpc 3 , 312.Xr rpc_svc_calls 3 , 313.Xr rpc_svc_err 3 , 314.Xr rpc_svc_reg 3 , 315.Xr rpcbind 8 316