228 lines
6.9 KiB
Groff
228 lines
6.9 KiB
Groff
.\" Copyright (c) 1996,1999 by Internet Software Consortium
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
|
|
.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
|
|
.\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
|
|
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
|
|
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
|
|
.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
|
|
.\" SOFTWARE.
|
|
.\"
|
|
.\" Copyright (c) 1983, 1987 The Regents of the University of California.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms are permitted provided
|
|
.\" that: (1) source distributions retain this entire copyright notice and
|
|
.\" comment, and (2) distributions including binaries display the following
|
|
.\" acknowledgement: ``This product includes software developed by the
|
|
.\" University of California, Berkeley and its contributors'' in the
|
|
.\" documentation or other materials provided with the distribution and in
|
|
.\" all advertising materials mentioning features or use of this software.
|
|
.\" Neither the name of the University nor the names of its contributors may
|
|
.\" be used to endorse or promote products derived from this software without
|
|
.\" specific prior written permission.
|
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
.Dd September 17, 1999
|
|
.Dt GETIPNODEBYNAME @LIB_NETWORK_EXT_U@
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm getipnodebyname ,
|
|
.Nm getipnodebyaddr
|
|
.Nd get network host entry
|
|
.br
|
|
.Nm freehostent
|
|
.Nd free network host entry
|
|
.Sh SYNOPSIS
|
|
.Fd #include <netdb.h>
|
|
.Pp
|
|
.Ft struct hostent *
|
|
.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error"
|
|
.Ft struct hostent *
|
|
.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error"
|
|
.Ft void
|
|
.Fn freehostent "struct hostent *he"
|
|
.Sh DESCRIPTION
|
|
.Fn Getipnodebyname ,
|
|
and
|
|
.Fn getipnodebyaddr
|
|
each return a pointer to a
|
|
.Ft hostent
|
|
structure (see below) describing an internet host
|
|
referenced by name or by address, as the function names indicate.
|
|
This structure contains either the information obtained from the name server,
|
|
.Xr @INDOT@named @SYS_OPS_EXT@ ,
|
|
or broken-out fields from a line in
|
|
.Pa /etc/hosts .
|
|
If the local name server is not running, these routines do a lookup in
|
|
.Pa /etc/hosts .
|
|
.Bd -literal -offset indent
|
|
struct hostent {
|
|
char *h_name; /* official name of host */
|
|
char **h_aliases; /* alias list */
|
|
int h_addrtype; /* host address type */
|
|
int h_length; /* length of address */
|
|
char **h_addr_list; /* list of addresses from name server */
|
|
};
|
|
|
|
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
|
.Ed
|
|
.Pp
|
|
The members of this structure are:
|
|
.Bl -tag -width "h_addr_list"
|
|
.It h_name
|
|
Official name of the host.
|
|
.It h_aliases
|
|
A zero-terminated array of alternate names for the host.
|
|
.It h_addrtype
|
|
The type of address being returned.
|
|
.It h_length
|
|
The length, in bytes, of the address.
|
|
.It h_addr_list
|
|
A zero-terminated array of network addresses for the host.
|
|
Host addresses are returned in network byte order.
|
|
.It h_addr
|
|
The first address in
|
|
.Li h_addr_list ;
|
|
this is for backward compatibility.
|
|
.El
|
|
.Pp
|
|
This structure should be freed after use by calling
|
|
.Fn freehostent .
|
|
.Pp
|
|
When using the nameserver,
|
|
.Fn getiphostbyaddr
|
|
will search for the named host in each parent domain given in the
|
|
.Dq Li search
|
|
directive of
|
|
.Xr resolv.conf @FORMAT_EXT@
|
|
unless the name contains a dot
|
|
.Pq Dq \&. .
|
|
If the name contains no dot, and if the environment variable
|
|
.Ev HOSTALIASES
|
|
contains the name of an alias file, the alias file will first be searched
|
|
for an alias matching the input name.
|
|
See
|
|
.Xr hostname @DESC_EXT@
|
|
for the domain search procedure and the alias file format.
|
|
.Pp
|
|
.Fn Getiphostbyaddr
|
|
can be told to look for IPv4 addresses, IPv6 addresses or both IPv4 and IPv6.
|
|
If IPv4 addresses only are to be looked up then
|
|
.Fa af
|
|
should be set to
|
|
.Dv AF_INET ,
|
|
otherwise it should be set to
|
|
.Dv AF_INET6 .
|
|
.Pp
|
|
There are three flags that can be set
|
|
.Bl -tag -width "AI_ADDRCONFIG"
|
|
.It Dv AI_V4MAPPED
|
|
Return IPv4 addresses if no IPv6 addresses are found.
|
|
This flag is ignored unless
|
|
.Fa af
|
|
is
|
|
.Dv AF_INET6 .
|
|
.It Dv AI_ALL
|
|
Return IPv4 addresses as well IPv6 addresses if
|
|
.Dv AI_V4MAPPED
|
|
is set.
|
|
This flag is ignored unless
|
|
.Fa af
|
|
is
|
|
.Dv AF_INET6 .
|
|
.It Dv AI_ADDRCONFIG
|
|
Only return addresses of a given type if the system has an active interface
|
|
with that type.
|
|
.El
|
|
.Pp
|
|
Also
|
|
.Dv AI_DEFAULT
|
|
is defined to be
|
|
.Dv (AI_V4MAPPED|AI_ADDRCONFIG) .
|
|
.Pp
|
|
.Fn Getipnodebyaddr
|
|
will lookup IPv4 mapped and compatible addresses in the IPv4 name
|
|
space and IPv6 name space
|
|
.Pp
|
|
.Fn Freehostent
|
|
frees the hostent structure allocated be
|
|
.Fn getipnodebyname
|
|
and
|
|
.Fn getipnodebyaddr .
|
|
The structures returned by
|
|
.Fn gethostbyname ,
|
|
.Fn gethostbyname2 ,
|
|
.Fn gethostbyaddr
|
|
and
|
|
.Fn gethostent
|
|
should not be passed to
|
|
.Fn freehostent
|
|
as they are pointers to static areas.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width "HOSTALIASES " -compact
|
|
.It Ev HOSTALIASES
|
|
Name of file containing
|
|
.Pq Ar host alias , full hostname
|
|
pairs.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "HOSTALIASES " -compact
|
|
.It Pa /etc/hosts
|
|
See
|
|
.Xr hosts @FORMAT_EXT@ .
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
.Pp
|
|
Error return status from
|
|
.Fn getipnodebyname
|
|
and
|
|
.Fn getipnodebyaddr
|
|
is indicated by return of a null pointer.
|
|
In this case
|
|
.Ft error
|
|
may then be checked to see whether this is a temporary failure
|
|
or an invalid or unknown host.
|
|
.Ft errno
|
|
can have the following values:
|
|
.Bl -tag -width "HOST_NOT_FOUND " -offset indent
|
|
.It Dv NETDB_INTERNAL
|
|
This indicates an internal error in the library, unrelated to the network
|
|
or name service.
|
|
.Ft errno
|
|
will be valid in this case; see
|
|
.Xr perror @SYSCALL_EXT@ .
|
|
.It Dv HOST_NOT_FOUND
|
|
No such host is known.
|
|
.It Dv TRY_AGAIN
|
|
This is usually a temporary error
|
|
and means that the local server did not receive
|
|
a response from an authoritative server.
|
|
A retry at some later time may succeed.
|
|
.It Dv NO_RECOVERY
|
|
Some unexpected server failure was encountered.
|
|
This is a non-recoverable error, as one might expect.
|
|
.It Dv NO_ADDRESS
|
|
The requested name is valid but does not have an IP address;
|
|
this is not a temporary error.
|
|
This means that the name is known to the name server but there is no address
|
|
associated with this name.
|
|
Another type of request to the name server using this domain name
|
|
will result in an answer;
|
|
for example, a mail-forwarder may be registered for this domain.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr hosts @FORMAT_EXT@ ,
|
|
.Xr hostname @DESC_EXT@ ,
|
|
.Xr @INDOT@named @SYS_OPS_EXT@ ,
|
|
.Xr resolver @LIB_NETWORK_EXT@ ,
|
|
.Xr resolver @FORMAT_EXT@ ,
|
|
.Xr gethostbyname @LIB_NETWORK_EXT@ ,
|
|
.Xr RFC2553 .
|