1 RPC_SVC_CREATE(3NSL) Networking Services Library Functions 2 3 4 5 NAME 6 rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create, 7 svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create, 8 svc_tp_create_addr, svc_vc_create, svc_door_create - server handle 9 creation routines 10 11 SYNOPSIS 12 #include <rpc/rpc.h> 13 14 bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info); 15 16 17 int svc_create(const void (*dispatch)(const struct svc_req *, 18 const SVCXPRT *), const rpcprog_t prognum, const rpcvers_t versnum, 19 const char *nettype); 20 21 22 void svc_destroy(SVCXPRT *xprt); 23 24 25 SVCXPRT *svc_dg_create(const int fildes, const uint_t sendsz, 26 const uint_t recvsz); 27 28 29 SVCXPRT *svc_fd_create(const int fildes, const uint_t sendsz, 30 const uint_t recvsz); 31 32 33 SVCXPRT *svc_raw_create(void); 34 35 36 SVCXPRT *svc_tli_create(const int fildes, const struct netconfig *netconf, 37 const struct t_bind *bind_info, const uint_t sendsz, 38 const uint_t recvsz); 39 40 41 SVCXPRT *svc_tp_create(const void (*dispatch) 42 (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum, 43 const rpcvers_t versnum, const struct netconfig *netconf); 44 45 46 SVCXPRT *svc_tp_create_addr(const void (*dispatch) 47 (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum, 48 const rpcvers_t versnum, const struct netconfig *netconf, 49 const struct netbuf *bind_addr) 50 ); 51 52 53 SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz, 54 const uint_t recvsz); 55 56 57 SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *), 58 const rpcprog_t prognum, const rpcvers_t versnum, 59 const uint_t sendsz); 60 61 62 DESCRIPTION 63 These routines are part of the RPC library which allows C language 64 programs to make procedure calls on servers across the network. These 65 routines deal with the creation of service handles. Once the handle is 66 created, the server can be invoked by calling svc_run(). 67 68 Routines 69 See rpc(3NSL) for the definition of the SVCXPRT data structure. 70 71 svc_control() 72 A function to change or retrieve information about a 73 service object. req indicates the type of operation and 74 info is a pointer to the information. The supported 75 values of req, their argument types, and what they do 76 are: 77 78 SVCGET_VERSQUIET 79 If a request is received for a program number 80 served by this server but the version number 81 is outside the range registered with the 82 server, an RPC_PROGVERSMISMATCH error will 83 normally be returned. info should be a 84 pointer to an integer. Upon successful 85 completion of the SVCGET_VERSQUIET request, 86 *info contains an integer which describes the 87 server's current behavior: 0 indicates normal 88 server behavior, that is, an 89 RPC_PROGVERSMISMATCH error will be returned. 90 1 indicates that the out of range request will 91 be silently ignored. 92 93 94 SVCSET_VERSQUIET 95 If a request is received for a program number 96 served by this server but the version number 97 is outside the range registered with the 98 server, an RPC_PROGVERSMISMATCH error will 99 normally be returned. It is sometimes 100 desirable to change this behavior. info should 101 be a pointer to an integer which is either 0, 102 indicating normal server behavior and an 103 RPC_PROGVERSMISMATCH error will be returned, 104 or 1, indicating that the out of range 105 request should be silently ignored. 106 107 108 SVCGET_XID 109 Returns the transaction ID of 110 connection-oriented and connectionless 111 transport service calls. The transaction ID 112 assists in uniquely identifying client 113 requests for a given RPC version, program 114 number, procedure, and client. The transaction 115 ID is extracted from the service transport 116 handle svc. info must be a pointer to an 117 unsigned long. Upon successful completion of 118 the SVCGET_XID request, *info contains the 119 transaction ID. Note that rendezvous and raw 120 service handles do not define a transaction 121 ID. Thus, if the service handle is of 122 rendezvous or raw type, and the request is of 123 type SVCGET_XID, svc_control() will return 124 FALSE. Note also that the transaction ID read 125 by the server can be set by the client through 126 the suboption CLSET_XID in clnt_control(). 127 See clnt_create(3NSL) 128 129 130 SVCSET_RECVERRHANDLER 131 Attaches or detaches a disconnection handler 132 to the service handle, svc, that will be 133 called when a transport error arrives during 134 the reception of a request or when the server 135 is waiting for a request and the connection 136 shuts down. This handler is only useful for a 137 connection oriented service handle. 138 139 *info contains the address of the error 140 handler to attach, or NULL to detach a 141 previously defined one. The error handler has 142 two arguments. It has a pointer to the 143 erroneous service handle. It also has an 144 integer that indicates if the full service is 145 closed (when equal to zero), or that only one 146 connection on this service is closed (when not 147 equal to zero). 148 149 void handler (const SVCXPRT *svc, const bool_t isAConnection); 150 151 With the service handle address, svc, the 152 error handler is able to detect which 153 connection has failed and to begin an error 154 recovery process. The error handler can be 155 called by multiple threads and should be 156 implemented in an MT-safe way. 157 158 159 SVCGET_RECVERRHANDLER 160 Upon successful completion of the 161 SVCGET_RECVERRHANDLER request, *info contains 162 the address of the handler for receiving 163 errors. Upon failure, *info contains NULL. 164 165 166 SVCSET_CONNMAXREC 167 Set the maximum record size (in bytes) and 168 enable non-blocking mode for this service 169 handle. Value can be set and read for both 170 connection and non-connection oriented 171 transports, but is silently ignored for the 172 non-connection oriented case. The info 173 argument should be a pointer to an int. 174 175 176 SVCGET_CONNMAXREC 177 Get the maximum record size for this service 178 handle. Zero means no maximum in effect and 179 the connection is in blocking mode. The result 180 is not significant for non-connection oriented 181 transports. The info argument should be a 182 pointer to an int. 183 184 This routine returns TRUE if the operation was 185 successful. Otherwise, it returns false. 186 187 188 svc_create() 189 svc_create() creates server handles for all the 190 transports belonging to the class nettype. 191 192 nettype defines a class of transports which can be used 193 for a particular application. The transports are tried 194 in left to right order in NETPATH variable or in top to 195 bottom order in the netconfig database. If nettype is 196 NULL, it defaults to netpath. 197 198 svc_create() registers itself with the rpcbind service 199 (see rpcbind(1M)). dispatch is called when there is a 200 remote procedure call for the given prognum and versnum; 201 this requires calling svc_run() (see svc_run() in 202 rpc_svc_calls(3NSL)). If svc_create() succeeds, it 203 returns the number of server handles it created, 204 otherwise it returns 0 and an error message is logged. 205 206 207 svc_destroy() 208 A function macro that destroys the RPC service handle 209 xprt. Destruction usually involves deallocation of 210 private data structures, including xprt itself. Use of 211 xprt is undefined after calling this routine. 212 213 214 svc_dg_create() 215 This routine creates a connectionless RPC service 216 handle, and returns a pointer to it. This routine 217 returns NULL if it fails, and an error message is 218 logged. sendsz and recvsz are parameters used to specify 219 the size of the buffers. If they are 0, suitable 220 defaults are chosen. The file descriptor fildes should 221 be open and bound. The server is not registered with 222 rpcbind(1M). 223 224 Warning: since connectionless-based RPC messages can 225 only hold limited amount of encoded data, this transport 226 cannot be used for procedures that take large arguments 227 or return huge results. 228 229 230 svc_fd_create() 231 This routine creates a service on top of an open and 232 bound file descriptor, and returns the handle to it. 233 Typically, this descriptor is a connected file 234 descriptor for a connection-oriented transport. sendsz 235 and recvsz indicate sizes for the send and receive 236 buffers. If they are 0, reasonable defaults are chosen. 237 This routine returns NULL if it fails, and an error 238 message is logged. 239 240 241 svc_raw_create() 242 This routine creates an RPC service handle and returns a 243 pointer to it. The transport is really a buffer within 244 the process's address space, so the corresponding RPC 245 client should live in the same address space; (see 246 clnt_raw_create() in rpc_clnt_create(3NSL)). This 247 routine allows simulation of RPC and acquisition of RPC 248 overheads (such as round trip times), without any kernel 249 and networking interference. This routine returns NULL 250 if it fails, and an error message is logged. 251 252 Note: svc_run() should not be called when the raw 253 interface is being used. 254 255 256 svc_tli_create() 257 This routine creates an RPC server handle, and returns a 258 pointer to it. fildes is the file descriptor on which 259 the service is listening. If fildes is RPC_ANYFD, it 260 opens a file descriptor on the transport specified by 261 netconf. If the file descriptor is unbound and bind_info 262 is non-null fildes is bound to the address specified by 263 bind_info, otherwise fildes is bound to a default 264 address chosen by the transport. In the case where the 265 default address is chosen, the number of outstanding 266 connect requests is set to 8 for connection-oriented 267 transports. The user may specify the size of the send 268 and receive buffers with the parameters sendsz and 269 recvsz ; values of 0 choose suitable defaults. This 270 routine returns NULL if it fails, and an error message 271 is logged. The server is not registered with the 272 rpcbind(1M) service. 273 274 275 svc_tp_create() 276 svc_tp_create() creates a server handle for the network 277 specified by netconf, and registers itself with the 278 rpcbind service. dispatch is called when there is a 279 remote procedure call for the given prognum and versnum; 280 this requires calling svc_run(). svc_tp_create() 281 returns the service handle if it succeeds, otherwise a 282 NULL is returned and an error message is logged. 283 284 285 svc_tp_create_addr() 286 svc_tp_create_addr() creates a server handle for the 287 network specified by netconf, and registers itself with 288 the rpcbind service. If bind_addr is non-NULL, that 289 address is used for the listener binding. If bind_addr 290 is NULL, this call is the same as svc_tp_create(). 291 dispatch is called when there is a remote procedure call 292 for the given prognum and versnum; this requires calling 293 svc_run(). svc_tp_create_addr() returns the service 294 handle if it succeeds, otherwise a NULL is returned and 295 an error message is logged. 296 297 298 svc_vc_create() 299 This routine creates a connection-oriented RPC service 300 and returns a pointer to it. This routine returns NULL 301 if it fails, and an error message is logged. The users 302 may specify the size of the send and receive buffers 303 with the parameters sendsz and recvsz; values of 0 304 choose suitable defaults. The file descriptor fildes 305 should be open and bound. The server is not registered 306 with the rpcbind(1M) service. 307 308 309 svc_door_create() 310 This routine creates an RPC server handle over doors for 311 the given program prognum and version versnum and 312 returns a pointer to it. Doors is a transport mechanism 313 that facilitates fast data transfer between processes on 314 the same machine. The user may set the size of the send 315 buffer with the parameter sendsz. If sendsz is 0, the 316 corresponding default buffer size is 16 Kbyte. If 317 successful, the svc_door_create() routine returns the 318 service handle. Otherwise it returns NULL and sets a 319 value for rpc_createerr. The server is not registered 320 with rpcbind(1M). The SVCSET_CONNMAXREC and 321 SVCGET_CONNMAXREC svc_control() requests can be used to 322 set and change the maximum allowed request size for the 323 doors transport. 324 325 326 ATTRIBUTES 327 See attributes(5) for descriptions of the following attributes: 328 329 330 331 332 +--------------------+-----------------+ 333 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 334 +--------------------+-----------------+ 335 |Architecture | All | 336 +--------------------+-----------------+ 337 |Interface Stability | Evolving | 338 +--------------------+-----------------+ 339 |MT-Level | MT-Safe | 340 +--------------------+-----------------+ 341 342 SEE ALSO 343 rpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL), 344 rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5) 345 346 347 348 June 19, 2017 RPC_SVC_CREATE(3NSL)