'\" et
.TH netdb.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
netdb.h
\(em definitions for network database operations
.SH SYNOPSIS
.LP
.nf
#include <netdb.h>
.fi
.SH DESCRIPTION
The
.IR <netdb.h> 
header may define the
.BR in_port_t
type and the
.BR in_addr_t
type as described in
.IR <netinet/in.h> .
.P
The
.IR <netdb.h> 
header shall define the
.BR hostent
structure, which shall include at least the following members:
.sp
.RS 4
.nf

char   *h_name       \fROfficial name of the host.\fR
char  **h_aliases    \fRA pointer to an array of pointers to\fR
                     \fRalternative host names, terminated by a\fR
                     \fRnull pointer.\fR
int     h_addrtype   \fRAddress type.\fR
int     h_length     \fRThe length, in bytes, of the address.\fR
char  **h_addr_list  \fRA pointer to an array of pointers to network\fR
                     \fRaddresses (in network byte order) for the host,\fR
                     \fRterminated by a null pointer.\fR
.fi
.P
.RE
.P
The
.IR <netdb.h> 
header shall define the
.BR netent
structure, which shall include at least the following members:
.sp
.RS 4
.nf

char     *n_name      \fROfficial, fully-qualified (including the\fR
                      \fRdomain) name of the host.\fR
char    **n_aliases   \fRA pointer to an array of pointers to\fR
                      \fRalternative network names, terminated by a\fR
                      \fRnull pointer.\fR
int       n_addrtype  \fRThe address type of the network.\fR
uint32_t  n_net       \fRThe network number, in host byte order.\fR
.fi
.P
.RE
.P
The
.IR <netdb.h> 
header shall define the
.BR uint32_t
type as described in
.IR <inttypes.h> .
.P
The
.IR <netdb.h> 
header shall define the
.BR protoent
structure, which shall include at least the following members:
.sp
.RS 4
.nf

char   *p_name     \fROfficial name of the protocol.\fR
char  **p_aliases  \fRA pointer to an array of pointers to\fR
                   \fRalternative protocol names, terminated by\fR
                   \fRa null pointer.\fR
int     p_proto    \fRThe protocol number.\fR
.fi
.P
.RE
.P
The
.IR <netdb.h> 
header shall define the
.BR servent
structure, which shall include at least the following members:
.sp
.RS 4
.nf

char   *s_name     \fROfficial name of the service.\fR
char  **s_aliases  \fRA pointer to an array of pointers to\fR
                   \fRalternative service names, terminated by\fR
                   \fRa null pointer.\fR
int     s_port     \fRA value which, when converted to uint16_t,\fR
                   \fRyields the port number in network byte order\fR
                   \fRat which the service resides.\fR
char   *s_proto    \fRThe name of the protocol to use when\fR
                   \fRcontacting the service.\fR
.fi
.P
.RE
.P
The
.IR <netdb.h> 
header shall define the IPPORT_RESERVED symbolic constant with the
value of the highest reserved Internet port number.
.SS "Address Information Structure"
.P
The
.IR <netdb.h> 
header shall define the
.BR addrinfo
structure, which shall include at least the following members:
.sp
.RS 4
.nf

int               ai_flags      \fRInput flags.\fR
int               ai_family     \fRAddress family of socket.\fR
int               ai_socktype   \fRSocket type.\fR
int               ai_protocol   \fRProtocol of socket.\fR
socklen_t         ai_addrlen    \fRLength of socket address.\fR
struct sockaddr  *ai_addr       \fRSocket address of socket.\fR
char             *ai_canonname  \fRCanonical name of service location.\fR
struct addrinfo  *ai_next       \fRPointer to next in list.\fR
.fi
.P
.RE
.P
The
.IR <netdb.h> 
header shall define the following symbolic constants that evaluate to
bitwise-distinct integer constants for use in the
.IR flags
field of the
.BR addrinfo
structure:
.IP AI_PASSIVE 14
Socket address is intended for
\fIbind\fR().
.IP AI_CANONNAME 14
Request for canonical name.
.IP AI_NUMERICHOST 14
Return numeric host address as name.
.IP AI_NUMERICSERV 14
Inhibit service name resolution.
.IP AI_V4MAPPED 14
If no IPv6 addresses are found, query for IPv4 addresses and return
them to the caller as IPv4-mapped IPv6 addresses.
.IP AI_ALL 14
Query for both IPv4 and IPv6 addresses.
.IP AI_ADDRCONFIG 14
Query for IPv4 addresses only when an IPv4 address is configured;
query for IPv6 addresses only when an IPv6 address is configured.
.P
The
.IR <netdb.h> 
header shall define the following symbolic constants that evaluate
to bitwise-distinct integer constants for use in the
.IR flags
argument to
\fIgetnameinfo\fR():
.IP NI_NOFQDN 14
Only the nodename portion of the FQDN is returned for local hosts.
.IP NI_NUMERICHOST 14
The numeric form of the node's address is returned instead of its
name.
.IP NI_NAMEREQD 14
Return an error if the node's name cannot be located in the database.
.IP NI_NUMERICSERV 14
The numeric form of the service address is returned instead of its name.
.IP NI_NUMERICSCOPE 14
.br
For IPv6 addresses, the numeric form of the scope identifier is
returned instead of its name.
.IP NI_DGRAM 14
Indicates that the service is a datagram service (SOCK_DGRAM).
.SS "Address Information Errors"
.P
The
.IR <netdb.h> 
header shall define the following symbolic constants for use as
error values for
\fIgetaddrinfo\fR()
and
\fIgetnameinfo\fR().
The values shall be suitable for use in
.BR #if
preprocessing directives.
.IP EAI_AGAIN 14
The name could not be resolved at this time. Future attempts may
succeed.
.IP EAI_BADFLAGS 14
The flags had an invalid value.
.IP EAI_FAIL 14
A non-recoverable error occurred.
.IP EAI_FAMILY 14
The address family was not recognized or the address length was invalid
for the specified family.
.IP EAI_MEMORY 14
There was a memory allocation failure.
.IP EAI_NONAME 14
The name does not resolve for the supplied parameters.
.RS 14 
.P
NI_NAMEREQD is set and the host's name cannot be located, or both
.IR nodename
and
.IR servname
were null.
.RE
.IP EAI_SERVICE 14
The service passed was not recognized for the specified socket type.
.IP EAI_SOCKTYPE 14
The intended socket type was not recognized.
.IP EAI_SYSTEM 14
A system error occurred. The error code can be found in
.IR errno .
.IP EAI_OVERFLOW 14
An argument buffer overflowed.
.P
The following shall be declared as functions and may also be defined as
macros. Function prototypes shall be provided.
.sp
.RS 4
.nf

void              endhostent(void);
void              endnetent(void);
void              endprotoent(void);
void              endservent(void);
void              freeaddrinfo(struct addrinfo *);
const char       *gai_strerror(int);
int               getaddrinfo(const char *restrict, const char *restrict,
                      const struct addrinfo *restrict,
                      struct addrinfo **restrict);
struct hostent   *gethostent(void);
int               getnameinfo(const struct sockaddr *restrict, socklen_t,
                      char *restrict, socklen_t, char *restrict,
                      socklen_t, int);
struct netent    *getnetbyaddr(uint32_t, int);
struct netent    *getnetbyname(const char *);
struct netent    *getnetent(void);
struct protoent  *getprotobyname(const char *);
struct protoent  *getprotobynumber(int);
struct protoent  *getprotoent(void);
struct servent   *getservbyname(const char *, const char *);
struct servent   *getservbyport(int, const char *);
struct servent   *getservent(void);
void              sethostent(int);
void              setnetent(int);
void              setprotoent(int);
void              setservent(int);
.fi
.P
.RE
.P
The
.IR <netdb.h> 
header shall define the
.BR socklen_t
type through
.BR typedef ,
as described in
.IR <sys/socket.h> .
.P
Inclusion of the
.IR <netdb.h> 
header may also make visible all symbols from
.IR <netinet/in.h> ,
.IR <sys/socket.h> ,
and
.IR <inttypes.h> .
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
None.
.SH "RATIONALE"
None.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fB<inttypes.h>\fP",
.IR "\fB<netinet_in.h>\fP",
.IR "\fB<sys_socket.h>\fP"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIbind\fR\^(\|)",
.IR "\fIendhostent\fR\^(\|)",
.IR "\fIendnetent\fR\^(\|)",
.IR "\fIendprotoent\fR\^(\|)",
.IR "\fIendservent\fR\^(\|)",
.IR "\fIfreeaddrinfo\fR\^(\|)",
.IR "\fIgai_strerror\fR\^(\|)",
.IR "\fIgetnameinfo\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .