[BACK]Return to gethostbyname.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / net

Annotation of src/lib/libc/net/gethostbyname.3, Revision 1.28

1.28    ! apb         1: .\"    $NetBSD: gethostbyname.3,v 1.27 2004/08/17 13:45:14 wiz Exp $
1.6       cgd         2: .\"
                      3: .\" Copyright (c) 1983, 1987, 1991, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
1.24      agc        14: .\" 3. Neither the name of the University nor the names of its contributors
1.1       cgd        15: .\"    may be used to endorse or promote products derived from this software
                     16: .\"    without specific prior written permission.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     21: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     28: .\" SUCH DAMAGE.
                     29: .\"
1.10      mrg        30: .\"     @(#)gethostbyname.3   8.4 (Berkeley) 5/25/95
1.1       cgd        31: .\"
1.28    ! apb        32: .Dd October 7, 2006
1.1       cgd        33: .Dt GETHOSTBYNAME 3
1.15      garbled    34: .Os
1.1       cgd        35: .Sh NAME
                     36: .Nm gethostbyname ,
1.16      itojun     37: .Nm gethostbyname2 ,
1.1       cgd        38: .Nm gethostbyaddr ,
1.26      ginsbach   39: .Nm gethostent ,
1.1       cgd        40: .Nm sethostent ,
                     41: .Nm endhostent ,
1.7       jtc        42: .Nm herror ,
                     43: .Nm hstrerror
1.1       cgd        44: .Nd get network host entry
1.11      perry      45: .Sh LIBRARY
                     46: .Lb libc
1.1       cgd        47: .Sh SYNOPSIS
1.23      wiz        48: .In netdb.h
1.4       davidb     49: .Fd extern int h_errno;
1.1       cgd        50: .Ft struct hostent *
1.5       deraadt    51: .Fn gethostbyname "const char *name"
1.1       cgd        52: .Ft struct hostent *
1.16      itojun     53: .Fn gethostbyname2 "const char *name" "int af"
                     54: .Ft struct hostent *
1.19      kleink     55: .Fn gethostbyaddr "const char *addr" "socklen_t len" "int type"
1.26      ginsbach   56: .Ft struct hostent *
                     57: .Fn gethostent void
1.7       jtc        58: .Ft void
1.1       cgd        59: .Fn sethostent "int stayopen"
1.7       jtc        60: .Ft void
1.1       cgd        61: .Fn endhostent void
1.7       jtc        62: .Ft void
1.8       lukem      63: .Fn herror "const char *string"
                     64: .Ft const char *
1.7       jtc        65: .Fn hstrerror "int err"
1.1       cgd        66: .Sh DESCRIPTION
                     67: The
1.16      itojun     68: .Fn gethostbyname ,
                     69: .Fn gethostbyname2
1.1       cgd        70: and
                     71: .Fn gethostbyaddr
                     72: functions
                     73: each return a pointer to an object with the
1.28    ! apb        74: following structure describing an internet host.
1.1       cgd        75: .Bd -literal
                     76: struct hostent {
                     77:        char    *h_name;        /* official name of host */
                     78:        char    **h_aliases;    /* alias list */
                     79:        int     h_addrtype;     /* host address type */
                     80:        int     h_length;       /* length of address */
                     81:        char    **h_addr_list;  /* list of addresses from name server */
                     82: };
                     83: #define        h_addr  h_addr_list[0]  /* address, for backward compatibility */
                     84: .Ed
                     85: .Pp
                     86: The members of this structure are:
                     87: .Bl -tag -width h_addr_list
                     88: .It Fa h_name
                     89: Official name of the host.
                     90: .It Fa h_aliases
1.10      mrg        91: A NULL-terminated array of alternative names for the host.
1.1       cgd        92: .It Fa h_addrtype
                     93: The type of address being returned; currently always
                     94: .Dv AF_INET .
                     95: .It Fa h_length
                     96: The length, in bytes, of the address.
                     97: .It Fa h_addr_list
1.10      mrg        98: A NULL-terminated array of network addresses for the host.
1.1       cgd        99: Host addresses are returned in network byte order.
                    100: .It Fa h_addr
                    101: The first address in
                    102: .Fa h_addr_list ;
