Return to gethostbyname.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / net

Annotation of 43BSDReno/lib/libc/net/gethostbyname.3, revision 1.1

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

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