mirror of https://github.com/mkerrisk/man-pages
299 lines
9.1 KiB
Plaintext
299 lines
9.1 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "<netdb.h>" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" <netdb.h>
|
|
.SH NAME
|
|
netdb.h \- definitions for network database operations
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <netdb.h>\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fI<netdb.h>\fP header may define the \fBin_port_t\fP type and
|
|
the \fBin_addr_t\fP type as described in \fI<netinet/in.h>\fP .
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the \fBhostent\fP structure
|
|
that includes at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBchar *h_name \fP Official name of the host. \fB
|
|
char **h_aliases \fP A pointer to an array of pointers to \fB
|
|
\fP alternative host names, terminated by a \fB
|
|
\fP null pointer. \fB
|
|
int h_addrtype \fP Address type. \fB
|
|
int h_length \fP The length, in bytes, of the address. \fB
|
|
char **h_addr_list \fP A pointer to an array of pointers to network \fB
|
|
\fP addresses (in network byte order) for the host, \fB
|
|
\fP terminated by a null pointer. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the \fBnetent\fP structure
|
|
that includes at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBchar *n_name \fP Official, fully-qualified (including the \fB
|
|
\fP domain) name of the host. \fB
|
|
char **n_aliases \fP A pointer to an array of pointers to \fB
|
|
\fP alternative network names, terminated by a \fB
|
|
\fP null pointer. \fB
|
|
int n_addrtype \fP The address type of the network. \fB
|
|
uint32_t n_net \fP The network number, in host byte order. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fBuint32_t\fP type shall be defined as described in \fI<inttypes.h>\fP
|
|
\&.
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the \fBprotoent\fP structure
|
|
that includes at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBchar *p_name \fP Official name of the protocol. \fB
|
|
char **p_aliases \fP A pointer to an array of pointers to \fB
|
|
\fP alternative protocol names, terminated by \fB
|
|
\fP a null pointer. \fB
|
|
int p_proto \fP The protocol number. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the \fBservent\fP structure
|
|
that includes at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBchar *s_name \fP Official name of the service. \fB
|
|
char **s_aliases \fP A pointer to an array of pointers to \fB
|
|
\fP alternative service names, terminated by \fB
|
|
\fP a null pointer. \fB
|
|
int s_port \fP The port number at which the service \fB
|
|
\fP resides, in network byte order. \fB
|
|
char *s_proto \fP The name of the protocol to use when \fB
|
|
\fP contacting the service. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the IPPORT_RESERVED macro
|
|
with the value of the highest reserved Internet port
|
|
number.
|
|
.LP
|
|
When the \fI<netdb.h>\fP header is included, \fIh_errno\fP shall be
|
|
available as a modifiable lvalue of type \fBint\fP. It
|
|
is unspecified whether \fIh_errno\fP is a macro or an identifier declared
|
|
with external linkage.
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the following macros for use
|
|
as error values for \fIgethostbyaddr\fP() and \fIgethostbyname\fP():
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
HOST_NOT_FOUND
|
|
NO_DATA
|
|
NO_RECOVERY
|
|
TRY_AGAIN
|
|
.fi
|
|
.RE
|
|
.SS Address Information Structure
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the \fBaddrinfo\fP structure
|
|
that includes at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBint ai_flags \fP Input flags. \fB
|
|
int ai_family \fP Address family of socket. \fB
|
|
int ai_socktype \fP Socket type. \fB
|
|
int ai_protocol \fP Protocol of socket. \fB
|
|
socklen_t ai_addrlen \fP Length of socket address. \fB
|
|
struct sockaddr *ai_addr \fP Socket address of socket. \fB
|
|
char *ai_canonname \fP Canonical name of service location. \fB
|
|
struct addrinfo *ai_next \fP Pointer to next in list. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the following macros that
|
|
evaluate to bitwise-distinct integer constants for use
|
|
in the \fIflags\fP field of the \fBaddrinfo\fP structure:
|
|
.TP 7
|
|
AI_PASSIVE
|
|
Socket address is intended for \fIbind\fP().
|
|
.TP 7
|
|
AI_CANONNAME
|
|
.sp
|
|
Request for canonical name.
|
|
.TP 7
|
|
AI_NUMERICHOST
|
|
.sp
|
|
Return numeric host address as name.
|
|
.TP 7
|
|
AI_NUMERICSERV
|
|
.sp
|
|
Inhibit service name resolution.
|
|
.TP 7
|
|
AI_V4MAPPED
|
|
If no IPv6 addresses are found, query for IPv4 addresses and return
|
|
them to the caller as IPv4-mapped IPv6 addresses.
|
|
.TP 7
|
|
AI_ALL
|
|
Query for both IPv4 and IPv6 addresses.
|
|
.TP 7
|
|
AI_ADDRCONFIG
|
|
.sp
|
|
Query for IPv4 addresses only when an IPv4 address is configured;
|
|
query for IPv6 addresses only when an IPv6 address is
|
|
configured.
|
|
.sp
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the following macros that
|
|
evaluate to bitwise-distinct integer constants for use
|
|
in the \fIflags\fP argument to \fIgetnameinfo\fP():
|
|
.TP 7
|
|
NI_NOFQDN
|
|
Only the nodename portion of the FQDN is returned for local hosts.
|
|
.TP 7
|
|
NI_NUMERICHOST
|
|
.sp
|
|
The numeric form of the node's address is returned instead of its
|
|
name.
|
|
.TP 7
|
|
NI_NAMEREQD
|
|
Return an error if the node's name cannot be located in the database.
|
|
.TP 7
|
|
NI_NUMERICSERV
|
|
.sp
|
|
The numeric form of the service address is returned instead of its
|
|
name.
|
|
.TP 7
|
|
NI_NUMERICSCOPE
|
|
.sp
|
|
For IPv6 addresses, the numeric form of the scope identifier is returned
|
|
instead of its name.
|
|
.TP 7
|
|
NI_DGRAM
|
|
Indicates that the service is a datagram service (SOCK_DGRAM).
|
|
.sp
|
|
.SS Address Information Errors
|
|
.LP
|
|
The \fI<netdb.h>\fP header shall define the following macros for use
|
|
as error values for \fIgetaddrinfo\fP() and \fIgetnameinfo\fP():
|
|
.TP 7
|
|
EAI_AGAIN
|
|
The name could not be resolved at this time. Future attempts may succeed.
|
|
.TP 7
|
|
EAI_BADFLAGS
|
|
The flags had an invalid value.
|
|
.TP 7
|
|
EAI_FAIL
|
|
A non-recoverable error occurred.
|
|
.TP 7
|
|
EAI_FAMILY
|
|
The address family was not recognized or the address length was invalid
|
|
for the specified family.
|
|
.TP 7
|
|
EAI_MEMORY
|
|
There was a memory allocation failure.
|
|
.TP 7
|
|
EAI_NONAME
|
|
The name does not resolve for the supplied parameters.
|
|
.LP
|
|
NI_NAMEREQD is set and the host's name cannot be located, or both
|
|
\fInodename\fP and \fIservname\fP were null.
|
|
.TP 7
|
|
EAI_SERVICE
|
|
The service passed was not recognized for the specified socket type.
|
|
.TP 7
|
|
EAI_SOCKTYPE
|
|
The intended socket type was not recognized.
|
|
.TP 7
|
|
EAI_SYSTEM
|
|
A system error occurred. The error code can be found in \fIerrno\fP.
|
|
.TP 7
|
|
EAI_OVERFLOW
|
|
.sp
|
|
An argument buffer overflowed.
|
|
.sp
|
|
.LP
|
|
The following shall be declared as functions and may also be defined
|
|
as macros. Function prototypes shall be provided.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBvoid 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 *gethostbyaddr(const void *, socklen_t, int);
|
|
struct hostent *gethostbyname(const char *);
|
|
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);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The type \fBsocklen_t\fP shall be defined through \fBtypedef\fP as
|
|
described in \fI<sys/socket.h>\fP.
|
|
.LP
|
|
Inclusion of the \fI<netdb.h>\fP header may also make visible all
|
|
symbols from \fI<netinet/in.h>\fP, \fI<sys/socket.h>\fP, and \fI<inttypes.h>\fP.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fI<netinet/in.h>\fP , \fI<inttypes.h>\fP , \fI<sys/socket.h>\fP ,
|
|
the System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIbind\fP(),
|
|
\fIendhostent\fP(), \fIendnetent\fP(), \fIendprotoent\fP(), \fIendservent\fP(),
|
|
\fIgetaddrinfo\fP(), \fIgetnameinfo\fP()
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|