1rpc_svc_create(3NSL) Networking Services Library Functionsrpc_svc_create(3NSL)
2
3
4

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_vc_create, svc_door_create - server handle creation routines
9

SYNOPSIS

11       #include <rpc/rpc.h>
12
13       bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);
14
15
16       int svc_create(const void (*dispatch)const struct svc_req *,
17            const SVCXPRT *, const rpcprog_t prognum, const rpcvers_t versnum,
18            const char *nettype);
19
20
21       void svc_destroy(SVCXPRT *xprt);
22
23
24       SVCXPRT *svc_dg_create(const int fildes, const uint_t sendsz,
25            const uint_t recvsz);
26
27
28       SVCXPRT *svc_fd_create(const int fildes, const uint_t sendsz,
29            const uint_t recvsz);
30
31
32       SVCXPRT *svc_raw_create(void)
33
34
35       SVCXPRT *svc_tli_create(const int fildes, const struct netconfig *netconf,
36            const struct t_bind *bind_addr, const uint_t sendsz,
37            const uint_t recvsz);
38
39
40       SVCXPRT *svc_tp_create(const void (*dispatch)
41            const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
42            const rpcvers_t versnum, const struct netconfig *netconf);
43
44
45       SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz,
46            const uint_t recvsz);
47
48
49       SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
50            const rpcprog_t prognum, const rpcvers_t versnum,
51            const uint_t sendsz);
52
53

DESCRIPTION

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

ATTRIBUTES

365       See attributes(5)  for descriptions of the following attributes:
366
367
368
369
370       ┌─────────────────────────────┬─────────────────────────────┐
371       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
372       ├─────────────────────────────┼─────────────────────────────┤
373       │Architecture                 │All                          │
374       ├─────────────────────────────┼─────────────────────────────┤
375       │Availability                 │SUNWcsl (32-bit)             │
376       ├─────────────────────────────┼─────────────────────────────┤
377       │                             │SUNWcslx (64-bit)            │
378       ├─────────────────────────────┼─────────────────────────────┤
379       │Interface Stability          │Evolving                     │
380       ├─────────────────────────────┼─────────────────────────────┤
381       │MT-Level                     │MT-Safe                      │
382       └─────────────────────────────┴─────────────────────────────┘
383

SEE ALSO

385       rpcbind(1M),   rpc(3NSL),  rpc_clnt_create(3NSL),  rpc_svc_calls(3NSL),
386       rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)
387
388
389
390SunOS 5.11                        22 Mar 2005             rpc_svc_create(3NSL)
Impressum