getrpcent(3C)

NAME

getrpcent(), getrpcent_r(), getrpcbyname(), getrpcbyname_r(), getrpcbynumber(), getrpcbynumber_r() − get rpc entry

SYNOPSIS

#include <netdb.h>

struct rpcent *getrpcent();

int getrpcent_r(struct rpcent *rpcent,
struct rpcent_data *rpc_data);

struct rpcent *getrpcbyname(char *name);

int getrpcbyname_r (char *name,
struct rpcent *rpcent,
struct rpcent_data *rpc_data);

struct rpcent *getrpcbynumber(int number);

int getrpcbynumber_r (register int number,
struct rpcent *rpcent,
struct rpcent_data *rpc_data);

int setrpcent(int stayopen);

int setrpcent_r (int f,
sruct rpcent_data *rpc_data);

int endrpcent();

int endrpcent_r (struct rpcent_data *rpc_data);

DESCRIPTION

getrpcent(), getrpcbyname(), and getrpcbynumber() each return a pointer to an object with the following structure containing the broken-out fields of a line in the rpc program number data base, /etc/rpc.

struct rpcent {
    char *r_name;      /* name of server for this rpc program */
    char **r_aliases; /* NULL terminated list of aliases */
    int r_number;     /* rpc program number for this service */
};

Functions

getrpcent() Read the next line of the file, opening the file if necessary.

setrpcent() Open and rewind the file. If the stayopen flag is non-zero, the rpc database is not closed after each call to getrpcent() (either directly or indirectly through one of the other getrpc*() calls).

endrpcent() Close the file.

getrpcbyname() Sequentially search from the beginning of the file until a matching rpc program name is found, or until EOF is encountered.

getrpcbynumber() Sequentially search from the beginning of the file until a matching rpc program number is found, or until EOF is encountered.

If the system is running the Network Information Service (NIS) services, getrpcbyname() and getrpcbynumber() get the rpc information from the NIS server (see ypserv(1M) and ypfiles(4)).

Reentrant Interfaces

getrpcent_r(), getrpcbyname_r(), and getrpcbynumber_r() expect to be passed the address of a struct rpcent and will store the result at the supplied location. An additional parameter, a pointer to a struct rpcent_data, must also be supplied. This structure is used to store data, to which fields in the struct rpcent will point, as well as state information such as open file descriptors. The struct rpcent_data is defined in the file <netdb.h>.

setrpcent_r() and endrpcent_r() are to be used only in conjunction with getrpcent_r() and take the same pointer to a struct rpcent_data as a parameter. If the Network Information Service is being used, setrpcent_r() initiaizes an internal database key. If the /etc/rpc file is being used, setrpcent_r() opens or rewinds the file. endrpcent_r() should always be called to ensure that files are closed and internally allocated data structures are released.

The stayopen parameter to setrpcent_r() currently has no effect. However, setrpcent() can still be used to keep the /etc/rpc file open when making calls to getrpcbyname_r() and getrpcbynumber_r()

The rpc_fp field in the struct rpcent_data must be initialized to NULL before it is passed to either getrpcent_r() or setrpcent_r() for the first time. Thereafter is should not be modified in any way. This is the only rpcent_data field that should ever be explicitly accessed.

Name Service Switch-Based Operation

The library routines, getrpcbyname(), getrpcbynumber(), getrpcent(), and their reentrant counterparts, internally call the name service switch to access the "rpc" database lookup policy configured in the /etc/nsswitch.conf file (see switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve rpc names and numbers.

RETURN VALUE

getrpcent(), getrpcbyname(), and getrpcbynumber() return a null pointer (0) on EOF or when unable to access the information in /etc/rpc either directly or through a Network Information Service database.

For the reentrant (_r) versions of these routines, -1 will be returned if the operation is unsuccessful or, in the case of getrpcent_r(), if the end of the rpc list has been reached. 0 is returned otherwise.

WARNINGS

In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved.

getrpcent(), getrpcbynumber(), getrpcbyname(), setrpcent(), and endrpcent() are unsafe in multi-thread applications. getrpcent_r(), getrpcbynumber_r(), getrpcbyname_r(), setrpcent_r(), and endrpcent_r() are MT-Safe and should be used instead.

AUTHOR

getrpcent() was developed by Sun Microsystems, Inc.

FILES

/etc/rpc /etc/nsswitch.conf

Museum

Related Articles