1.3       jtc       103: this is for backward compatibility.
1.10      mrg       104: .El
1.1       cgd       105: .Pp
1.28    ! apb       106: In the case of
        !           107: .Fn gethostbyname
        !           108: and
        !           109: .Fn gethostbyname2 ,
        !           110: the host is specified by name,
        !           111: or using a string representation of a numeric address.
        !           112: In the case of
        !           113: .Fn gethostbyaddr ,
        !           114: the host is specified using a binary representation of an address.
        !           115: .Pp
        !           116: The returned
        !           117: .Ft "struct hostent"
        !           118: structure may contain
        !           119: the result of a simple string to binary conversion,
        !           120: information obtained from the domain name resolver (see
        !           121: .Xr resolver 3 ) ,
        !           122: broken-out fields from a line in
        !           123: .Pa /etc/hosts ,
        !           124: or database entries supplied by the
        !           125: .Xr yp 8
        !           126: system.
        !           127: The order of the lookups is controlled by the
        !           128: .Sq hosts
        !           129: entry in
        !           130: .Xr nsswitch.conf 5 .
        !           131: .Pp
        !           132: When using the domain name resolver,
1.1       cgd       133: .Fn gethostbyname
1.16      itojun    134: and
                    135: .Fn gethostbyname2
1.1       cgd       136: will search for the named host in the current domain and its parents
                    137: unless the name ends in a dot.
                    138: If the name contains no dot, and if the environment variable
                    139: .Dq Ev HOSTALIASES
                    140: contains the name of an alias file, the alias file will first be searched
                    141: for an alias matching the input name.
                    142: See
                    143: .Xr hostname 7
                    144: for the domain search procedure and the alias file format.
                    145: .Pp
                    146: The
1.16      itojun    147: .Fn gethostbyname2
                    148: function is an evolution of
                    149: .Fn gethostbyname
                    150: which is intended to allow lookups in address families other than
                    151: .Dv AF_INET ,
                    152: for example
                    153: .Dv AF_INET6 .
                    154: Currently the
                    155: .Fa af
                    156: argument must be specified as
                    157: .Dv AF_INET
                    158: or
                    159: .Dv AF_INET6 ,
1.22      wiz       160: else the function will return
1.16      itojun    161: .Dv NULL
                    162: after having set
                    163: .Va h_errno
                    164: to
1.17      itojun    165: .Dv NETDB_INTERNAL .
1.16      itojun    166: .Pp
                    167: The
1.26      ginsbach  168: .Fn gethostent
                    169: function
                    170: reads the next line of the
                    171: .Pa /etc/hosts
                    172: file, opening the file if necessary.
                    173: .Pp
                    174: The
1.1       cgd       175: .Fn sethostent
                    176: function
                    177: may be used to request the use of a connected
                    178: .Tn TCP
                    179: socket for queries.
                    180: If the
                    181: .Fa stayopen
                    182: flag is non-zero,
                    183: this sets the option to send all queries to the name server using
                    184: .Tn TCP
1.12      fair      185: and to retain the connection after each call to
1.16      itojun    186: .Fn gethostbyname ,
1.27      wiz       187: .Fn gethostbyname2 ,
1.1       cgd       188: or
                    189: .Fn gethostbyaddr .
                    190: Otherwise, queries are performed using
                    191: .Tn UDP
                    192: datagrams.
                    193: .Pp
                    194: The
                    195: .Fn endhostent
                    196: function
                    197: closes the
                    198: .Tn TCP
                    199: connection.
1.16      itojun    200: .Pp
                    201: The
                    202: .Fn herror
                    203: function writes a message to the diagnostic output consisting of the
                    204: string parameter
                    205: .Fa s ,
                    206: the constant string ": ", and a message corresponding to the value of
                    207: .Va h_errno .
                    208: .Pp
                    209: The
                    210: .Fn hstrerror
                    211: function returns a string which is the message text corresponding to the
                    212: value of the
                    213: .Fa err
                    214: parameter.
1.1       cgd       215: .Sh FILES
                    216: .Bl -tag -width /etc/hosts -compact
                    217: .It Pa /etc/hosts
                    218: .El
                    219: .Sh DIAGNOSTICS
