1GETHOSTBYADDR(P)           POSIX Programmer's Manual          GETHOSTBYADDR(P)
2
3
4

NAME

6       gethostbyaddr, gethostbyname - network host database functions
7

SYNOPSIS

9       #include <netdb.h>
10
11
12
13       struct hostent *gethostbyaddr(const void *addr, socklen_t len,
14              int type);
15       struct hostent *gethostbyname(const char *name);
16
17

DESCRIPTION

19       These  functions  shall retrieve information about hosts. This informa‐
20       tion is considered to be stored in a  database  that  can  be  accessed
21       sequentially  or  randomly. Implementation of this database is unspeci‐
22       fied.
23
24       Note:  In many cases it is implemented by the Domain  Name  System,  as
25              documented in RFC 1034, RFC 1035, and RFC 1886.
26
27
28       Entries shall be returned in hostent structures.
29
30       The gethostbyaddr() function shall return an entry containing addresses
31       of address family type for the host with address addr. The len argument
32       contains  the  length  of  the address pointed to by addr. The gethost‐
33       byaddr() function need  not  be  reentrant.  A  function  that  is  not
34       required to be reentrant is not required to be thread-safe.
35
36       The gethostbyname() function shall return an entry containing addresses
37       of address family AF_INET for the host with name name.  The  gethostby‐
38       name() function need not be reentrant.  A function that is not required
39       to be reentrant is not required to be thread-safe.
40
41       The addr argument of gethostbyaddr() shall be an in_addr structure when
42       type  is AF_INET. It contains a binary format (that is, not null-termi‐
43       nated) address in network byte order. The gethostbyaddr()  function  is
44       not  guaranteed  to  return  addresses  of  address families other than
45       AF_INET, even when such addresses exist in the database.
46
47       If gethostbyaddr() returns successfully, then the h_addrtype  field  in
48       the  result  shall  be the same as the type argument that was passed to
49       the function, and the h_addr_list field shall  list  a  single  address
50       that is a copy of the addr argument that was passed to the function.
51
52       The name argument of gethostbyname() shall be a node name; the behavior
53       of gethostbyname() when passed a numeric address string is unspecified.
54       For IPv4, a numeric address string shall be in the dotted-decimal nota‐
55       tion described in inet_addr() .
56
57       If name is not a numeric address string and is an  alias  for  a  valid
58       host name, then gethostbyname() shall return information about the host
59       name to which the alias refers, and name shall be included in the  list
60       of aliases returned.
61

RETURN VALUE

63       Upon successful completion, these functions shall return a pointer to a
64       hostent structure if the requested entry was found, and a null  pointer
65       if  the  end of the database was reached or the requested entry was not
66       found.
67
68       Upon unsuccessful completion, gethostbyaddr() and gethostbyname() shall
69       set h_errno to indicate the error.
70

ERRORS

72       These  functions shall fail in the following cases. The gethostbyaddr()
73       and gethostbyname() functions shall set h_errno to the value  shown  in
74       the list below. Any changes to errno are unspecified.
75
76       HOST_NOT_FOUND
77
78              No such host is known.
79
80       NO_DATA
81              The  server  recognized the request and the name, but no address
82              is available. Another type of request to the name server for the
83              domain might return an answer.
84
85       NO_RECOVERY
86
87              An unexpected server failure occurred which cannot be recovered.
88
89       TRY_AGAIN
90              A  temporary  and  possibly  transient error occurred, such as a
91              failure of a server to respond.
92
93
94       The following sections are informative.
95

EXAMPLES

97       None.
98

APPLICATION USAGE

100       The gethostbyaddr() and gethostbyname() functions may  return  pointers
101       to  static data, which may be overwritten by subsequent calls to any of
102       these functions.
103
104       The getaddrinfo() and getnameinfo() functions are  preferred  over  the
105       gethostbyaddr() and gethostbyname() functions.
106

RATIONALE

108       None.
109

FUTURE DIRECTIONS

111       The gethostbyaddr() and gethostbyname() functions may be withdrawn in a
112       future version.
113

SEE ALSO

115       endhostent()  ,  endservent()  ,  gai_strerror()  ,   getaddrinfo()   ,
116       h_errno()   ,   inet_addr()   ,   the   Base   Definitions   volume  of
117       IEEE Std 1003.1-2001, <netdb.h>
118

COPYRIGHT

120       Portions of this text are reprinted and reproduced in  electronic  form
121       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
122       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
123       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
124       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
125       event of any discrepancy between this version and the original IEEE and
126       The Open Group Standard, the original IEEE and The Open Group  Standard
127       is  the  referee document. The original Standard can be obtained online
128       at http://www.opengroup.org/unix/online.html .
129
130
131
132IEEE/The Open Group                  2003                     GETHOSTBYADDR(P)