347 lines
12 KiB
HTML
347 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title><netdb.h></title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="<netdb.h>"></a> <a name="tag_13_31"></a><!-- <netdb.h> -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_13_31_01"></a>NAME</h4>
|
|
|
|
<blockquote>netdb.h - definitions for network database operations</blockquote>
|
|
|
|
<h4><a name="tag_13_31_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><tt>#include <netdb.h></tt></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_31_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i><netdb.h></i> header may define the <b>in_port_t</b> type and the <b>in_addr_t</b> type as described in <a href=
|
|
"netinet/in.h.html"><i><netinet/in.h></i></a> .</p>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the <b>hostent</b> structure that includes at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>char *h_name </tt> Official name of the host. <tt>
|
|
char **h_aliases </tt> A pointer to an array of pointers to <tt>
|
|
</tt> alternative host names, terminated by a <tt>
|
|
</tt> null pointer. <tt>
|
|
int h_addrtype </tt> Address type. <tt>
|
|
int h_length </tt> The length, in bytes, of the address. <tt>
|
|
char **h_addr_list </tt> A pointer to an array of pointers to network <tt>
|
|
</tt> addresses (in network byte order) for the host, <tt>
|
|
</tt> terminated by a null pointer. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the <b>netent</b> structure that includes at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>char *n_name </tt> Official, fully-qualified (including the <tt>
|
|
</tt> domain) name of the host. <tt>
|
|
char **n_aliases </tt> A pointer to an array of pointers to <tt>
|
|
</tt> alternative network names, terminated by a <tt>
|
|
</tt> null pointer. <tt>
|
|
int n_addrtype </tt> The address type of the network. <tt>
|
|
uint32_t n_net </tt> The network number, in host byte order. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <b>uint32_t</b> type shall be defined as described in <a href="inttypes.h.html"><i><inttypes.h></i></a> .</p>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the <b>protoent</b> structure that includes at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>char *p_name </tt> Official name of the protocol. <tt>
|
|
char **p_aliases </tt> A pointer to an array of pointers to <tt>
|
|
</tt> alternative protocol names, terminated by <tt>
|
|
</tt> a null pointer. <tt>
|
|
int p_proto </tt> The protocol number. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the <b>servent</b> structure that includes at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>char *s_name </tt> Official name of the service. <tt>
|
|
char **s_aliases </tt> A pointer to an array of pointers to <tt>
|
|
</tt> alternative service names, terminated by <tt>
|
|
</tt> a null pointer. <tt>
|
|
int s_port </tt> The port number at which the service <tt>
|
|
</tt> resides, in network byte order. <tt>
|
|
char *s_proto </tt> The name of the protocol to use when <tt>
|
|
</tt> contacting the service. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the IPPORT_RESERVED macro with the value of the highest reserved Internet port
|
|
number.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
When the <i><netdb.h></i> header is included, <i>h_errno</i> shall be available as a modifiable lvalue of type <b>int</b>. It
|
|
is unspecified whether <i>h_errno</i> is a macro or an identifier declared with external linkage. <img src="../images/opt-end.gif"
|
|
alt="[Option End]" border="0"></p>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the following macros for use as error values for <a href=
|
|
"../functions/gethostbyaddr.html"><i>gethostbyaddr</i>()</a> and <a href=
|
|
"../functions/gethostbyname.html"><i>gethostbyname</i>()</a>:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
HOST_NOT_FOUND
|
|
NO_DATA
|
|
NO_RECOVERY
|
|
TRY_AGAIN
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h5><a name="tag_13_31_03_01"></a>Address Information Structure</h5>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the <b>addrinfo</b> structure that includes at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>int ai_flags </tt> Input flags. <tt>
|
|
int ai_family </tt> Address family of socket. <tt>
|
|
int ai_socktype </tt> Socket type. <tt>
|
|
int ai_protocol </tt> Protocol of socket. <tt>
|
|
socklen_t ai_addrlen </tt> Length of socket address. <tt>
|
|
struct sockaddr *ai_addr </tt> Socket address of socket. <tt>
|
|
char *ai_canonname </tt> Canonical name of service location. <tt>
|
|
struct addrinfo *ai_next </tt> Pointer to next in list. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the following macros that evaluate to bitwise-distinct integer constants for use
|
|
in the <i>flags</i> field of the <b>addrinfo</b> structure:</p>
|
|
|
|
<dl compact>
|
|
<dt>AI_PASSIVE</dt>
|
|
|
|
<dd>Socket address is intended for <a href="../functions/bind.html"><i>bind</i>()</a>.</dd>
|
|
|
|
<dt>AI_CANONNAME</dt>
|
|
|
|
<dd><br>
|
|
Request for canonical name.</dd>
|
|
|
|
<dt>AI_NUMERICHOST</dt>
|
|
|
|
<dd><br>
|
|
Return numeric host address as name.</dd>
|
|
|
|
<dt>AI_NUMERICSERV</dt>
|
|
|
|
<dd><br>
|
|
Inhibit service name resolution.</dd>
|
|
|
|
<dt>AI_V4MAPPED</dt>
|
|
|
|
<dd>If no IPv6 addresses are found, query for IPv4 addresses and return them to the caller as IPv4-mapped IPv6 addresses.</dd>
|
|
|
|
<dt>AI_ALL</dt>
|
|
|
|
<dd>Query for both IPv4 and IPv6 addresses.</dd>
|
|
|
|
<dt>AI_ADDRCONFIG</dt>
|
|
|
|
<dd><br>
|
|
Query for IPv4 addresses only when an IPv4 address is configured; query for IPv6 addresses only when an IPv6 address is
|
|
configured.</dd>
|
|
</dl>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the following macros that evaluate to bitwise-distinct integer constants for use
|
|
in the <i>flags</i> argument to <a href="../functions/getnameinfo.html"><i>getnameinfo</i>()</a>:</p>
|
|
|
|
<dl compact>
|
|
<dt>NI_NOFQDN</dt>
|
|
|
|
<dd>Only the nodename portion of the FQDN is returned for local hosts.</dd>
|
|
|
|
<dt>NI_NUMERICHOST</dt>
|
|
|
|
<dd><br>
|
|
The numeric form of the node's address is returned instead of its name.</dd>
|
|
|
|
<dt>NI_NAMEREQD</dt>
|
|
|
|
<dd>Return an error if the node's name cannot be located in the database.</dd>
|
|
|
|
<dt>NI_NUMERICSERV</dt>
|
|
|
|
<dd><br>
|
|
The numeric form of the service address is returned instead of its name.</dd>
|
|
|
|
<dt>NI_DGRAM</dt>
|
|
|
|
<dd>Indicates that the service is a datagram service (SOCK_DGRAM).</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_13_31_03_02"></a>Address Information Errors</h5>
|
|
|
|
<p>The <i><netdb.h></i> header shall define the following macros for use as error values for <a href=
|
|
"../functions/getaddrinfo.html"><i>getaddrinfo</i>()</a> and <a href="../functions/getnameinfo.html"><i>getnameinfo</i>()</a>:</p>
|
|
|
|
<dl compact>
|
|
<dt>EAI_AGAIN</dt>
|
|
|
|
<dd>The name could not be resolved at this time. Future attempts may succeed.</dd>
|
|
|
|
<dt>EAI_BADFLAGS</dt>
|
|
|
|
<dd>The flags had an invalid value.</dd>
|
|
|
|
<dt>EAI_FAIL</dt>
|
|
|
|
<dd>A non-recoverable error occurred.</dd>
|
|
|
|
<dt>EAI_FAMILY</dt>
|
|
|
|
<dd>The address family was not recognized or the address length was invalid for the specified family.</dd>
|
|
|
|
<dt>EAI_MEMORY</dt>
|
|
|
|
<dd>There was a memory allocation failure.</dd>
|
|
|
|
<dt>EAI_NONAME</dt>
|
|
|
|
<dd>The name does not resolve for the supplied parameters.
|
|
|
|
<p>NI_NAMEREQD is set and the host's name cannot be located, or both <i>nodename</i> and <i>servname</i> were null.</p>
|
|
</dd>
|
|
|
|
<dt>EAI_SERVICE</dt>
|
|
|
|
<dd>The service passed was not recognized for the specified socket type.</dd>
|
|
|
|
<dt>EAI_SOCKTYPE</dt>
|
|
|
|
<dd>The intended socket type was not recognized.</dd>
|
|
|
|
<dt>EAI_SYSTEM</dt>
|
|
|
|
<dd>A system error occurred. The error code can be found in <i>errno</i>.</dd>
|
|
|
|
<dt>EAI_OVERFLOW</dt>
|
|
|
|
<dd><br>
|
|
An argument buffer overflowed.</dd>
|
|
</dl>
|
|
|
|
<p>The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.</p>
|
|
|
|
<pre>
|
|
<tt>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 *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, unsigned);
|
|
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);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The type <b>socklen_t</b> shall be defined through <b>typedef</b> as described in <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a>.</p>
|
|
|
|
<p>Inclusion of the <i><netdb.h></i> header may also make visible all symbols from <a href=
|
|
"../basedefs/netinet/in.h.html"><i><netinet/in.h></i></a>, <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a>, and <a href=
|
|
"../basedefs/inttypes.h.html"><i><inttypes.h></i></a>.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_13_31_04"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_31_05"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_31_06"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_31_07"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="netinet/in.h.html"><i><netinet/in.h></i></a> , <a href="inttypes.h.html"><i><inttypes.h></i></a> , <a href=
|
|
"sys/socket.h.html"><i><sys/socket.h></i></a> , the System Interfaces volume of IEEE Std 1003.1-2001, <a href=
|
|
"../functions/bind.html"><i>bind</i>()</a>, <a href="../functions/endhostent.html"><i>endhostent</i>()</a>, <a href=
|
|
"../functions/endnetent.html"><i>endnetent</i>()</a>, <a href="../functions/endprotoent.html"><i>endprotoent</i>()</a>, <a href=
|
|
"../functions/endservent.html"><i>endservent</i>()</a>, <a href="../functions/getaddrinfo.html"><i>getaddrinfo</i>()</a>, <a href=
|
|
"../functions/getnameinfo.html"><i>getnameinfo</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_31_08"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 6. Derived from the XNS, Issue 5.2 specification.</p>
|
|
|
|
<p>The Open Group Base Resolution bwg2001-009 is applied, which changes the return type for <a href=
|
|
"../functions/gai_strerror.html"><i>gai_strerror</i>()</a> from <b>char *</b> to <b>const char *</b>. This is for coordination with
|
|
the IPnG Working Group.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|