man/rpc_svc_create.3t

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