1rpc_soc(3NSL)        Networking Services Library Functions       rpc_soc(3NSL)
2
3
4

NAME

6       rpc_soc,   authdes_create,   authunix_create,  authunix_create_default,
7       callrpc,      clnt_broadcast,      clntraw_create,      clnttcp_create,
8       clntudp_bufcreate,     clntudp_create,    get_myaddress,    getrpcport,
9       pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, pmap_unset,  regis‐
10       terrpc,  svc_fds, svc_getcaller, svc_getreq, svc_register, svc_unregis‐
11       ter,  svcfd_create,  svcraw_create,  svctcp_create,   svcudp_bufcreate,
12       svcudp_create, xdr_authunix_parms - obsolete library routines for RPC
13

SYNOPSIS

15       #define PORTMAP
16       #include <rpc/rpc.h>
17
18
19       AUTH *authdes_create(char *name, uint_t window,
20            struct sockaddr_in *syncaddr, des_block *ckey);
21
22
23       AUTH *authunix_create(char *host, uid_t uid, gid_t gid,
24            int grouplen, gid_t *gidlistp);
25
26
27       AUTH *authunix_create_default(void)
28
29
30       callrpc(char *host, rpcprog_t prognum, rpcvers_t versnum,
31            rpcproc_t procnum, xdrproc_t inproc, char *in,
32            xdrproc_t outproc, char *out);
33
34
35       enum clnt_stat_clnt_broadcast(rpcprog_t prognum, rpcvers_t versnum,
36            rpcproc_t procnum, xdrproc_t inproc, char *in,
37            xdrproc_t outproc, char *out, resultproc_teachresult);
38
39
40       CLIENT *clntraw_create(rpcproc_t procnum, rpcvers_t versnum);
41
42
43       CLIENT *clnttcp_create(struct sockaddr_in *addr,
44            rpcprog_t prognum, rpcvers_t versnum, int *fdp,
45            uint_t sendz, uint_t recvsz);
46
47
48       CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, rpcprog_t prognum,
49            rpcvers_t versnum, struct timeval wait,
50            int *fdp, uint_t sendz, uint_t recvsz);
51
52
53       CLIENT *clntudp_create(struct sockaddr_in *addr,
54            rpcprog_t prognum, struct timeval wait, int *fdp);
55
56
57       void get_myaddress(struct sockaddr_in *addr);
58
59
60       ushort getrpcport(char *host, rpcprog_t prognum,
61            rpcvers_t versnum, rpcprot_t proto);
62
63
64       struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);
65
66
67       ushort pmap_getport(struct sockaddr_in *addr,
68            rpcprog_t prognum, rpcvers_t versnum,
69            rpcprot_t protocol);
70
71
72       enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr,
73            rpcprog_t prognum, rpcvers_t versnum,
74            rpcproc_t progcnum, caddr_t in, xdrproct_t inproc,
75            caddr_t out, cdrproct_t outproc,
76            struct timeval tout, rpcport_t *portp);
77
78
79       bool_t pmap_set(rpcprog_t prognum, rpcvers_t versnum,
80            rpcprot_t protocol, u_short port);
81
82
83       bool_t pmap_unset(rpcprog_t prognum, rpcvers_t versnum);
84
85
86       int svc_fds;
87
88
89       struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);
90
91
92       void svc_getreq(int rdfds);
93
94
95       SVCXPRT *svcfd_create(int fd, uint_t sendsz,
96            uint_t recvsz);
97
98
99       SVCXPRT *svcraw_create(void)
100
101
102       SVCXPRT *svctcp_create(int fd, uint_t sendsz,
103            uint_t recvsz);
104
105
106       SVCXPRT *svcudp_bufcreate(int fd, uint_t sendsz,
107            uint_t recvsz);
108
109
110       SVCXPRT *svcudp_create(int fd);
111
112
113       registerrpc(rpcprog_t prognum, rpcvers_t versnum, rpcproc_t procnum,
114            char *(*procname)(), xdrproc_t inproc, xdrproc_t outproc);
115
116
117       bool_tsvc_register(SVCXPRT *xprt, rpcprog_t prognum, rpcvers_t versnum,
118            void (*dispatch(), int protocol);
119
120
121       void svc_unregister(rpcprog_t prognum, rpcvers_t versnum);
122
123
124       bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *supp);
125
126

