getnetent(3N)

NAME

getnetent(), getnetbyaddr(), getnetbyname(), setnetent(), endnetent() — get, set, or end network entry

SYNOPSIS

#include <sys/socket.h> 
#include <netdb.h> 

struct netent *getnetent(void); 

struct netent *getnetbyname(const char *name); 

struct netent *getnetbyaddr(unsigned int net, int type); 

_XOPEN_SOURCE_EXTENDED only 
struct netent *getnetbyaddr(in_addr_t net, int type); 

int setnetent(int stayopen); 

int endnetent(void); 

_XOPEN_SOURCE_EXTENDED only 
void setnetent(int stayopen); 
void endnetent(void); 

DESCRIPTION

getnetent(), getnetbyname(), and getnetbyaddr() each return a pointer to a structure of type netent containing the broken-out fields of a line in the network data base, /etc/networks.

The members of this structure are:

n_name: The official name of the network.
n_aliases: A null-terminated list of alternate names for the network.
n_addrtype: The type of the network number returned; always AF_INET.
n_net: The network number.

Functions behave as follows:

getnetent(): Reads the next line of the file, opening the file if necessary.
setnetent(): Opens and rewinds the file. If the stayopen flag is non-zero, the network data base is not closed after each call to getnetent() (either directly or indirectly through one of the other getnet* calls).
endnetent(): Closes the file.
getnetbyname(): Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter name is found, or until EOF is encountered.
getnetbyaddr(): Sequentially searches from the beginning of the file until a network number matching its parameter net is found, or until EOF is encountered. The parameter net must be in network order. The parameter type must be the constant AF_INET. Network numbers are supplied in host order (see byteorder(3N)).

If the system is running Network Information Service (NFS), getnetbyname() and getnetbyaddr() obtain their network information from the NIS server (see ypserv(1M) and ypfiles(4)).

In a multithreaded application, getnetent(), getentbyaddr(), and getentbyname() use thread-specific storage that is re-used in each call. The return value, struct netent, should be unique for each thread and should be saved, if desired, before the thread makes the next getnet*() call.

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

Name Service Switch-Based Operation

The library routines getnetbyname(), getnetbyaddr(), and getnetent() internally call the name service switch to access the "networks" database lookup policy configured in the /etc/nsswitch.conf file (see nsswitch.conf(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses.

RETURN VALUE

getnetent(), getnetbyname(), and getnetbyaddr() return a null pointer (0) on EOF or when they are unable to open /etc/networks. getnetbyaddr() also returns a null pointer if its type parameter is invalid.

EXAMPLES

The following code excerpt counts the number of network entries:

int count = 0;

(void) setnetent(0);
while (netbuf=getnetent() != NULL)
    count++;
(void) endnetent();

OBSOLESCENT INTERFACES

int getnetent_r(struct netent *result, struct netent_data *buffer); 

int getnetbyname_r( 
     const char *name, 
     struct netent *result, 
     struct netent_data *buffer); 

int getnetbyaddr_r( 
     int net, 
     int type, 
     struct netent *result, 
     struct netent_data *buffer); 

int setnetent_r(int stayopen, struct netent_data *buffer); 

int endnetent_r(struct netent_data *buffer); 

The above reentrant interfaces have been moved from libc to libd4r. They are included to support existing applications and may be removed in the future release. New multithreaded applications should not use these APIs.

The reentrant interfaces function the same as the regular interfaces (those without the -r suffix.) However, getnetent_r(), getnetbyname_r(), and getnetbyaddr_r() expect to be passed the address of a struct netent and will store the address of the result at the supplied parameter. An additional parameter, the address of struct netent_data, which is defined in the file <netdb.h>, cannot be a NULL pointer.

getnetent_r(), getnetbyname_r(), getnetbyaddr_r(), setnetent_r(), and endnetent_t() return a -1 if the operation is unsuccessful. A 0 is returned otherwise.

WARNINGS

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

AUTHOR

getnetent() was developed by Sun Microsystems Inc.

FILES

/etc/networks

STANDARDS CONFORMANCE

getnetent(): XPG4