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