| <html lang="en"> |
| <head> |
| <title>Host Names - The GNU C Library</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The GNU C Library"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Host-Addresses.html#Host-Addresses" title="Host Addresses"> |
| <link rel="prev" href="Host-Address-Functions.html#Host-Address-Functions" title="Host Address Functions"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU C library. |
| |
| This is Edition 0.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Host-Names"></a> |
| <p> |
| Previous: <a rel="previous" accesskey="p" href="Host-Address-Functions.html#Host-Address-Functions">Host Address Functions</a>, |
| Up: <a rel="up" accesskey="u" href="Host-Addresses.html#Host-Addresses">Host Addresses</a> |
| <hr> |
| </div> |
| |
| <h5 class="subsubsection">16.6.2.4 Host Names</h5> |
| |
| <p><a name="index-hosts-database-1712"></a><a name="index-converting-host-name-to-address-1713"></a><a name="index-converting-host-address-to-name-1714"></a> |
| Besides the standard numbers-and-dots notation for Internet addresses, |
| you can also refer to a host by a symbolic name. The advantage of a |
| symbolic name is that it is usually easier to remember. For example, |
| the machine with Internet address ‘<samp><span class="samp">158.121.106.19</span></samp>’ is also known as |
| ‘<samp><span class="samp">alpha.gnu.org</span></samp>’; and other machines in the ‘<samp><span class="samp">gnu.org</span></samp>’ |
| domain can refer to it simply as ‘<samp><span class="samp">alpha</span></samp>’. |
| |
| <p><a name="index-g_t_002fetc_002fhosts-1715"></a><a name="index-netdb_002eh-1716"></a>Internally, the system uses a database to keep track of the mapping |
| between host names and host numbers. This database is usually either |
| the file <samp><span class="file">/etc/hosts</span></samp> or an equivalent provided by a name server. |
| The functions and other symbols for accessing this database are declared |
| in <samp><span class="file">netdb.h</span></samp>. They are BSD features, defined unconditionally if |
| you include <samp><span class="file">netdb.h</span></samp>. |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Data Type: <b>struct hostent</b><var><a name="index-struct-hostent-1717"></a></var><br> |
| <blockquote><p>This data type is used to represent an entry in the hosts database. It |
| has the following members: |
| |
| <dl> |
| <dt><code>char *h_name</code><dd>This is the “official” name of the host. |
| |
| <br><dt><code>char **h_aliases</code><dd>These are alternative names for the host, represented as a null-terminated |
| vector of strings. |
| |
| <br><dt><code>int h_addrtype</code><dd>This is the host address type; in practice, its value is always either |
| <code>AF_INET</code> or <code>AF_INET6</code>, with the latter being used for IPv6 |
| hosts. In principle other kinds of addresses could be represented in |
| the database as well as Internet addresses; if this were done, you |
| might find a value in this field other than <code>AF_INET</code> or |
| <code>AF_INET6</code>. See <a href="Socket-Addresses.html#Socket-Addresses">Socket Addresses</a>. |
| |
| <br><dt><code>int h_length</code><dd>This is the length, in bytes, of each address. |
| |
| <br><dt><code>char **h_addr_list</code><dd>This is the vector of addresses for the host. (Recall that the host |
| might be connected to multiple networks and have different addresses on |
| each one.) The vector is terminated by a null pointer. |
| |
| <br><dt><code>char *h_addr</code><dd>This is a synonym for <code>h_addr_list[0]</code>; in other words, it is the |
| first host address. |
| </dl> |
| </p></blockquote></div> |
| |
| <p>As far as the host database is concerned, each address is just a block |
| of memory <code>h_length</code> bytes long. But in other contexts there is an |
| implicit assumption that you can convert IPv4 addresses to a |
| <code>struct in_addr</code> or an <code>uint32_t</code>. Host addresses in |
| a <code>struct hostent</code> structure are always given in network byte |
| order; see <a href="Byte-Order.html#Byte-Order">Byte Order</a>. |
| |
| <p>You can use <code>gethostbyname</code>, <code>gethostbyname2</code> or |
| <code>gethostbyaddr</code> to search the hosts database for information about |
| a particular host. The information is returned in a |
| statically-allocated structure; you must copy the information if you |
| need to save it across calls. You can also use <code>getaddrinfo</code> and |
| <code>getnameinfo</code> to obtain this information. |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Function: struct hostent * <b>gethostbyname</b> (<var>const char *name</var>)<var><a name="index-gethostbyname-1718"></a></var><br> |
| <blockquote><p>The <code>gethostbyname</code> function returns information about the host |
| named <var>name</var>. If the lookup fails, it returns a null pointer. |
| </p></blockquote></div> |
| |
| <!-- netdb.h --> |
| <!-- IPv6 Basic API --> |
| <div class="defun"> |
| — Function: struct hostent * <b>gethostbyname2</b> (<var>const char *name, int af</var>)<var><a name="index-gethostbyname2-1719"></a></var><br> |
| <blockquote><p>The <code>gethostbyname2</code> function is like <code>gethostbyname</code>, but |
| allows the caller to specify the desired address family (e.g. |
| <code>AF_INET</code> or <code>AF_INET6</code>) of the result. |
| </p></blockquote></div> |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Function: struct hostent * <b>gethostbyaddr</b> (<var>const char *addr, size_t length, int format</var>)<var><a name="index-gethostbyaddr-1720"></a></var><br> |
| <blockquote><p>The <code>gethostbyaddr</code> function returns information about the host |
| with Internet address <var>addr</var>. The parameter <var>addr</var> is not |
| really a pointer to char - it can be a pointer to an IPv4 or an IPv6 |
| address. The <var>length</var> argument is the size (in bytes) of the address |
| at <var>addr</var>. <var>format</var> specifies the address format; for an IPv4 |
| Internet address, specify a value of <code>AF_INET</code>; for an IPv6 |
| Internet address, use <code>AF_INET6</code>. |
| |
| <p>If the lookup fails, <code>gethostbyaddr</code> returns a null pointer. |
| </p></blockquote></div> |
| |
| <p><a name="index-h_005ferrno-1721"></a>If the name lookup by <code>gethostbyname</code> or <code>gethostbyaddr</code> |
| fails, you can find out the reason by looking at the value of the |
| variable <code>h_errno</code>. (It would be cleaner design for these |
| functions to set <code>errno</code>, but use of <code>h_errno</code> is compatible |
| with other systems.) |
| |
| <p>Here are the error codes that you may find in <code>h_errno</code>: |
| |
| <dl> |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <dt><code>HOST_NOT_FOUND</code><dd><a name="index-HOST_005fNOT_005fFOUND-1722"></a>No such host is known in the database. |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <br><dt><code>TRY_AGAIN</code><dd><a name="index-TRY_005fAGAIN-1723"></a>This condition happens when the name server could not be contacted. If |
| you try again later, you may succeed then. |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <br><dt><code>NO_RECOVERY</code><dd><a name="index-NO_005fRECOVERY-1724"></a>A non-recoverable error occurred. |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <br><dt><code>NO_ADDRESS</code><dd><a name="index-NO_005fADDRESS-1725"></a>The host database contains an entry for the name, but it doesn't have an |
| associated Internet address. |
| </dl> |
| |
| <p>The lookup functions above all have one in common: they are not |
| reentrant and therefore unusable in multi-threaded applications. |
| Therefore provides the GNU C library a new set of functions which can be |
| used in this context. |
| |
| <!-- netdb.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>gethostbyname_r</b> (<var>const char *restrict name, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop</var>)<var><a name="index-gethostbyname_005fr-1726"></a></var><br> |
| <blockquote><p>The <code>gethostbyname_r</code> function returns information about the host |
| named <var>name</var>. The caller must pass a pointer to an object of type |
| <code>struct hostent</code> in the <var>result_buf</var> parameter. In addition |
| the function may need extra buffer space and the caller must pass an |
| pointer and the size of the buffer in the <var>buf</var> and <var>buflen</var> |
| parameters. |
| |
| <p>A pointer to the buffer, in which the result is stored, is available in |
| <code>*</code><var>result</var> after the function call successfully returned. If |
| an error occurs or if no entry is found, the pointer <code>*</code><var>result</var> |
| is a null pointer. Success is signalled by a zero return value. If the |
| function failed the return value is an error number. In addition to the |
| errors defined for <code>gethostbyname</code> it can also be <code>ERANGE</code>. |
| In this case the call should be repeated with a larger buffer. |
| Additional error information is not stored in the global variable |
| <code>h_errno</code> but instead in the object pointed to by <var>h_errnop</var>. |
| |
| <p>Here's a small example: |
| <pre class="smallexample"> struct hostent * |
| gethostname (char *host) |
| { |
| struct hostent hostbuf, *hp; |
| size_t hstbuflen; |
| char *tmphstbuf; |
| int res; |
| int herr; |
| |
| hstbuflen = 1024; |
| /* Allocate buffer, remember to free it to avoid memory leakage. */ |
| tmphstbuf = malloc (hstbuflen); |
| |
| while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen, |
| &hp, &herr)) == ERANGE) |
| { |
| /* Enlarge the buffer. */ |
| hstbuflen *= 2; |
| tmphstbuf = realloc (tmphstbuf, hstbuflen); |
| } |
| /* Check for errors. */ |
| if (res || hp == NULL) |
| return NULL; |
| return hp; |
| } |
| </pre> |
| </blockquote></div> |
| |
| <!-- netdb.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>gethostbyname2_r</b> (<var>const char *name, int af, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop</var>)<var><a name="index-gethostbyname2_005fr-1727"></a></var><br> |
| <blockquote><p>The <code>gethostbyname2_r</code> function is like <code>gethostbyname_r</code>, but |
| allows the caller to specify the desired address family (e.g. |
| <code>AF_INET</code> or <code>AF_INET6</code>) for the result. |
| </p></blockquote></div> |
| |
| <!-- netdb.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>gethostbyaddr_r</b> (<var>const char *addr, size_t length, int format, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop</var>)<var><a name="index-gethostbyaddr_005fr-1728"></a></var><br> |
| <blockquote><p>The <code>gethostbyaddr_r</code> function returns information about the host |
| with Internet address <var>addr</var>. The parameter <var>addr</var> is not |
| really a pointer to char - it can be a pointer to an IPv4 or an IPv6 |
| address. The <var>length</var> argument is the size (in bytes) of the address |
| at <var>addr</var>. <var>format</var> specifies the address format; for an IPv4 |
| Internet address, specify a value of <code>AF_INET</code>; for an IPv6 |
| Internet address, use <code>AF_INET6</code>. |
| |
| <p>Similar to the <code>gethostbyname_r</code> function, the caller must provide |
| buffers for the result and memory used internally. In case of success |
| the function returns zero. Otherwise the value is an error number where |
| <code>ERANGE</code> has the special meaning that the caller-provided buffer is |
| too small. |
| </p></blockquote></div> |
| |
| <p>You can also scan the entire hosts database one entry at a time using |
| <code>sethostent</code>, <code>gethostent</code> and <code>endhostent</code>. Be careful |
| when using these functions because they are not reentrant. |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Function: void <b>sethostent</b> (<var>int stayopen</var>)<var><a name="index-sethostent-1729"></a></var><br> |
| <blockquote><p>This function opens the hosts database to begin scanning it. You can |
| then call <code>gethostent</code> to read the entries. |
| |
| <!-- There was a rumor that this flag has different meaning if using the DNS, --> |
| <!-- but it appears this description is accurate in that case also. --> |
| <p>If the <var>stayopen</var> argument is nonzero, this sets a flag so that |
| subsequent calls to <code>gethostbyname</code> or <code>gethostbyaddr</code> will |
| not close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| </p></blockquote></div> |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Function: struct hostent * <b>gethostent</b> (<var>void</var>)<var><a name="index-gethostent-1730"></a></var><br> |
| <blockquote><p>This function returns the next entry in the hosts database. It |
| returns a null pointer if there are no more entries. |
| </p></blockquote></div> |
| |
| <!-- netdb.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Function: void <b>endhostent</b> (<var>void</var>)<var><a name="index-endhostent-1731"></a></var><br> |
| <blockquote><p>This function closes the hosts database. |
| </p></blockquote></div> |
| |
| </body></html> |
| |
