getrpcent(3C)

NAME

getrpcent(), getrpcbyname(), getrpcbynumber(), setrpcent(), endrpcent() — get RPC entry

SYNOPSIS

cc [ flag ]... file ... -lnsl [ library ]...

#include <netdb.h>

struct rpcent *getrpcbyname(char *name);

struct rpcent *getrpcbynumber(int number);

struct rpcent *getrpcent(void);

void setrpcent(int stayopen);

void endrpcent();

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.

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

setrpcent() sets (or resets) the enumeration to the beginning 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().

MULTITHREAD USAGE

Thread Safe:: Yes
Cancel Safe:: Yes
Fork Safe:: No
Async-cancel Safe:: No
Async-signal Safe:: No

These functions can be called safely in a multithreaded environment. They may be cancellation points in that they call functions that are cancel points.

In a multithreaded environment, these functions are not safe to be called by a child process after fork() and before exec(). These functions should not be called by a multithreaded application that supports asynchronous cancellation or asynchronous signals.

getrpcbyname(), getrpcbynumber() and getrpcent() use thread specific storage that is re-used in each call. The return value, struct rpcent, should be unique for each thread and should be saved, if desired, before the thread makes the next getrpc*() call.

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(), the threads will enumerate disjoint subsets of the RPC entry database.

RETURN VALUE

RPC entries are represented by the struct rpcent structure defined in <netdb.h>:

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(), and getrpcbynumber() each return a pointer to a struct rpcent if they successfully locate the requested entry; otherwise they return NULL.

The function getrpcent() returns a pointer to a struct rpcent if it successfully enumerates an entry; otherwise it returns NULL, indicating the end of the enumeration.

WARNINGS

Programs that use the interfaces described in this manual page cannot be linked statically since the implementations of these functions employ dynamic loading and linking of shared objects at run time.

AUTHOR

getrpcent() was developed by Sun Microsystems, Inc.

FILES

/etc/rpc 
/etc/nsswitch.conf 

getrpcent(3C)

Technical documentation

» Table of Contents

» Index