DESCRIPTION

128       RPC routines allow C programs to make procedure calls on other machines
129       across the network. First, the client  calls  a  procedure  to  send  a
130       request  to the server. Upon receipt of the request, the server calls a
131       dispatch routine to perform the requested service, and then sends  back
132       a reply. Finally, the procedure call returns to the client.
133
134
135       The  routines  described  in  this  manual page have been superseded by
136       other routines. The preferred routine is given after the description of
137       the routine. New programs should use the preferred routines, as support
138       for the older interfaces may be dropped in future releases.
139
140   File Descriptors
141       Transport independent  RPC uses  TLI as its transport interface instead
142       of sockets.
143
144
145       Some  of  the  routines described in this section (such as clnttcp_cre‐
146       ate()) take a pointer to a file descriptor as one of the parameters. If
147       the user wants the file descriptor to be a socket, then the application
148       will have to be linked with both  librpcsoc and  libnsl.  If  the  user
149       passed   RPC_ANYSOCK  as  the  file  descriptor, and the application is
150       linked with libnsl only, then the  routine  will  return  a   TLI  file
151       descriptor and not a socket.
152
153   Routines
154       The following routines require that the header <rpc/rpc.h> be included.
155       The symbol PORTMAP should be defined so that the  appropriate  function
156       declarations  for  the  old  interfaces are included through the header
157       files.
158
159       authdes_create()              authdes_create() is the first of two rou‐
160                                     tines  which  interface to the RPC secure
161                                     authentication  system,  known   as   DES
162                                     authentication.     The     second     is
163                                     authdes_getucred(),  below.   Note:   the
164                                     keyserver daemon keyserv(1M) must be run‐
165                                     ning for the DES authentication system to
166                                     work.
167
168                                     authdes_create(),   used  on  the  client
169                                     side,  returns an  authentication  handle
170                                     that  will  enable  the use of the secure
171                                     authentication system. The first  parame‐
172                                     ter name is the network name, or netname,
173                                     of the owner of the server process.  This
174                                     field   usually   represents  a  hostname
175                                     derived   from   the   utility    routine
176                                     host2netname(),  but could also represent
177                                     a user  name  using  user2netname().  See
178                                     secure_rpc(3NSL).  The  second  field  is
179                                     window on the validity of the client cre‐
180                                     dential, given in seconds.   A small win‐
181                                     dow is more secure than a large one,  but
182                                     choosing  too  small  of  a  window  will
183                                     increase the frequency of  resynchroniza‐
184                                     tions  because of clock drift.  The third
185                                     parameter syncaddr is optional.    If  it
186                                     is  NULL,  then the authentication system
187                                     will  assume  that  the  local  clock  is
188                                     always  in  sync with the server's clock,
189                                     and will not attempt  resynchronizations.
190                                     If  an address is supplied, however, then
191                                     the system will use the address for  con‐
192                                     sulting  the remote time service whenever
193                                     resynchronization  is   required.    This
194                                     parameter  is  usually the address of the
195                                     RPC server itself.  The  final  parameter
196                                     ckey  is  also  optional.  If it is NULL,
197                                     then the authentication system will  gen‐
198                                     erate a random DES key to be used for the
199                                     encryption of credentials. If it is  sup‐
200                                     plied,  however,   then  it  will be used
201                                     instead.
202
203                                     This routine exists for backward compati‐
204                                     bility  only,  and it is made obsolete by
205                                     authdes_seccreate().                  See
206                                     secure_rpc(3NSL).
207
208
209       authunix_create()             Create  and  return an RPC authentication
210                                     handle that contains  .UX  authentication
211                                     information.  The  parameter  host is the
212                                     name of the machine on which the informa‐
213                                     tion  was created; uid is the user's user
214                                     ID; gid is the user's current  group  ID;
215                                     grouplen  and gidlistp refer to a counted
216                                     array  of  groups  to  which   the   user
217                                     belongs.
218
219                                     It is not very difficult to impersonate a
220                                     user.
221
222                                     This routine exists for backward compati‐
223                                     bility  only,  and it is made obsolete by
224                                     authsys_create().                     See
225                                     rpc_clnt_auth(3NSL).
226
227
228       authunix_create_default()     Call authunix_create() with the appropri‐
229                                     ate parameters.
230
231                                     This routine exists for backward compati‐
232                                     bility  only,  and it is made obsolete by
233                                     authsys_create_default().             See
234                                     rpc_clnt_auth(3NSL).
235
236
237       callrpc()                     Call the remote procedure associated with
238                                     prognum,  versnum,  and  procnum  on  the
239                                     machine,  host.  The  parameter inproc is
240                                     used to encode  the  procedure's  parame‐
241                                     ters,  and  outproc is used to decode the
242                                     procedure's results; in is the address of
243                                     the  procedure's argument, and out is the
244                                     address of where to place the  result(s).
245                                     This  routine  returns  0 if it succeeds,
246                                     or the value of enum clnt_stat cast to an
247                                     integer   if   it   fails.   The  routine
248                                     clnt_perrno() is  handy  for  translating
249                                     failure   statuses   into  messages.  See
250                                     rpc_clnt_calls(3NSL).
251
252                                     You do not have control  of  timeouts  or
253                                     authentication  using  this routine. This
254                                     routine exists for backward compatibility
255                                     only, and is made obsolete by rpc_call().
256                                     See rpc_clnt_calls(3NSL).
257
258
259       clnt_stat_clnt_broadcast()    Like callrpc(), except the  call  message
260                                     is  broadcast  to  all  locally connected
261                                     broadcast  nets.  Each  time  the  caller
262                                     receives  a  response, this routine calls
263                                     eachresult(), whose form is:
264
265                                       eachresult(char *out, struct sockaddr_in *addr);
266
267                                     where out is the same as  out  passed  to
268                                     clnt_broadcast(),  except that the remote
269                                     procedure's output is decoded there; addr
270                                     points to the address of the machine that
271                                     sent the results. If eachresult() returns
272                                     0.   clnt_broadcast()   waits   for  more
273                                     replies; otherwise it returns with appro‐
274                                     priate  status.  If eachresult() is NULL,
275                                     clnt_broadcast() returns without  waiting
276                                     for any replies.
277
278                                     Broadcast  packets are limited in size to
279                                     the maximum transfer unit of  the  trans‐
280                                     ports involved. For Ethernet, the callers
281                                     argument  size  is   approximately   1500
282                                     bytes.  Since the call message is sent to
283                                     all connected  networks,  it  may  poten‐
284                                     tially    lead   to   broadcast   storms.
285                                     clnt_broadcast() uses SB AUTH_SYS creden‐
286                                     tials        by        default.       See
287                                     rpc_clnt_auth(3NSL). This routine  exists
288                                     for  backward  compatibility only, and is
289                                     made  obsolete  by  rpc_broadcast().  See
290                                     rpc_clnt_calls(3NSL).
291
292
293       clntraw_create()              This routine creates an internal, memory-
294                                     based RPC client for the  remote  program
295                                     prognum,  version  versnum. The transport
296                                     used to pass messages to the  service  is
297                                     actually  a  buffer  within the process's
298                                     address space, so the  corresponding  RPC
299                                     server  should  live  in the same address
300                                     space. See svcraw_create().  This  allows
301                                     simulation  of RPC and acquisition of RPC
302                                     overheads,  such  as  round  trip  times,
303                                     without  any  kernel  interference.  This
304                                     routine returns NULL if it fails.
305
306                                     This routine exists for backward compati‐
307                                     bility  only. It has the same functional‐
308                                     ity     as     clnt_raw_create().     See
309                                     rpc_clnt_create(3NSL),   which  obsoletes
310                                     it.
311
312
313       clnttcp_create()              This routine creates an  RPC  client  for
314                                     the  remote program prognum, version ver‐
315                                     snum; the client uses TCP/IP as a  trans‐
316                                     port.  The  remote  program is located at
317                                     Internet address addr. If  addr->sin_port
318                                     is   0, then it is set to the actual port
319                                     that the remote program is listening  on.
320                                     The  remote  rpcbind service is consulted
321                                     for this information. The parameter  *fdp
322                                     is  a  file descriptor, which may be open
323                                     and bound; if  it  is  RPC_ANYSOCK,  then
324                                     this  routine  opens  a  new one and sets
325                                     *fdp. Refer to the File  Descriptor  sec‐
326                                     tion  for  more  information.  Since TCP-
327                                     based RPC uses buffered I/O, the user may
328                                     specify  the size of the send and receive
329                                     buffers with the  parameters  sendsz  and
330                                     recvsz.  Values  of   0  choose  suitable
331                                     defaults. This routine returns NULL if it
332                                     fails.
333
334                                     This routine exists for backward compati‐
335                                     bility only. clnt_create(), clnt_tli_cre‐
336                                     ate(), or clnt_vc_create() should be used
337                                     instead. See rpc_clnt_create(3NSL).
338
339
340       clntudp_bufcreate()           Create a client  handle  for  the  remote
341                                     program  prognum,  on versnum; the client
342                                     uses  UDP/IP as the transport. The remote
343                                     program   is   located  at  the  Internet
344                                     address addr. If addr->sin_port is  0, it
345                                     is  set to  port on which the remote pro‐
346                                     gram is listening on (the remote  rpcbind
347                                     service  is  consulted  for this informa‐
348                                     tion).  The  parameter  *fdp  is  a  file
349                                     descriptor,  which may be open and bound.
350                                     If it is RPC_ANYSOCK, then  this  routine
351                                     opens  a  new one and sets *fdp. Refer to
352                                     the  File  Descriptor  section  for  more
353                                     information.  The  UDP  transport resends
354                                     the call message  in  intervals  of  wait
355                                     time  until  a  response  is  received or
356                                     until the call times out. The total  time
357                                     for  the call to time out is specified by
358                                     clnt_call(). See rpc_clnt_calls(3NSL). If
359                                     successful  it  returns  a client handle,
360                                     otherwise it returns NULL. The error  can
361                                     be  printed using the clnt_pcreateerror()
362                                     routine. See rpc_clnt_create(3NSL).
363
364                                     The user can specify the  maximum  packet
365                                     size  for  sending and receiving by using
366                                     sendsz and recvsz arguments for UDP-based
367                                     RPC messages.
368
369                                     If addr->sin_port is  0 and the requested
370                                     version number versnum is not  registered
371                                     with   the  remote  portmap  service,  it
372                                     returns a handle if at  least  a  version
373                                     number  for  the  given program number is
374                                     registered.  The version mismatch is dis‐
375                                     covered   by  a  clnt_call()  later  (see
376                                     rpc_clnt_calls(3NSL)).
377
378                                     This routine exists for backward compati‐
379                                     bility    only.    clnt_tli_create()   or
380                                     clnt_dg_create() should be used  instead.
381                                     See rpc_clnt_create(3NSL).
382
383
384       clntudp_create()              This routine creates an RPC client handle
385                                     for the remote program  prognum,  version
386                                     versnum;  the  client  uses  UDP/IP  as a
387                                     transport. The remote program is  located
388                                     at     Internet    address    addr.    If
389                                     addr->sin_port is  0, then it is  set  to
390                                     actual  port  that  the remote program is
391                                     listening on. The remote rpcbind  service
392                                     is  consulted  for  this information. The
393                                     parameter  *fdp  is  a  file  descriptor,
394                                     which  may  be  open  and bound; if it is
395                                     RPC_ANYSOCK, then this  routine  opens  a
396                                     new  one and sets *fdp. Refer to the File
397                                     Descriptor section for more  information.
398                                     The  UDP  transport resends the call mes‐
399                                     sage in intervals of wait  time  until  a
400                                     response  is  received  or until the call
401                                     times out. The total time for the call to
402                                     time out is specified by clnt_call(). See
403                                     rpc_clnt_calls(3NSL).    clntudp_create()
404                                     returns  a client handle on success, oth‐
405                                     erwise it returns NULL. The error can  be
406                                     printed   using  the  clnt_pcreateerror()
407                                     routine. See rpc_clnt_create(3NSL).
408
409                                     Since UDP-based  RPC  messages  can  only
410                                     hold up to 8 Kbytes of encoded data, this
411                                     transport cannot be used  for  procedures
412                                     that  take large arguments or return huge
413                                     results.
414
415                                     This routine exists for backward compati‐
416                                     bility only. clnt_create(), clnt_tli_cre‐
417                                     ate(), or clnt_dg_create() should be used
418                                     instead. See rpc_clnt_create(3NSL).
419
420
421       get_myaddress()               Places the local system's IP address into
422                                     *addr,  without  consulting  the  library
423                                     routines  that  deal with /etc/hosts. The
424                                     port number is always set to  htons(PMAP‐
425                                     PORT).
426
427                                     This  routine  is  only  intended for use
428                                     with the  RPC  library.  It  returns  the
429                                     local system's address in a form compati‐
430                                     ble with the  RPC library, and should not
431                                     be   taken  as  the  system's  actual  IP
432                                     address. In fact, the *addr buffer's host
433                                     address  part  is  actually  zeroed. This
434                                     address may have only local  significance
435                                     and  should   not  be  assumed  to  be an
436                                     address that can be used  to  connect  to
437                                     the  local  system  by  remote systems or
438                                     processes.
439
440                                     This routine remains for backward compat‐
441                                     ibility  only.  The routine netdir_getby‐
442                                     name()  should  be  used  with  the  name
443                                     HOST_SELF  to retrieve the local system's
444                                     network address as  a  netbuf  structure.
445                                     See netdir(3NSL).
446
447
448       getrpcport()                  getrpcport()  returns the port number for
449                                     the version versnum of the   RPC  program
450                                     prognum  running on host and using proto‐
451                                     col proto. getrpcport() returns  0 if the
452                                     RPC  system failed to contact  the remote
453                                     portmap service, the  program  associated
454                                     with  prognum is not registered, or there
455                                     is no mapping between the program  and  a
456                                     port.
457
458                                     This routine exists for backward compati‐
459                                     bility only.  Enhanced  functionality  is
460                                     provided     by    rpcb_getaddr().    See
461                                     rpcbind(3NSL).
462
463
464       pmaplist()                    A user interface to the portmap  service,
465                                     which  returns  a list of the current RPC
466                                     program-to-port  mappings  on  the   host
467                                     located  at IP address addr. This routine
468                                     can return NULL . The command `rpcinfo-p'
469                                     uses this routine.
470
471                                     This routine exists for backward compati‐
472                                     bility only,  enhanced  functionality  is
473                                     provided     by    rpcb_getmaps().    See
474                                     rpcbind(3NSL).
475
476
477       pmap_getport()                A user interface to the portmap  service,
478                                     which  returns  the  port number on which
479                                     waits a  service  that  supports  program
480                                     prognum,  version versnum, and speaks the
481                                     transport protocol associated with proto‐
482                                     col. The value of protocol is most likely
483                                     IPPROTO_UDP  or  IPPROTO_TCP.  A   return
484                                     value  of   0 means that the mapping does
485                                     not exist or that the RPC system failured
486                                     to  contact  the  remote portmap service.
487                                     In the latter case, the  global  variable
488                                     rpc_createerr contains the  RPC status.
489
490                                     This routine exists for backward compati‐
491                                     bility only,  enhanced  functionality  is
492                                     provided     by    rpcb_getaddr().    See
493                                     rpcbind(3NSL).
494
495
496       pmap_rmtcall()                Request that the portmap on the  host  at
497                                     IP  address  *addr  make  an  RPC  on the
498                                     behalf of the caller to  a  procedure  on
499                                     that host. *portp is modified to the pro‐
500                                     gram's port number if the procedure  suc‐
501                                     ceeds.  The  definitions of other parame‐
502                                     ters  are  discussed  in  callrpc()   and
503                                     clnt_call(). See rpc_clnt_calls(3NSL).
504
505                                     This  procedure is only available for the
506                                     UDP transport.
507
508                                     If the requested remote procedure is  not
509                                     registered  with  the remote portmap then
510                                     no error response  is  returned  and  the
511                                     call  times  out. Also, no authentication
512                                     is done.
513
514                                     This routine exists for backward compati‐
515                                     bility  only,  enhanced  functionality is
516                                     provided    by    rpcb_rmtcall().     See
517                                     rpcbind(3NSL).
518
519
520       pmap_set()                    A  user interface to the portmap service,
521                                     that establishes a  mapping  between  the
522                                     triple  [prognum,  versnum, protocol] and
523                                     port on the  machine's  portmap  service.
524                                     The  value of protocol may be IPPROTO_UDP
525                                     or  IPPROTO_TCP.  Formerly,  the  routine
526                                     failed if the requested port was found to
527                                     be in use.  Now, the routine  only  fails
528                                     if it finds that port is still bound.  If
529                                     port is not bound, the routine  completes
530                                     the requested registration.  This routine
531                                     returns  1 if it succeeds,  0  otherwise.
532                                     Automatically done by svc_register().
533
534                                     This routine exists for backward compati‐
535                                     bility only,  enhanced  functionality  is
536                                     provided      by      rpcb_set().     See
537                                     rpcbind(3NSL).
538
539
540       pmap_unset()                  A user interface to the portmap  service,
541                                     which  destroys  all  mapping between the
542                                     triple [prognum, versnum,  all-protocols]
543                                     and  port  on  the machine's portmap ser‐
544                                     vice.  This routine  returns  one  if  it
545                                     succeeds,  0 otherwise.
546
547                                     This routine exists for backward compati‐
548                                     bility only,  enhanced  functionality  is
549                                     provided     by     rpcb_unset().     See
550                                     rpcbind(3NSL).
551
552
553       svc_fds()                     A global variable reflecting the RPC ser‐
554                                     vice  side's  read  file  descriptor  bit
555                                     mask; it is suitable as  a  parameter  to
556                                     the select() call. This is only of inter‐
557                                     est if a  service  implementor  does  not
558                                     call  svc_run(),  but rather does his own
559                                     asynchronous event processing. This vari‐
560                                     able  is  read-only  ,  yet it may change
561                                     after calls to svc_getreq() or  any  cre‐
562                                     ation  routines.  Do not pass its address
563                                     to select()! Similar  to  svc_fdset,  but
564                                     limited to 32 descriptors.
565
566                                     This   interface   is  made  obsolete  by
567                                     svc_fdset. See rpc_svc_calls(3NSL).
568
569
570       svc_getcaller()               This routine returns the network address,
571                                     represented  as  a struct sockaddr_in, of
572                                     the caller of a procedure associated with
573                                     the RPC service transport handle, xprt.
574
575                                     This routine exists for backward compati‐
576                                     bility only, and is obsolete.   The  pre‐
577                                     ferred  interface  is svc_getrpccaller().
578                                     See rpc_svc_reg(3NSL), which returns  the
579                                     address as a struct netbuf.
580
581
582       svc_getreq()                  This  routine  is  only  of interest if a
583                                     service   implementor   does   not   call
584                                     svc_run(),  but instead implements custom
585                                     asynchronous  event  processing.  It   is
586                                     called  when the select() call has deter‐
587                                     mined that an RPC request has arrived  on
588                                     some  RPC  file descriptors; rdfds is the
589                                     resultant read file descriptor bit  mask.
590                                     The   routine   returns   when  all  file
591                                     descriptors associated with the value  of
592                                     rdfds have been serviced. This routine is
593                                     similar to svc_getreqset() but is limited
594                                     to 32 descriptors.
595
596                                     This   interface   is  made  obsolete  by
597                                     svc_getreqset()
598
599
600       svcfd_create()                Create a service on top of any  open  and
601                                     bound    descriptor.    Typically,   this
602                                     descriptor is a connected file descriptor
603                                     for  a stream protocol. Refer to the File
604                                     Descriptor section for more  information.
605                                     sendsz  and recvsz indicate sizes for the
606                                     send and receive buffers. If they are  0,
607                                     a reasonable default is chosen.
608
609                                     This   interface   is  made  obsolete  by
610                                     svc_fd_create()     (see     rpc_svc_cre‐
611                                     ate(3NSL)).
612
613
614       svcraw_create()               This routine creates an internal, memory-
615                                     based RPC service transport, to which  it
616                                     returns   a  pointer.  The  transport  is
617                                     really  a  buffer  within  the  process's
618                                     address  space,  so the corresponding RPC
619                                     client should live in  the  same  address
620                                     space; see clntraw_create(). This routine
621                                     allows simulation of RPC and  acquisition
622                                     of  RPC  overheads  (such  as  round trip
623                                     times), without any kernel  interference.
624                                     This routine returns NULL if it fails.
625
626                                     This routine exists for backward compati‐
627                                     bility only, and has the same functional‐
628                                     ity of svc_raw_create(). See rpc_svc_cre‐
629                                     ate(3NSL), which obsoletes it.
630
631
632       svctcp_create()               This routine creates a  TCP/IP-based  RPC
633                                     service  transport, to which it returns a
634                                     pointer. The transport is associated with
635                                     the  file  descriptor  fd,  which  may be
636                                     RPC_ANYSOCK, in which  case  a  new  file
637                                     descriptor   is   created.  If  the  file
638                                     descriptor is not bound to  a  local  TCP
639                                     port,  then  this  routine binds it to an
640                                     arbitrary  port.  Refer   to   the   File
641                                     Descriptor  section for more information.
642                                     Upon  completion,  xprt->xp_fd   is   the
643                                     transport's    file    descriptor,    and
644                                     xprt->xp_port  is  the  transport's  port
645                                     number.  This  routine returns NULL if it
646                                     fails. Since TCP-based RPC uses  buffered
647                                     I/O,  users  may specify the size of buf‐
648                                     fers;  values  of   0   choose   suitable
649                                     defaults.
650
651                                     This routine exists for backward compati‐
652                                     bility only.  svc_create(),  svc_tli_cre‐
653                                     ate(),  or svc_vc_create() should be used
654                                     instead. See rpc_svc_create(3NSL).
655
656
657       svcudp_bufcreate()            This routine creates a  UDP/IP-based  RPC
658                                     service  transport, to which it returns a
659                                     pointer. The transport is associated with
660                                     the   file   descriptor   fd.  If  fd  is
661                                     RPC_ANYSOCK then a new file descriptor is
662                                     created.  If  the  file descriptor is not
663                                     bound to a local UDP port, then this rou‐
664                                     tine  binds it to an arbitrary port. Upon
665                                     completion, xprtxp_fd is the  transport's
666                                     file descriptor, and xprt->xp_port is the
667                                     transport's port  number.  Refer  to  the
668                                     File Descriptor section for more informa‐
669                                     tion. This routine  returns  NULL  if  it
670                                     fails.
671
672                                     The  user  specifies  the  maximum packet
673                                     size for sending and  receiving UDP-based
674                                     RPC  messages  by  using  the  sendsz and
675                                     recvsz parameters.
676
677                                     This routine exists for backward compati‐
678                                     bility    only.    svc_tli_create(),   or
679                                     svc_dg_create() should be  used  instead.
680                                     See rpc_svc_create(3NSL).
681
682
683       svcudp_create()               This  routine  creates a UDP/IP-based RPC
684                                     service transport, to which it returns  a
685                                     pointer. The transport is associated with
686                                     the file  descriptor  fd,  which  may  be
687                                     RPC_ANYSOCK,  in  which  case  a new file
688                                     descriptor  is  created.  If   the   file
689                                     descriptor  is  not  bound to a local UDP
690                                     port, then this routine binds  it  to  an
691                                     arbitrary    port.    Upon    completion,
692                                     xprt->xp_fd  is  the   transport's   file
693                                     descriptor,  and  xprt->xp_port   is  the
694                                     transport's  port  number.  This  routine
695                                     returns NULL if it fails.
696
697                                     Since  UDP-based  RPC  messages  can only
698                                     hold up to 8 Kbytes of encoded data, this
699                                     transport  cannot  be used for procedures
700                                     that take large arguments or return  huge
701                                     results.
702
703                                     This routine exists for backward compati‐
704                                     bility only.  svc_create(),  svc_tli_cre‐
705                                     ate(),  or svc_dg_create() should be used
706                                     instead. See rpc_svc_create(3NSL).
707
708
709       registerrpc()                 Register program prognum, procedure proc‐
710                                     name,  and  version  versnum with the RPC
711                                     service package. If a request arrives for
712                                     program  prognum,  version  versnum,  and
713                                     procedure  procnum,  procname  is  called
714                                     with a pointer to its parameter(s). proc‐
715                                     name  should  return  a  pointer  to  its
716                                     static   result(s).  inproc  is  used  to
717                                     decode the parameters  while  outproc  is
718                                     used  to encode the results. This routine
719                                     returns  0 if the registration succeeded,
720                                     −1 otherwise.
721
722                                     svc_run()  must  be  called after all the
723                                     services are registered.
724
725                                     This routine exists for backward compati‐
726                                     bility  only,  and it is made obsolete by
727                                     rpc_reg().
728
729
730       svc_register()                Associates prognum and versnum  with  the
731                                     service  dispatch procedure, dispatch. If
732                                     protocol is  0, the service is not regis‐
733                                     tered with the portmap service. If proto‐
734                                     col is non-zero,  then a mapping  of  the
735                                     triple  [prognum,  versnum,  protocol] to
736                                     xprt->xp_port  is  established  with  the
737                                     local portmap service (generally protocol
738                                     is  0, IPPROTO_UDP or  IPPROTO_TCP).  The
739                                     procedure   dispatch  has  the  following
740                                     form:
741
742                                       dispatch(struct svc_req *request, SVCXPRT *xprt);
743
744                                     The svc_register() routine returns one if
745                                     it succeeds,  and  0 otherwise.
746
747                                     This routine exists for backward compati‐
748                                     bility only.  Enhanced  functionality  is
749                                     provided by svc_reg().
750
751
752       svc_unregister()              Remove   all   mapping   of   the  double
753                                     [prognum, versnum] to dispatch  routines,
754                                     and of the triple [prognum, versnum, all-
755                                     protocols] to port number from portmap.
756
757                                     This routine exists for backward compati‐
758                                     bility.  Enhanced  functionality  is pro‐
759                                     vided by svc_unreg().
760
761
762       xdr_authunix_parms()          Used  for  describing  UNIX  credentials.
763                                     This routine is useful for users who wish
764                                     to  generate  these  credentials  without
765                                     using the RPC authentication package.
766
767                                     This routine exists for backward compati‐
768                                     bility only,  and  is  made  obsolete  by
769                                     xdr_authsys_parms(). See rpc_xdr(3NSL).
770
771

ATTRIBUTES

773       See attributes(5) for descriptions of the following attributes:
774
775
776
777
778       ┌─────────────────────────────┬─────────────────────────────┐
779       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
780       ├─────────────────────────────┼─────────────────────────────┤
781       │MT-Level                     │Unsafe                       │
782       └─────────────────────────────┴─────────────────────────────┘
783

SEE ALSO

785       keyserv(1M),   rpcbind(1M),  rpcinfo(1M),  netdir(3NSL),  netdir_getby‐
786       name(3NSL),   rpc(3NSL),   rpc_clnt_auth(3NSL),   rpc_clnt_calls(3NSL),
787       rpc_clnt_create(3NSL),    rpc_svc_calls(3NSL),    rpc_svc_create(3NSL),
788       rpc_svc_err(3NSL),  rpc_svc_reg(3NSL),  rpc_xdr(3NSL),   rpcbind(3NSL),
789       secure_rpc(3NSL),  select(3C),  xdr_authsys_parms(3NSL),  libnsl(3LIB),
790       librpcsoc(3LIBUCB), attributes(5)
791

NOTES

793       These interfaces are  unsafe  in  multithreaded  applications.   Unsafe
794       interfaces should be called only from the main thread.
795
796
797
798SunOS 5.11                        7 Jun 2001                     rpc_soc(3NSL)
Impressum