NAME

netdb.h - definitions for network database operations

SYNOPSIS

#include <netdb.h>

DESCRIPTION

The <netdb.h> header may make available the type in_port_t and the type in_addr_t as defined in the description of <netinet/in.h>.

The <netdb.h> header defines the hostent structure that includes at least the following members:

char  *h_name      Official name of the host.
char **h_aliases   A pointer to an array of pointers to alternative host names,
                   terminated by a null pointer.
int    h_addrtype  Address type.
int    h_length    The length, in bytes, of the address.
char **h_addr_list A pointer to an array of pointers to network addresses (in
                   network byte order) for the host, terminated by a null pointer.

The <netdb.h> header defines the netent structure that includes at least the following members:

char  *n_name      Official, fully-qualified (including the domain) name of the host.
char **n_aliases   A pointer to an array of pointers to alternative network names,
                   terminated by a null pointer.
int    n_addrtype  The address type of the network.
uint32_t n_net     The network number, in host byte order.

The uint32_t type is made available by inclusion of <inttypes.h> (see referenced document XSH).

The <netdb.h> header defines the protoent structure that includes at least the following members:

char  *p_name      Official name of the protocol.
char **p_aliases   A pointer to an array of pointers to alternative protocol names,
                   terminated by a null pointer.
int    p_proto     The protocol number.

The <netdb.h> header defines the servent structure that includes at least the following members:

char  *s_name      Official name of the service.
char **s_aliases   A pointer to an array of pointers to alternative service names,
                   terminated by a null pointer.
int    s_port      The port number at which the service resides, in network byte order.
char  *s_proto     The name of the protocol to use when contacting the service.

The <netdb.h> header defines the macro IPPORT_RESERVED with the value of the highest reserved Internet port number.

When the <netdb.h> header is included, h_errno is available as a modifiable l-value of type int. It is unspecified whether h_errno is a macro or an identifier declared with external linkage.

The <netdb.h> header defines the following macros for use as error values for gethostbyaddr(), gethostbyname(), getipnodebyaddr(), and getipnodebyname()

HOST_NOT_FOUND

NO_DATA

NO_RECOVERY

TRY_AGAIN

The <netdb.h> header defines the following macros that evaluate to bitwise-distinct integer constants, for use in the flags argument of getipnodebyname():

AI_V4MAPPED

IPv4-mapped IPv6 addresses are acceptable

AI_ALL

return all addresses: IPv6 and IPv4-mapped IPv6

AI_ADDRCONFIG

return addresses depending on what source addresses are configured.

The <netdb.h> header defines macro AI_DEFAULT, which evaluates to the logical OR of AI_V4MAPPED and AI_ADDRCONFIG.

The following are declared as functions, and may also be defined as macros:

void             endhostent(void);
void             endnetent(void);
void             endprotoent(void);
void             endservent(void);
void             freehostent(struct hostent *ptr);
struct hostent  *gethostbyaddr(const void *addr, socket_t len, int type);
struct hostent  *gethostbyname(const char *name);
struct hostent  *gethostent(void);
struct hostent  *getipnodebyaddr(const void *addr, socket_t len, 
                                 int type, int *error_num);
struct hostent  *getipnodebyname(const char *name, int type, int flags,
                                 int *error_num);
struct netent   *getnetbyaddr(uint32_t net, int type);
struct netent   *getnetbyname(const char *name);
struct netent   *getnetent(void);
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynumber(int proto);
struct protoent *getprotoent(void);
struct servent  *getservbyname(const char *name, const char *proto);
struct servent  *getservbyport(int port, const char *proto);
struct servent  *getservent(void);
void             sethostent(int stayopen);
void             setnetent(int stayopen);
void             setprotoent(int stayopen);
void             setservent(int stayopen);

Inclusion of the <netdb.h> header may also make visible all symbols from <netinet/in.h> and <inttypes.h>.

Address Information Structure

The <netdb.h> header defines the addrinfo structure that includes at least the following members:

int               ai_flags      Input flags
int               ai_family     Address family of socket
int               ai_socktype   Socket type
int               ai_protocol   Protocol of socket
socklen_t         ai_addrlen    Length of socket address
struct sockaddr  *ai_addr       Socket address of socket
char             *ai_canonname  Canonical name of service location
struct addrinfo  *ai_next       Pointer to next in list

The <netdb.h> header defines the following macros that evaluate to bitwise-distinct integer constants, for use in the flags field of the addrinfo structure.

AI_PASSIVE

socket address is intended for bind()

AI_CANONNAME

request for canonical name

AI_NUMERICHOST

return numeric host address as name

The <netdb.h> header defines the following macros that evaluate to bitwise-distinct integer constants, for use in the flags argument to getnameinfo().

NI_NOFQDN

Only the nodename portion of the FQDN is returned for local hosts.

NI_NUMERICHOST

The numeric form of the node's address is returned instead of its name.

NI_NAMEREQD

Return an error if the node's name cannot be located in the database.

NI_NUMERICSERV

The numeric form of the service address is returned instead of its name.

NI_DGRAM

Indicates that the service is a datagram service (SOCK_DGRAM).

The <netdb.h> header defines the following macros for use as error values for getaddrinfo() and getnameinfo():

EAI_AGAIN

The name could not be resolved at this time. Future attempts may succeed.

EAI_BADFLAGS

The flags had an invalid value

EAI_FAIL

A non-recoverable error occurred

EAI_FAMILY

The address family was not recognized or the address length was invalid for the specified family

EAI_MEMORY

There was a memory allocation failure

EAI_NONAME

The name does not resolve for the supplied parameters

NI_NAMEREQD is set and the host's name cannot be located, or both nodename and servname were null.

EAI_SERVICE

The service passed was not recognized for the specified socket type

EAI_SOCKTYPE

The intended socket type was not recognized

EAI_SYSTEM

A system error occurred. The error code can be found in errno

SEE ALSO

endhostent(), endnetent(), endprotoent(), endservent(), getaddrinfo(), getnameinfo().

CHANGE HISTORY

First released in Issue 4.

Address information structure and errors added in Issue 5.2.