1.12      fair      220: Error return status from
1.26      ginsbach  221: .Fn gethostbyent ,
1.16      itojun    222: .Fn gethostbyname ,
1.27      wiz       223: .Fn gethostbyname2 ,
1.1       cgd       224: and
                    225: .Fn gethostbyaddr
                    226: is indicated by return of a null pointer.
                    227: The external integer
                    228: .Va h_errno
                    229: may then be checked to see whether this is a temporary failure
                    230: or an invalid or unknown host.
                    231: The routine
                    232: .Fn herror
                    233: can be used to print an error message describing the failure.
                    234: If its argument
                    235: .Fa string
                    236: is
                    237: .Pf non Dv -NULL ,
                    238: it is printed, followed by a colon and a space.
                    239: The error message is printed with a trailing newline.
                    240: .Pp
                    241: The variable
                    242: .Va h_errno
                    243: can have the following values:
                    244: .Bl -tag -width HOST_NOT_FOUND
                    245: .It Dv HOST_NOT_FOUND
                    246: No such host is known.
                    247: .It Dv TRY_AGAIN
                    248: This is usually a temporary error
                    249: and means that the local server did not receive
                    250: a response from an authoritative server.
                    251: A retry at some later time may succeed.
                    252: .It Dv NO_RECOVERY
                    253: Some unexpected server failure was encountered.
                    254: This is a non-recoverable error.
                    255: .It Dv NO_DATA
1.12      fair      256: The requested name is valid but does not have an IP address;
                    257: this is not a temporary error.
1.1       cgd       258: This means that the name is known to the name server but there is no address
                    259: associated with this name.
                    260: Another type of request to the name server using this domain name
                    261: will result in an answer;
                    262: for example, a mail-forwarder may be registered for this domain.
                    263: .El
                    264: .Sh SEE ALSO
                    265: .Xr resolver 3 ,
                    266: .Xr hosts 5 ,
1.13      lukem     267: .Xr nsswitch.conf 5 ,
1.1       cgd       268: .Xr hostname 7 ,
                    269: .Xr named 8
1.25      wiz       270: .Sh HISTORY
                    271: The
                    272: .Fn herror
                    273: function appeared in
                    274: .Bx 4.3 .
                    275: The
                    276: .Fn endhostent ,
                    277: .Fn gethostbyaddr ,
                    278: .Fn gethostbyname ,
1.26      ginsbach  279: .Fn gethostent ,
1.25      wiz       280: and
                    281: .Fn sethostent
                    282: functions appeared in
                    283: .Bx 4.2 .
                    284: The
                    285: .Fn gethostbyname2
                    286: function first appeared in bind-4.9.4.
                    287: IPv6 support was implemented in WIDE Hydrangea IPv6 protocol stack kit.
1.20      wiz       288: .Sh CAVEATS
1.18      itojun    289: If the search routines specified in
                    290: .Xr nsswitch.conf 5
                    291: decide to read the
1.1       cgd       292: .Pa /etc/hosts
1.18      itojun    293: file,
1.26      ginsbach  294: .Fn gethostbyname ,
1.27      wiz       295: .Fn gethostbyname2 ,
                    296: and
1.26      ginsbach  297: .Fn gethostbyaddr
                    298: will
1.18      itojun    299: read the next line of the file,
                    300: re-opening the file if necessary.
1.1       cgd       301: .Pp
                    302: The
                    303: .Fn sethostent
                    304: function
1.6       cgd       305: opens and/or rewinds the file
                    306: .Pa /etc/hosts .
                    307: If the
1.1       cgd       308: .Fa stayopen
                    309: argument is non-zero,
1.6       cgd       310: the file will not be closed after each call to
1.16      itojun    311: .Fn gethostbyname ,
1.27      wiz       312: .Fn gethostbyname2 ,
1.26      ginsbach  313: .Fn gethostbyaddr ,
1.1       cgd       314: or
1.26      ginsbach  315: .Fn gethostent .
1.6       cgd       316: .Pp
1.1       cgd       317: The
                    318: .Fn endhostent
1.18      itojun    319: function closes the file.
1.1       cgd       320: .Sh BUGS
                    321: These functions use static data storage;
                    322: if the data is needed for future use, it should be
                    323: copied before any subsequent calls overwrite it.
                    324: Only the Internet
                    325: address format is currently understood.
1.26      ginsbach  326: .Pp
                    327: The
                    328: .Fn gethostent
1.27      wiz       329: does not currently follow the search order specified in
1.26      ginsbach  330: .Xr nsswitch.conf 5
                    331: and only reads the
                    332: .Pa /etc/hosts
                    333: file.

CVSweb <webmaster@jp.NetBSD.org>