MyWebUniversity.com Home Page
 



OpenSolaris man pages main menu


Networking Services Library Functions               rpcsoc(3NSL)



NAME
     rpcsoc,          authdescreate,           authunixcreate,
     authunixcreatedefault,       callrpc,      clntbroadcast,
     clntrawcreate,      clnttcpcreate,      clntudpbufcreate,
     clntudpcreate,   getmyaddress,  getrpcport,  pmapgetmaps,
     pmapgetport,    pmaprmtcall,     pmapset,     pmapunset,
     registerrpc,     svcfds,     svcgetcaller,     svcgetreq,
     svcregister, svcunregister,  svcfdcreate,  svcrawcreate,
     svctcpcreate,        svcudpbufcreate,       svcudpcreate,
     xdrauthunixparms - obsolete library routines for RPC

SYNOPSIS
     #define PORTMAP
     #include 


     AUTH *authdescreate(char *name, uintt window,
          struct sockaddrin *syncaddr, desblock *ckey);


     AUTH *authunixcreate(char *host, uidt uid, gidt gid,
          int grouplen, gidt *gidlistp);


     AUTH *authunixcreatedefault(void)


     callrpc(char *host, rpcprogt prognum, rpcverst versnum,
          rpcproct procnum, xdrproct inproc, char *in,
          xdrproct outproc, char *out);


     enum clntstatclntbroadcast(rpcprogt prognum, rpcverst versnum,
          rpcproct procnum, xdrproct inproc, char *in,
          xdrproct outproc, char *out, resultprocteachresult);


     CLIENT *clntrawcreate(rpcproct procnum, rpcverst versnum);


     CLIENT *clnttcpcreate(struct sockaddrin *addr,
          rpcprogt prognum, rpcverst versnum, int *fdp,
          uintt sendz, uintt recvsz);


     CLIENT *clntudpbufcreate(struct sockaddrin *addr, rpcprogt prognum,
          rpcverst versnum, struct timeval wait,
          int *fdp, uintt sendz, uintt recvsz);


     CLIENT *clntudpcreate(struct sockaddrin *addr,
          rpcprogt prognum, struct timeval wait, int *fdp);



SunOS 5.11           Last change: 7 Jun 2001                    1






Networking Services Library Functions               rpcsoc(3NSL)



     void getmyaddress(struct sockaddrin *addr);


     ushort getrpcport(char *host, rpcprogt prognum,
          rpcverst versnum, rpcprott proto);


     struct pmaplist *pmapgetmaps(struct sockaddrin *addr);


     ushort pmapgetport(struct sockaddrin *addr,
          rpcprogt prognum, rpcverst versnum,
          rpcprott protocol);


     enum clntstat pmaprmtcall(struct sockaddrin *addr,
          rpcprogt prognum, rpcverst versnum,
          rpcproct progcnum, caddrt in, xdrproctt inproc,
          caddrt out, cdrproctt outproc,
          struct timeval tout, rpcportt *portp);


     boolt pmapset(rpcprogt prognum, rpcverst versnum,
          rpcprott protocol, ushort port);


     boolt pmapunset(rpcprogt prognum, rpcverst versnum);


     int svcfds;


     struct sockaddrin *svcgetcaller(SVCXPRT *xprt);


     void svcgetreq(int rdfds);


     SVCXPRT *svcfdcreate(int fd, uintt sendsz,
          uintt recvsz);


     SVCXPRT *svcrawcreate(void)


     SVCXPRT *svctcpcreate(int fd, uintt sendsz,
          uintt recvsz);


     SVCXPRT *svcudpbufcreate(int fd, uintt sendsz,
          uintt recvsz);




SunOS 5.11           Last change: 7 Jun 2001                    2






