Return to gethostbyname.3 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3

Annotation of 43BSDTahoe/man/man3/gethostbyname.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983,1987 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)gethostbyname.3     6.9 (Berkeley) 4/5/88
        !             6: .\"
        !             7: .TH GETHOSTBYNAME 3N "April 5, 1988"
        !             8: .UC 5
        !             9: .SH NAME
        !            10: gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry
        !            11: .SH SYNOPSIS
        !            12: .B "#include <netdb.h>
        !            13: .PP
        !            14: .B "extern int h_errno;
        !            15: .PP
        !            16: .B "struct hostent *gethostbyname(name)
        !            17: .br
        !            18: .B "char *name;
        !            19: .PP
        !            20: .B "struct hostent *gethostbyaddr(addr, len, type)
        !            21: .br
        !            22: .B "char *addr; int len, type;
        !            23: .PP
        !            24: .B "struct hostent *gethostent()
        !            25: .PP
        !            26: .B "sethostent(stayopen)
        !            27: .br
        !            28: .B "int stayopen;
        !            29: .PP
        !            30: .B "endhostent()
        !            31: .PP
        !            32: .B "herror(string)
        !            33: .br
        !            34: .B "char *string;
        !            35: .PP
        !            36: .SH DESCRIPTION
        !            37: .I Gethostbyname
        !            38: and
        !            39: .I gethostbyaddr
        !            40: each return a pointer to an object with the
        !            41: following structure describing an internet host
        !            42: referenced by name or by address, respectively.
        !            43: This structure contains either the information obtained from the name server,
        !            44: .IR named (8),
        !            45: or broken-out fields from a line in 
        !            46: .IR /etc/hosts .
        !            47: If the local name server is not running these routines do a lookup in
        !            48: .IR /etc/hosts .
        !            49: .RS
        !            50: .PP
        !            51: .nf
        !            52: struct hostent {
        !            53:        char    *h_name;        /* official name of host */
        !            54:        char    **h_aliases;    /* alias list */
        !            55:        int     h_addrtype;     /* host address type */
        !            56:        int     h_length;       /* length of address */
        !            57:        char    **h_addr_list;  /* list of addresses from name server */
        !            58: };
        !            59: #define        h_addr  h_addr_list[0]  /* address, for backward compatibility */
        !            60: .ft R
        !            61: .ad
        !            62: .fi
        !            63: .RE
        !            64: .PP
        !            65: The members of this structure are:
        !            66: .TP \w'h_addr_list'u+2n
        !            67: h_name
        !            68: Official name of the host.
        !            69: .TP \w'h_addr_list'u+2n
        !            70: h_aliases
        !            71: A zero terminated array of alternate names for the host.
        !            72: .TP \w'h_addr_list'u+2n
        !            73: h_addrtype
        !            74: The type of address being returned; currently always AF_INET.
        !            75: .TP \w'h_addr_list'u+2n
        !            76: h_length
        !            77: The length, in bytes, of the address.
        !            78: .TP \w'h_addr_list'u+2n
        !            79: h_addr_list
        !            80: A zero terminated array of network addresses for the host.
        !            81: Host addresses are returned in network byte order.
        !            82: .TP \w'h_addr_list'u+2n
        !            83: h_addr
        !            84: The first address in h_addr_list; this is for backward compatiblity.
        !            85: .PP
        !            86: When using the nameserver,
        !            87: .I gethostbyname
        !            88: will search for the named host in the current domain and its parents
        !            89: unless the name ends in a dot.
        !            90: If the name contains no dot, and if the environment variable ``HOSTALAIASES''
        !            91: contains the name of an alias file, the alias file will first be searched
        !            92: for an alias matching the input name.
        !            93: See
        !            94: .IR hostname (7)
        !            95: for the domain search procedure and the alias file format.
        !            96: .PP
        !            97: .I Sethostent
        !            98: may be used to request the use of a connected TCP socket for queries.
        !            99: If the
        !           100: .I stayopen
        !           101: flag is non-zero,
        !           102: this sets the option to send all queries to the name server using TCP
        !           103: and to retain the connection after each call to 
        !           104: .I gethostbyname
        !           105: or
        !           106: .IR gethostbyaddr .
        !           107: Otherwise, queries are performed using UDP datagrams.
        !           108: .PP
        !           109: .I Endhostent
        !           110: closes the TCP connection.
        !           111: .SH DIAGNOSTICS
        !           112: .PP
        !           113: Error return status from 
        !           114: .I gethostbyname
        !           115: and
        !           116: .I gethostbyaddr
        !           117: is indicated by return of a null pointer.
        !           118: The external integer
        !           119: .IR h_errno
        !           120: may then be checked to see whether this is a temporary failure
        !           121: or an invalid or unknown host.
        !           122: The routine
        !           123: .I herror
        !           124: can be used to print an error message describing the failure.
        !           125: If its argument
        !           126: .I string
        !           127: is non-NULL, it is printed, followed by a colon and a space.
        !           128: The error message is printed with a trailing newline.
        !           129: .PP
        !           130: .IR h_errno
        !           131: can have the following values:
        !           132: .RS
        !           133: .IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n
        !           134: No such host is known.
        !           135: .IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n
        !           136: This is usually a temporary error
        !           137: and means that the local server did not receive
        !           138: a response from an authoritative server.
        !           139: A retry at some later time may succeed.
        !           140: .IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n
        !           141: Some unexpected server failure was encountered.
        !           142: This is a non-recoverable error.
        !           143: .IP NO_DATA \w'HOST_NOT_FOUND'u+2n
        !           144: The requested name is valid but does not have an IP address; 
        !           145: this is not a temporary error.  
        !           146: This means that the name is known to the name server but there is no address
        !           147: associated with this name.
        !           148: Another type of request to the name server using this domain name
        !           149: will result in an answer;
        !           150: for example, a mail-forwarder may be registered for this domain.
        !           151: .RE
        !           152: .SH FILES
        !           153: /etc/hosts
        !           154: .SH "SEE ALSO"
        !           155: resolver(3), hosts(5), hostname(7), named(8)
        !           156: .SH CAVEAT
        !           157: .PP
        !           158: .I Gethostent
        !           159: is defined, and
        !           160: .I sethostent
        !           161: and
        !           162: .I endhostent
        !           163: are redefined,
        !           164: when
        !           165: .IR libc
        !           166: is built to use only the routines to lookup in
        !           167: .IR /etc/hosts 
        !           168: and not the name server.
        !           169: .PP
        !           170: .I Gethostent
        !           171: reads the next line of
        !           172: .IR /etc/hosts ,
        !           173: opening the file if necessary.
        !           174: .PP
        !           175: .I Sethostent 
        !           176: is redefined to open and rewind the file.  If the
        !           177: .I stayopen
        !           178: argument is non-zero,
        !           179: the hosts data base will not be closed after each call to
        !           180: .I gethostbyname
        !           181: or
        !           182: .IR gethostbyaddr .
        !           183: .I Endhostent
        !           184: is redefined to close the file.
        !           185: .SH BUGS
        !           186: All information
        !           187: is contained in a static area
        !           188: so it must be copied if it is
        !           189: to be saved.  Only the Internet
        !           190: address format is currently understood.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.