lib/libc/rpc/rpc_svc_create.3

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