Content-type: text/html Man page of gethostent

gethostent

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

gethostent, gethostent_r, sethostent, sethostent_r - Opens network host file  

LIBRARY

Standard C Library (libc.so, libc.a)  

SYNOPSIS

#include <netdb.h>

struct hostent *gethostent(void);

void sethostent(
        int stay_open);

[Digital]  The following obsolete functions are supported in order to maintain backward compatibility with previous versions of the operating system. You should not use them in new designs. int gethostent_r(
        struct hostent *host,
        struct hostent_data *host_data);

int sethostent_r(
        int stay_open,
        struct hostent_data *host_data);

[Digital]  The following definition of the sethostent() function does not conform to current standards and is supported only for backward compatibility:

int sethostent(
        int stay_open);  

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

gethostent(): XPG4-UNIX

sethostent(): XPG4-UNIX

Refer to the standards(5) reference page for more information about industry standards and associated tags.  

PARAMETERS

[Digital]  For gethostent_r() only, this points to the hostent structure. The netdb.h header file defines the hostent structure. [Digital]  For gethostent_r() and sethostent_r() only, this is data for the host database. The netdb.h header file defines the hostent_data structure. Contains a value used to indicate when to close the network host database. Specifying a value of 0 (zero) closes the network host database file after each call to the gethostbyname() or gethostbyaddr() function. Specifying a nonzero value allows the network host database file to remain open after each call.  

DESCRIPTION

The gethostent() (get host entry) function reads the next line of the either the local /etc/hosts file or one of the files distributed by BIND or NIS, opening it if necessary, returning a hostent structure. The netdb.h header file defines the hostent_data structure.

The sethostent() (set host entry) function opens either the local /etc/hosts file or one of the files distributed by BIND or NIS, and resets the file marker to the beginning of the file. To determine which file or files to search, and in which order, the system uses the switches in the /etc/svc.conf file.

Passing a nonzero value to the stay_open parameter establishes a connection with a name server and allows a client process to retrieve one entry at a time from the network hosts database file. The client process can close the connection with the endhostent() function.  

NOTES

The gethostent() function returns a pointer to thread-specific data. Subsequent calls to this or a related function from the same thread overwrite this data.

[Digital]  The gethostent_r() and sethostent_r() functions are obsolete reentrant versions of the gethostent() and sethostent() functions. They are supported in order to maintain backward compatibility with previous versions of the operating system and should not be used in new designs. Note that, you must zero-fill the host_data structure before its first access by the gethostent_r() function.  

RETURN VALUES

Upon successful completion, the gethostent() function returns a pointer to a hostent structure. If it fails or reaches the end of the network hostname database, the gethostent() function returns a null pointer and places an appropriate error code in the h_errno variable.

[Digital]  Upon successful completion, the gethostent_r() and sethostent_r() functions return a value of 0 (zero). The gethostent_r() function stores the hostent data structure in the location pointed to by host. Upon failure, the gethostent_r() and sethostent_r() functions return a value of -1 and set the errno variable.

[Digital]  The version of sethostent() that is supported for backward compatibility always returns a value of 1.  

ERRORS

Current industry standards do not define error values for the gethostent() and sethostent() functions.

[Digital]  If the following condition occurs, the gethostent() or gethostent_r() function sets h_errno to the corresponding value: This error code indicates an unrecoverable error.

[Digital]  If the following condition occurs, the gethostent_r() function sets errno to the corresponding value: The host or host_data parameter is invalid.

[Digital]  If the following condition occurs, the sethostent_r() function sets errno to the corresponding value: The host_data parameter is invalid.

[Digital]  In addition, the sethostent(), backward compatible version of sethostent() and sethostent_r() functions can fail to open the file. In this case errno will be set to the failure.  

FILES

Contains the hostname database. Contains the name server and domain name. The database service selection configuration file.  

RELATED INFORMATION

Functions: endhostent(3), gethostbyaddr(3), gethostbyname(3)

Files: resolv.conf(4), svc.conf(4)

Networks: bind_intro(7), nis_intro(7)

Standards: standards(5) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:46 GMT, October 02, 2010