Manual Pages for UNIX Operating System command usage for man endrpcent

Networking Services Library Functions          getrpcbyname(3NSL)



NAME
     getrpcbyname,        getrpcbyname_r,         getrpcbynumber,
     getrpcbynumber_r,    getrpcent,    getrpcent_r,   setrpcent,
     endrpcent - get RPC entry

SYNOPSIS
     cc [ flag ... ] file ... -lnsl [ library ... ]
     #include 



     struct rpcent *getrpcbyname(const char *name);


     struct rpcent *getrpcbyname_r(const char *name, struct rpcent *result,
          char *buffer, int buflen);


     struct rpcent *getrpcbynumber(const int number);


     struct rpcent *getrpcbynumber_r(const int number, struct rpcent *result,
          char *buffer, int buflen);


     struct rpcent *getrpcent(void);


     struct rpcent *getrpcent_r(struct rpcent *result, char *buffer,
          int buflen);


     void setrpcent(const int stayopen);


     void endrpcent(void);


DESCRIPTION
     These functions are used to obtain entries for  RPC  (Remote
     Procedure Call) services.  An entry may come from any of the
     sources for rpc specified  in  the  /etc/nsswitch.conf  file
     (see nsswitch.conf(4)).


     getrpcbyname() searches for an entry with  the  RPC  service
     name specified by the parameter name.


     getrpcbynumber() searches for an entry with the RPC  program
     number number.




SunOS 5.11          Last change: 20 Feb 1998                    1






Networking Services Library Functions          getrpcbyname(3NSL)



     The functions setrpcent(), getrpcent(), and endrpcent()  are
     used to enumerate RPC entries from the database.


     setrpcent() sets (or resets) the enumeration to  the  begin-
     ning  of  the  set  of RPC entries.  This function should be
     called before  the  first  call  to  getrpcent().  Calls  to
     getrpcbyname()  and  getrpcbynumber()  leave the enumeration
     position in an indeterminate state.   If the  stayopen  flag
     is non-zero, the system may keep allocated resources such as
     open  file  descriptors   until   a   subsequent   call   to
     endrpcent().


     Successive calls to  getrpcent()  return  either  successive
     entries or NULL, indicating the end of the enumeration.


     endrpcent() may  be  called  to  indicate  that  the  caller
     expects to do no further RPC entry retrieval operations; the
     system may then  deallocate resources it was using.   It  is
     still  allowed, but possibly less efficient, for the process
     to call more RPC entry  retrieval  functions  after  calling
     endrpcent().

  Reentrant Interfaces
     The functions getrpcbyname(), getrpcbynumber(),  and  getrp-
     cent() use static storage that is re-used in each call, mak-
     ing these routines unsafe for use in multithreaded  applica-
     tions.


     The  functions  getrpcbyname_r(),  getrpcbynumber_r(),   and
     getrpcent_r()  provide reentrant interfaces for these opera-
     tions.


     Each reentrant interface performs the same operation as  its
     non-reentrant  counterpart,  named  by  removing the  ``_r''
     suffix.  The reentrant interfaces, however, use buffers sup-
     plied by the caller to store returned results, and  are safe
     for use in both single-threaded and  multithreaded  applica-
     tions.


     Each reentrant interface takes the same  parameters  as  its
     non-reentrant  counterpart,  as  well as the following addi-
     tional parameters.  The parameter result must be  a  pointer
     to  a  struct  rpcent structure allocated by the caller.  On
     successful completion, the function returns the RPC entry in
     this  structure. The parameter buffer must be a pointer to a
     buffer supplied by the  caller.   This  buffer  is  used  as



SunOS 5.11          Last change: 20 Feb 1998                    2






Networking Services Library Functions          getrpcbyname(3NSL)



     storage  space  for the RPC entry data.  All of the pointers
     within the returned  struct  rpcent  result  point  to  data
     stored  within  this  buffer (see RETURN VALUES). The buffer
     must be large enough to hold all of the data associated with
     the  RPC entry. The parameter buflen should give the size in
     bytes of the buffer indicated by buffer.


     For enumeration in multithreaded applications, the  position
     within  the enumeration is a process-wide property shared by
     all threads. setrpcent() may  be  used  in  a  multithreaded
     application  but  resets  the  enumeration  position for all
     threads.   If   multiple   threads   interleave   calls   to
     getrpcent_r(),  the  threads will enumerate disjoint subsets
     of the RPC entry database.


     Like their non-reentrant counterparts, getrpcbyname_r()  and
     getrpcbynumber_r()  leave  the  enumeration  position  in an
     indeterminate state.

RETURN VALUES
     RPC entries are represented by the struct  rpcent  structure
     defined in :

       struct rpcent {
          char *r_name;       /* name of this rpc service
          char **r_aliases;   /* zero-terminated list of alternate names */
          int r_number;       /* rpc program number */
       };



     The     functions     getrpcbyname(),      getrpcbyname_r(),
     getrpcbynumber(),   and  getrpcbynumber_r()  each  return  a
     pointer to a struct rpcent if they successfully  locate  the
     requested entry; otherwise they return NULL.


     The functions getrpcent() and getrpcent_r()  each  return  a
     pointer to a struct rpcent if they successfully enumerate an
     entry; otherwise they return NULL, indicating the end of the
     enumeration.


     The functions getrpcbyname(), getrpcbynumber(),  and  getrp-
     cent()  use  static storage, so returned data must be copied
     before a subsequent call to any of these  functions  if  the
     data is to be saved.






SunOS 5.11          Last change: 20 Feb 1998                    3






Networking Services Library Functions          getrpcbyname(3NSL)



     When  the  pointer  returned  by  the  reentrant   functions
     getrpcbyname_r(),  getrpcbynumber_r(),  and getrpcent_r() is
     non-NULL, it is always equal to the result pointer that  was
     supplied by the caller.

ERRORS
     The reentrant functions  getrpcyname_r(), getrpcbynumber_r()
     and  getrpcent_r()  will return NULL and set errno to ERANGE
     if the length of the buffer supplied by caller is not  large
     enough  to  store  the  result.  See Intro(2) for the proper
     usage and interpretation of errno in multithreaded  applica-
     tions.

FILES
     /etc/rpc


     /etc/nsswitch.conf

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



     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  MT-Level                   |  See "Reentrant  Interfaces"|
   |                             |  in DESCRIPTION.            |
   |_____________________________|_____________________________|


SEE ALSO
     rpcinfo(1M),  rpc(3NSL),  nsswitch.conf(4),  rpc(4),  attri-
     butes(5)

WARNINGS
     The       reentrant       interfaces       getrpcbyname_r(),
     getrpcbynumber_r(),  and  getrpcent_r() are included in this
     release on an uncommitted basis only,  and  are  subject  to
     change or removal in future minor releases.

NOTES
     When compiling multithreaded  applications,  see   Intro(3),
     Notes  On  Multithreaded Applications, for information about
     the use of the _REENTRANT flag.


     Use  of   the   enumeration   interfaces   getrpcent()   and
     getrpcent_r()  is  discouraged;  enumeration may not be sup-
     ported  for  all  database  sources.    The   semantics   of



SunOS 5.11          Last change: 20 Feb 1998                    4






Networking Services Library Functions          getrpcbyname(3NSL)



     enumeration are discussed further in nsswitch.conf(4).






















































SunOS 5.11          Last change: 20 Feb 1998                    5