Networking Services Library Functions               rpcsoc(3NSL)



     SVCXPRT *svcudpcreate(int fd);


     registerrpc(rpcprogt prognum, rpcverst versnum, rpcproct procnum,
          char *(*procname)(), xdrproct inproc, xdrproct outproc);


     booltsvcregister(SVCXPRT *xprt, rpcprogt prognum, rpcverst versnum,
          void (*dispatch(), int protocol);


     void svcunregister(rpcprogt prognum, rpcverst versnum);


     boolt xdrauthunixparms(XDR *xdrs, struct authunixparms *supp);


DESCRIPTION
     RPC routines allow C programs to  make  procedure  calls  on
     other machines across the network. First, the client calls a
     procedure to send a request to the server. Upon  receipt  of
     the  request, the server calls a dispatch routine to perform
     the requested service, and then sends back a reply. Finally,
     the procedure call returns to the client.


     The routines described in this manual page have been  super-
     seded  by  other  routines.  The  preferred routine is given
     after the description of the routine.  New  programs  should
     use  the preferred routines, as support for the older inter-
     faces may be dropped in future releases.

  File Descriptors
     Transport independent  RPC uses  TLI as its transport inter-
     face instead of sockets.


     Some of the routines described  in  this  section  (such  as
     clnttcpcreate()) take a pointer to a file descriptor as one
     of the parameters. If the user wants the file descriptor  to
     be  a  socket,  then  the application will have to be linked
     with  both   librpcsoc  and  libnsl.  If  the  user   passed
     RPCANYSOCK  as  the file descriptor, and the application is
     linked with libnsl only, then the routine will return a  TLI
     file descriptor and not a socket.

  Routines
     The following routines require that the  header  
     be  included.  The  symbol PORTMAP should be defined so that
     the appropriate function declarations for the old interfaces
     are included through the header files.




SunOS 5.11           Last change: 7 Jun 2001                    3






Networking Services Library Functions               rpcsoc(3NSL)



     authdescreate()              authdescreate() is the  first
                                   of  two  routines which inter-
                                   face to the RPC secure authen-
                                   tication  system, known as DES
                                   authentication. The second  is
                                   authdesgetucred(),     below.
                                   Note:  the  keyserver   daemon
                                   keyserv(1M)  must  be  running
                                   for  the  DES   authentication
                                   system to work.

                                   authdescreate(), used on  the
                                   client   side,    returns   an
                                   authentication   handle   that
                                   will  enable  the  use  of the
                                   secure authentication  system.
                                   The  first  parameter  name is
                                   the network name, or  netname,
                                   of  the  owner  of  the server
                                   process.  This  field  usually
                                   represents  a hostname derived
                                   from   the   utility   routine
                                   host2netname(), but could also
                                   represent a  user  name  using
                                   user2netname().            See
                                   securerpc(3NSL).  The  second
                                   field  is  window on the vali-
                                   dity of the client credential,
                                   given  in  seconds.    A small
                                   window is more secure  than  a
                                   large  one,   but choosing too
                                   small   of   a   window   will
                                   increase   the   frequency  of
                                   resynchronizations because  of
                                   clock drift.  The third param-
                                   eter  syncaddr  is   optional.
                                   If   it   is  NUL,  then  the
                                   authentication   system   will
                                   assume that the local clock is
                                   always  in   sync   with   the
                                   server's  clock,  and will not
                                   attempt resynchronizations. If
                                   an  address  is supplied, how-
                                   ever, then the system will use
                                   the address for consulting the
                                   remote time  service  whenever
                                   resynchronization is required.
                                   This parameter is usually  the
                                   address   of  the  RPC  server
                                   itself.  The  final  parameter
                                   ckey  is  also optional. If it
                                   is     NUL,     then      the



SunOS 5.11           Last change: 7 Jun 2001                    4






Networking Services Library Functions               rpcsoc(3NSL)



                                   authentication   system   will
                                   generate a random DES  key  to
                                   be  used for the encryption of
                                   credentials.  If  it  is  sup-
                                   plied,  however,  then it will
                                   be used instead.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   it   is   made   obsolete   by
                                   authdesseccreate().       See
                                   securerpc(3NSL).


     authunixcreate()             Create  and  return   an   RPC
                                   authentication   handle   that
                                   contains  .UX   authentication
                                   information.   The   parameter
                                   host  is  the  name   of   the
                                   machine  on which the informa-
                                   tion was created; uid  is  the
                                   user's  user  ID;  gid  is the
                                   user's   current   group   ID;
                                   grouplen and gidlistp refer to
                                   a counted array of  groups  to
                                   which the user belongs.

                                   It is not  very  difficult  to
                                   impersonate a user.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   it   is   made   obsolete   by
                                   authsyscreate().          See
                                   rpcclntauth(3NSL).


     authunixcreatedefault()     Call  authunixcreate()   with
                                   the appropriate parameters.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   it   is   made   obsolete   by
                                   authsyscreatedefault().  See
                                   rpcclntauth(3NSL).


     callrpc()                     Call  the   remote   procedure
                                   associated with prognum, vers-
                                   num,  and   procnum   on   the
                                   machine,  host.  The parameter
                                   inproc is used to  encode  the



SunOS 5.11           Last change: 7 Jun 2001                    5






Networking Services Library Functions               rpcsoc(3NSL)



                                   procedure's   parameters,  and
                                   outproc is used to decode  the
                                   procedure's results; in is the
                                   address  of  the   procedure's
                                   argument,   and   out  is  the
                                   address of where to place  the
                                   result(s).     This    routine
                                   returns  0 if it succeeds,  or
                                   the  value  of  enum clntstat
                                   cast  to  an  integer  if   it
                                   fails.       The       routine
                                   clntperrno()  is  handy   for
                                   translating  failure  statuses
                                   into       messages.       See
                                   rpcclntcalls(3NSL).

                                   You do  not  have  control  of
                                   timeouts   or   authentication
                                   using this routine. This  rou-
                                   tine  exists for backward com-
                                   patibility only, and  is  made
                                   obsolete  by  rpccall().  See
                                   rpcclntcalls(3NSL).


     clntstatclntbroadcast()    Like  callrpc(),  except   the
                                   call  message  is broadcast to
                                   all locally  connected  broad-
                                   cast   nets.   Each  time  the
                                   caller  receives  a  response,
                                   this       routine       calls
                                   eachresult(), whose form is:

                                     eachresult(char *out, struct sockaddrin *addr);

                                   where out is the same  as  out
                                   passed   to  clntbroadcast(),
                                   except   that    the    remote
                                   procedure's  output is decoded
                                   there;  addr  points  to   the
                                   address  of  the  machine that
                                   sent    the    results.     If
                                   eachresult()    returns     0.
                                   clntbroadcast()   waits   for
                                   more   replies;  otherwise  it
                                   returns    with    appropriate
                                   status.   If  eachresult()  is
                                   NUL, clntbroadcast() returns
                                   without    waiting   for   any
                                   replies.

                                   Broadcast packets are  limited



SunOS 5.11           Last change: 7 Jun 2001                    6






Networking Services Library Functions               rpcsoc(3NSL)



                                   in   size   to   the   maximum
                                   transfer  unit  of  the  tran-
                                   sports involved. For Ethernet,
                                   the callers argument  size  is
                                   approximately    1500   bytes.
                                   Since the call message is sent
                                   to  all connected networks, it
                                   may potentially lead to broad-
                                   cast  storms. clntbroadcast()
                                   uses SB  AUTHSYS  credentials
                                   by         default.        See
                                   rpcclntauth(3NSL). This rou-
                                   tine  exists for backward com-
                                   patibility only, and  is  made
                                   obsolete  by  rpcbroadcast().
                                   See rpcclntcalls(3NSL).


     clntrawcreate()              This routine creates an inter-
                                   nal,  memory-based  RPC client
                                   for the remote  program  prog-
                                   num,   version   versnum.  The
                                   transport used  to  pass  mes-
                                   sages  to the service is actu-
                                   ally  a  buffer   within   the
                                   process's  address  space,  so
                                   the corresponding  RPC  server
                                   should   live   in   the  same
                                   address       space.       See
                                   svcrawcreate().  This  allows
                                   simulation of RPC and acquisi-
                                   tion of RPC overheads, such as
                                   round trip times, without  any
                                   kernel interference. This rou-
                                   tine returns NUL if it fails.

                                   This routine exists for  back-
                                   ward  compatibility  only.  It
                                   has the same functionality  as
                                   clntrawcreate().         See
                                   rpcclntcreate(3NSL),   which
                                   obsoletes it.


     clnttcpcreate()              This routine  creates  an  RPC
                                   client  for the remote program
                                   prognum, version versnum;  the
                                   client  uses TCP/IP as a tran-
                                   sport. The remote  program  is
                                   located  at  Internet  address
                                   addr. If addr->sinport is  0,
                                   then  it  is set to the actual



SunOS 5.11           Last change: 7 Jun 2001                    7






Networking Services Library Functions               rpcsoc(3NSL)



                                   port that the  remote  program
                                   is  listening  on.  The remote
                                   rpcbind service  is  consulted
                                   for   this   information.  The
                                   parameter  *fdp  is   a   file
                                   descriptor,  which may be open
                                   and   bound;    if    it    is
                                   RPCANYSOCK, then this routine
                                   opens a new one and sets *fdp.
                                   Refer  to  the File Descriptor
                                   section for more  information.
                                   Since  TCP-based RPC uses buf-
                                   fered  I/O,   the   user   may
                                   specify  the  size of the send
                                   and receive buffers  with  the
                                   parameters  sendsz and recvsz.
                                   Values of  0  choose  suitable
                                   defaults. This routine returns
                                   NUL if it fails.

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   clntcreate(),
                                   clnttlicreate(),          or
                                   clntvccreate()   should   be
                                   used        instead.       See
                                   rpcclntcreate(3NSL).


     clntudpbufcreate()           Create a client handle for the
                                   remote   program  prognum,  on
                                   versnum;   the   client   uses
                                   UDP/IP  as  the transport. The
                                   remote program is  located  at
                                   the  Internet address addr. If
                                   addr->sinport is   0,  it  is
                                   set  to   port  on  which  the
                                   remote program is listening on
                                   (the remote rpcbind service is
                                   consulted  for  this  informa-
                                   tion). The parameter *fdp is a
                                   file descriptor, which may  be
                                   open   and  bound.  If  it  is
                                   RPCANYSOCK, then this routine
                                   opens a new one and sets *fdp.
                                   Refer to the  File  Descriptor
                                   section  for more information.
                                   The UDP transport resends  the
                                   call  message  in intervals of
                                   wait time until a response  is
                                   received  or  until  the  call
                                   times out. The total time  for



SunOS 5.11           Last change: 7 Jun 2001                    8






Networking Services Library Functions               rpcsoc(3NSL)



                                   the call to time out is speci-
                                   fied   by   clntcall().   See
                                   rpcclntcalls(3NSL).  If suc-
                                   cessful it  returns  a  client
                                   handle,  otherwise  it returns
                                   NUL. The error can be printed
                                   using  the clntpcreateerror()
                                   routine.                   See
                                   rpcclntcreate(3NSL).

                                   The user can specify the  max-
                                   imum  packet  size for sending
                                   and receiving by using  sendsz
                                   and  recvsz arguments for UDP-
                                   based RPC messages.

                                   If addr->sinport  is   0  and
                                   the  requested  version number
                                   versnum is not registered with
                                   the remote portmap service, it
                                   returns a handle if at least a
                                   version  number  for the given
                                   program number is  registered.
                                   The    version   mismatch   is
                                   discovered  by  a  clntcall()
                                   later                     (see
                                   rpcclntcalls(3NSL)).

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   clnttlicreate()           or
                                   clntdgcreate()   should   be
                                   used       instead.        See
                                   rpcclntcreate(3NSL).


     clntudpcreate()              This routine  creates  an  RPC
                                   client  handle  for the remote
                                   program prognum, version vers-
                                   num; the client uses UDP/IP as
                                   a transport. The  remote  pro-
                                   gram  is  located  at Internet
                                   address   addr.    If    addr-
                                   >sinport  is   0,  then it is
                                   set to actual  port  that  the
                                   remote  program  is  listening
                                   on. The remote rpcbind service
                                   is consulted for this informa-
                                   tion. The parameter *fdp is  a
                                   file  descriptor, which may be
                                   open  and  bound;  if  it   is
                                   RPCANYSOCK, then this routine



SunOS 5.11           Last change: 7 Jun 2001                    9






Networking Services Library Functions               rpcsoc(3NSL)



                                   opens a new one and sets *fdp.
                                   Refer  to  the File Descriptor
                                   section for more  information.
                                   The  UDP transport resends the
                                   call message in  intervals  of
                                   wait  time until a response is
                                   received  or  until  the  call
                                   times  out. The total time for
                                   the call to time out is speci-
                                   fied   by   clntcall().   See
                                   rpcclntcalls(3NSL).
                                   clntudpcreate()   returns   a
                                   client handle on success, oth-
                                   erwise  it  returns  NUL. The
                                   error can be printed using the
                                   clntpcreateerror()   routine.
                                   See rpcclntcreate(3NSL).

                                   Since UDP-based  RPC  messages
                                   can  only  hold up to 8 Kbytes
                                   of encoded  data,  this  tran-
                                   sport  cannot be used for pro-
                                   cedures that take large  argu-
                                   ments or return huge results.

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   clntcreate(),
                                   clnttlicreate(),          or
                                   clntdgcreate()   should   be
                                   used        instead.       See
                                   rpcclntcreate(3NSL).


     getmyaddress()               Places the local  system's  IP
                                   address  into  *addr,  without
                                   consulting  the  library  rou-
                                   tines     that    deal    with
                                   /etc/hosts. The port number is
                                   always set to htons(PMAPORT).

                                   This routine is only  intended
                                   for use with the  RPC library.
                                   It returns the local  system's
                                   address  in  a form compatible
                                   with  the   RPC  library,  and
                                   should  not  be  taken  as the
                                   system's actual IP address. In
                                   fact,  the *addr buffer's host
                                   address   part   is   actually
                                   zeroed.  This address may have
                                   only  local  significance  and



SunOS 5.11           Last change: 7 Jun 2001                   10






Networking Services Library Functions               rpcsoc(3NSL)



                                   should   not  be assumed to be
                                   an address that can be used to
                                   connect to the local system by
                                   remote systems or processes.

                                   This routine remains for back-
                                   ward  compatibility  only. The
                                   routine     netdirgetbyname()
                                   should  be  used with the name
                                   HOSTSELF  to   retrieve   the
                                   local system's network address
                                   as  a  netbuf  structure.  See
                                   netdir(3NSL).


     getrpcport()                  getrpcport() returns the  port
                                   number for the version versnum
                                   of the   RPC  program  prognum
                                   running on host and using pro-
                                   tocol   proto.    getrpcport()
                                   returns   0 if the  RPC system
                                   failed to contact  the  remote
                                   portmap  service,  the program
                                   associated with prognum is not
                                   registered,  or  there  is  no
                                   mapping  between  the  program
                                   and a port.

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   Enhanced functionality is pro-
                                   vided  by  rpcbgetaddr(). See
                                   rpcbind(3NSL).


     pmaplist()                    A user interface to the  port-
                                   map  service,  which returns a
                                   list  of   the   current   RPC
                                   program-to-port   mappings  on
                                   the host located at IP address
                                   addr.  This routine can return
                                   NUL . The command `rpcinfo-p'
                                   uses this routine.

                                   This routine exists for  back-
                                   ward    compatibility    only,
                                   enhanced functionality is pro-
                                   vided  by  rpcbgetmaps(). See
                                   rpcbind(3NSL).






SunOS 5.11           Last change: 7 Jun 2001                   11






Networking Services Library Functions               rpcsoc(3NSL)



     pmapgetport()                A user interface to the  port-
                                   map  service,   which  returns
                                   the port number on which waits
                                   a  service  that supports pro-
                                   gram  prognum,  version  vers-
                                   num,  and speaks the transport
                                   protocol associated with  pro-
                                   tocol.  The  value of protocol
                                   is most likely IPROTOUDP  or
                                   IPROTOTCP. A return value of
                                   0 means that the mapping  does
                                   not exist or that the RPC sys-
                                   tem failured  to  contact  the
                                   remote  portmap  service.   In
                                   the latter  case,  the  global
                                   variable   rpccreateerr  con-
                                   tains the  RPC status.

                                   This routine exists for  back-
                                   ward    compatibility    only,
                                   enhanced functionality is pro-
                                   vided  by  rpcbgetaddr(). See
                                   rpcbind(3NSL).


     pmaprmtcall()                Request that  the  portmap  on
                                   the  host  at IP address *addr
                                   make an RPC on the  behalf  of
                                   the  caller  to a procedure on
                                   that host. *portp is  modified
                                   to  the  program's port number
                                   if the procedure succeeds. The
                                   definitions  of  other parame-
                                   ters    are    discussed    in
                                   callrpc() and clntcall(). See
                                   rpcclntcalls(3NSL).

                                   This procedure is only  avail-
                                   able for the UDP transport.

                                   If the requested  remote  pro-
                                   cedure  is not registered with
                                   the  remote  portmap  then  no
                                   error response is returned and
                                   the call times out.  Also,  no
                                   authentication is done.

                                   This routine exists for  back-
                                   ward    compatibility    only,
                                   enhanced functionality is pro-
                                   vided  by  rpcbrmtcall(). See
                                   rpcbind(3NSL).



SunOS 5.11           Last change: 7 Jun 2001                   12






Networking Services Library Functions               rpcsoc(3NSL)



     pmapset()                    A user interface to the  port-
                                   map service,  that establishes
                                   a mapping between  the  triple
                                   [prognum,  versnum,  protocol]
                                   and  port  on  the   machine's
                                   portmap service.  The value of
                                   protocol may be IPROTOUDP or
                                   IPROTOTCP.   Formerly,   the
                                   routine    failed    if    the
                                   requested port was found to be
                                   in use.  Now, the routine only
                                   fails if it finds that port is
                                   still bound.  If  port is  not
                                   bound,  the  routine completes
                                   the  requested   registration.
                                   This  routine returns  1 if it
                                   succeeds,     0     otherwise.
                                   Automatically      done     by
                                   svcregister().

                                   This routine exists for  back-
                                   ward    compatibility    only,
                                   enhanced functionality is pro-
                                   vided   by   rpcbset().   See
                                   rpcbind(3NSL).


     pmapunset()                  A user interface to the  port-
                                   map  service,   which destroys
                                   all mapping between the triple
                                   [prognum,     versnum,    all-
                                   protocols]  and  port  on  the
                                   machine's   portmap   service.
                                   This routine returns one if it
                                   succeeds,  0 otherwise.

                                   This routine exists for  back-
                                   ward    compatibility    only,
                                   enhanced functionality is pro-
                                   vided   by  rpcbunset().  See
                                   rpcbind(3NSL).


     svcfds()                     A global  variable  reflecting
                                   the  RPC  service  side's read
                                   file descriptor bit  mask;  it
                                   is  suitable as a parameter to
                                   the  select()  call.  This  is
                                   only  of interest if a service
                                   implementor  does   not   call
                                   svcrun(), but rather does his
                                   own     asynchronous     event



SunOS 5.11           Last change: 7 Jun 2001                   13






Networking Services Library Functions               rpcsoc(3NSL)



                                   processing.  This  variable is
                                   read-only , yet it may  change
                                   after calls to svcgetreq() or
                                   any creation routines. Do  not
                                   pass  its address to select()!
                                   Similar to svcfdset, but lim-
                                   ited to 32 descriptors.

                                   This   interface    is    made
                                   obsolete   by  svcfdset.  See
                                   rpcsvccalls(3NSL).


     svcgetcaller()               This routine returns the  net-
                                   work address, represented as a
                                   struct  sockaddrin,  of   the
                                   caller  of a procedure associ-
                                   ated  with  the  RPC   service
                                   transport handle, xprt.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   is  obsolete.   The  preferred
                                   interface                   is
                                   svcgetrpccaller().        See
                                   rpcsvcreg(3NSL),       which
                                   returns  the  address   as   a
                                   struct netbuf.


     svcgetreq()                  This  routine   is   only   of
                                   interest  if  a service imple-
                                   mentor    does    not     call
                                   svcrun(),  but instead imple-
                                   ments   custom    asynchronous
                                   event processing. It is called
                                   when  the  select()  call  has
                                   determined that an RPC request
                                   has arrived on some  RPC  file
                                   descriptors;   rdfds   is  the
                                   resultant read file descriptor
                                   bit  mask. The routine returns
                                   when  all   file   descriptors
                                   associated  with  the value of
                                   rdfds have been serviced. This
                                   routine    is    similar    to
                                   svcgetreqset() but is limited
                                   to 32 descriptors.

                                   This   interface    is    made
                                   obsolete by svcgetreqset()




SunOS 5.11           Last change: 7 Jun 2001                   14






Networking Services Library Functions               rpcsoc(3NSL)



     svcfdcreate()                Create a service on top of any
                                   open   and  bound  descriptor.
                                   Typically, this descriptor  is
                                   a  connected  file  descriptor
                                   for a stream  protocol.  Refer
                                   to the File Descriptor section
                                   for more  information.  sendsz
                                   and  recvsz indicate sizes for
                                   the send and receive  buffers.
                                   If  they  are  0, a reasonable
                                   default is chosen.

                                   This   interface    is    made
                                   obsolete   by  svcfdcreate()
                                   (see rpcsvccreate(3NSL)).


     svcrawcreate()               This routine creates an inter-
                                   nal,  memory-based RPC service
                                   transport, to which it returns
                                   a  pointer.  The  transport is
                                   really  a  buffer  within  the
                                   process's  address  space,  so
                                   the corresponding  RPC  client
                                   should   live   in   the  same
                                   address       space;       see
                                   clntrawcreate(). This routine
                                   allows simulation of  RPC  and
                                   acquisition  of  RPC overheads
                                   (such as  round  trip  times),
                                   without  any  kernel interfer-
                                   ence.  This  routine   returns
                                   NUL if it fails.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   has the same functionality  of
                                   svcrawcreate().          See
                                   rpcsvccreate(3NSL),    which
                                   obsoletes it.


     svctcpcreate()               This   routine    creates    a
                                   TCP/IP-based RPC service tran-
                                   sport, to which it  returns  a
                                   pointer.   The   transport  is
                                   associated   with   the   file
                                   descriptor  fd,  which  may be
                                   RPCANYSOCK, in which  case  a
                                   new    file    descriptor   is
                                   created. If the file  descrip-
                                   tor  is  not  bound to a local



SunOS 5.11           Last change: 7 Jun 2001                   15






Networking Services Library Functions               rpcsoc(3NSL)



                                   TCP port,  then  this  routine
                                   binds it to an arbitrary port.
                                   Refer to the  File  Descriptor
                                   section  for more information.
                                   Upon  completion,  xprt->xpfd
                                   is    the   transport's   file
                                   descriptor, and  xprt->xpport
                                   is    the   transport's   port
                                   number. This  routine  returns
                                   NUL  if  it fails. Since TCP-
                                   based RPC uses  buffered  I/O,
                                   users  may specify the size of
                                   buffers; values of   0  choose
                                   suitable defaults.

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   svccreate(),
                                   svctlicreate(),           or
                                   svcvccreate() should be used
                                   instead.                   See
                                   rpcsvccreate(3NSL).


     svcudpbufcreate()            This   routine    creates    a
                                   UDP/IP-based RPC service tran-
                                   sport, to which it  returns  a
                                   pointer.   The   transport  is
                                   associated   with   the   file
                                   descriptor   fd.   If   fd  is
                                   RPCANYSOCK then  a  new  file
                                   descriptor  is created. If the
                                   file descriptor is  not  bound
                                   to a local UDP port, then this
                                   routine binds it to  an  arbi-
                                   trary  port.  Upon completion,
                                   xprtxpfd is  the  transport's
                                   file   descriptor,  and  xprt-
                                   >xpport  is  the  transport's
                                   port number. Refer to the File
                                   Descriptor  section  for  more
                                   information.    This   routine
                                   returns NUL if it fails.

                                   The user specifies the maximum
                                   packet  size  for  sending and
                                   receiving UDP-based  RPC  mes-
                                   sages  by using the sendsz and
                                   recvsz parameters.

                                   This routine exists for  back-
                                   ward    compatibility    only.



SunOS 5.11           Last change: 7 Jun 2001                   16






Networking Services Library Functions               rpcsoc(3NSL)



                                   svctlicreate(),           or
                                   svcdgcreate() should be used
                                   instead.                   See
                                   rpcsvccreate(3NSL).


     svcudpcreate()               This   routine    creates    a
                                   UDP/IP-based RPC service tran-
                                   sport, to which it  returns  a
                                   pointer.   The   transport  is
                                   associated   with   the   file
                                   descriptor  fd,  which  may be
                                   RPCANYSOCK, in which  case  a
                                   new    file    descriptor   is
                                   created. If the file  descrip-
                                   tor  is  not  bound to a local
                                   UDP port,  then  this  routine
                                   binds it to an arbitrary port.
                                   Upon  completion,  xprt->xpfd
                                   is    the   transport's   file
                                   descriptor, and  xprt->xpport
                                   is    the   transport's   port
                                   number. This  routine  returns
                                   NUL if it fails.

                                   Since UDP-based  RPC  messages
                                   can  only  hold up to 8 Kbytes
                                   of encoded  data,  this  tran-
                                   sport  cannot be used for pro-
                                   cedures that take large  argu-
                                   ments or return huge results.

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   svccreate(),
                                   svctlicreate(),           or
                                   svcdgcreate() should be used
                                   instead.                   See
                                   rpcsvccreate(3NSL).


     registerrpc()                 Register program prognum, pro-
                                   cedure  procname,  and version
                                   versnum with the  RPC  service
                                   package.  If a request arrives
                                   for program  prognum,  version
                                   versnum,  and  procedure proc-
                                   num, procname is called with a
                                   pointer  to  its parameter(s).
                                   procname   should   return   a
                                   pointer    to    its    static
                                   result(s). inproc is  used  to



SunOS 5.11           Last change: 7 Jun 2001                   17






Networking Services Library Functions               rpcsoc(3NSL)



                                   decode  the  parameters  while
                                   outproc is used to encode  the
                                   results.  This routine returns
                                   0  if  the  registration  suc-
                                   ceeded, -1 otherwise.

                                   svcrun() must be called after
                                   all     the    services    are
                                   registered.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   it   is   made   obsolete   by
                                   rpcreg().


     svcregister()                Associates prognum and versnum
                                   with the service dispatch pro-
                                   cedure, dispatch. If  protocol
                                   is   0,  the  service  is  not
                                   registered  with  the  portmap
                                   service.  If  protocol is non-
                                   zero,  then a mapping  of  the
                                   triple [prognum, versnum, pro-
                                   tocol]  to  xprt->xpport   is
                                   established   with  the  local
                                   portmap   service   (generally
                                   protocol is  0, IPROTOUDP or
                                   IPROTOTCP).  The   procedure
                                   dispatch   has  the  following
                                   form:

                                     dispatch(struct svcreq *request, SVCXPRT *xprt);

                                   The   svcregister()   routine
                                   returns  one  if  it succeeds,
                                   and  0 otherwise.

                                   This routine exists for  back-
                                   ward    compatibility    only.
                                   Enhanced functionality is pro-
                                   vided by svcreg().


     svcunregister()              Remove all mapping of the dou-
                                   ble   [prognum,   versnum]  to
                                   dispatch routines, and of  the
                                   triple    [prognum,   versnum,
                                   all-protocols] to port  number
                                   from portmap.

                                   This   routine   exists    for



SunOS 5.11           Last change: 7 Jun 2001                   18






Networking Services Library Functions               rpcsoc(3NSL)



                                   backward        compatibility.
                                   Enhanced functionality is pro-
                                   vided by svcunreg().


     xdrauthunixparms()          Used   for   describing   UNIX
                                   credentials.  This  routine is
                                   useful for users who  wish  to
                                   generate   these   credentials
                                   without using the RPC  authen-
                                   tication package.

                                   This routine exists for  back-
                                   ward  compatibility  only, and
                                   is    made     obsolete     by
                                   xdrauthsysparms().       See
                                   rpcxdr(3NSL).


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     Unsafe                      
    


SEE ALSO
     keyserv(1M),   rpcbind(1M),    rpcinfo(1M),    netdir(3NSL),
     netdirgetbyname(3NSL),    rpc(3NSL),   rpcclntauth(3NSL),
     rpcclntcalls(3NSL),                 rpcclntcreate(3NSL),
     rpcsvccalls(3NSL),                   rpcsvccreate(3NSL),
     rpcsvcerr(3NSL),     rpcsvcreg(3NSL),     rpcxdr(3NSL),
     rpcbind(3NSL),         securerpc(3NSL),         select(3C),
     xdrauthsysparms(3NSL),  libnsl(3LIB),  librpcsoc(3LIBUCB),
     attributes(5)

NOTES
     These interfaces are unsafe in  multithreaded  applications.
     Unsafe  interfaces  should  be  called  only  from  the main
     thread.









SunOS 5.11           Last change: 7 Jun 2001                   19



OpenSolaris man pages main menu

Contact us      |       About us      |       Term of use      |       Copyright © 2000-2010 MyWebUniversity.com ™