NOMBRE¶
gethostbyname, gethostbyaddr, sethostent, endhostent, herror, hstrerror -
obtienen una entrada de anfitrión de red
SINOPSIS¶
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* para AF_INET */
struct hostent *gethostbyaddr(const char *addr,
int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
const char *hstrerror(int err);
/* extensiones de GNU */
struct hostent *gethostbyname2(const char *name, int af);
int gethostbyname_r (const char *name,
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);
int gethostbyname2_r (const char *name, int af,
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);
DESCRIPCIÓN¶
La función
gethostbyname() devuelve una estructura del tipo
hostent para el anfitrión (host) dado
name. Aquí,
name es ora un nombre de anfitrión, ora una dirección
IPv4 en la notación normal de puntos, ora una dirección IPv6 en
la notación de dos puntos (y posiblemente de puntos). (Vea la RFC 1884
para una descripción de las direcciones en IPv6). Si
name es una
dirección IPv4 o IPv6, no se realiza ninguna búsqueda y
gethostbyname() simplemente copia
name en el campo
h_name
y su equivalente
struct in_addr en el campo
h_addr_list[0] de la
estructura
hostent devuelta. Si
name no termina con un punto y
la variable de ambiente
HOSTALIASES está asignada, se
buscará primero
name en el fichero de alias señalado por
HOSTALIASES (vea
hostname(7) para saber cómo es el
formato del fichero). Se buscan el dominio actual y sus ancestros a menos que
name termine en punto.
La función
gethostbyaddr() devuelve una estructura del tipo
hostent para la dirección de anfitrión dada
addr
de longitud
len y de tipo
type. El único tipo de
dirección válido actualmente es
AF_INET.
La función
sethostent() especifica, si
stayopen es true
(1), que se debería emplear un conector (socket) TCP para las
interrogaciones al servidor de nombres y que la conexión debería
permanecer abierta durante sucesivas preguntas. De otro modo, las peticiones
al servidor de nombres utilizarán datagramas UDP.
La función
endhostent() termina el uso de una conexión TCP
para las peticiones al servidor de nombres.
La (obsoleta) función
herror() muestra en stderr un mensaje de
error asociado con el valor actual de
h_errno.
La (obsoleta) función
hstrerror() toma un número de error
(habitualmente
h_errno) y devuelve la cadena del mensaje
correspondiente.
Las preguntas al servidor de nombres llevadas a cabo por
gethostbyname()
y
gethostbyaddr() usan una combinación de uno o todos los
servidores de nombres
named(8), una declaración en
/etc/hosts, y el Servicio de Información de Red (NIS, antes
Páginas Amarillas, YP), dependiendo de los contenidos de la
línea
order en
/etc/host.conf. (Vea
resolv+(8)).
La acción predeterminada es preguntar a
named(8), seguido por
/etc/hosts.
La estructura
hostent se define en
<netdb.h> como sigue:
struct hostent {
char *h_name; /* nombre oficial del anfitrión */
char **h_aliases; /* lista de alias */
int h_addrtype; /* tipo dirección anfitrión */
int h_length; /* longitud de la dirección */
char **h_addr_list; /* lista de direcciones */
}
#define h_addr h_addr_list[0] /* por compatibilidad atrás */
Los miembros de la estructura
hostent son:
- h_name
- El nombre oficial de un anfitrión.
- h_aliases
- Una cadena terminada en el carácter nulo de los nombres
alternativos para el anfitrión.
- h_addrtype
- El tipo de dirección; siempre AF_INET de momento.
- h_length
- La longitud de la dirección en bytes.
- h_addr_list
- Una cadena terminada en nulo de direcciones de red para el
anfitrión en orden de bytes de red.
- h_addr
- La primera dirección en h_addr_list por compatibilidad hacia
atrás.
VALOR DEVUELTO¶
Las funciones
gethostbyname() y
gethostbyaddr() devuelven la
estructura
hostent, o un puntero NULL si ha ocurrido un error. En caso
de error, la variable
h_errno contiene un número de error.
ERRORES¶
La variable
h_errno puede tener los siguientes valores:
- HOST_NOT_FOUND
- El anfitrión especificado es desconocido.
- NO_ADDRESS o NO_DATA
- El nombre pedido es válido pero no tiene una dirrección
IP.
- NO_RECOVERY
- Ha ocurrido un error no recuperable del servidor de nombres.
- TRY_AGAIN
- Ha ocurrido un error temporal sobre un servidor de nombres con autoridad.
Intente luego más tarde.
FICHEROS¶
- /etc/host.conf
- fichero de configuración del resolvedor
- /etc/hosts
- fichero de base de datos de anfitriones
BSD 4.3.
OBSERVACIONES¶
El estandar SUS-v2 contiene fallos y declara el parámetro
len de
gethostbyaddr() de tipo
size_t. (Esto está equivocado,
porque tiene que ser de tipo
int, y
size_t no lo es. POSIX
1003.1-2001 lo especifica de tipo
socklen_t, lo cual es correcto.)
Las funciones
gethostbyname() y
gethostbyaddr() pueden devolver
punteros a datos estáticos, que pueden ser sobreescritos por llamadas
posteriores. Copiar la estructura
hostent no es suficiente, puesto que
contiene punteros - se requiere una copia en profundidad.
Glibc2 también tiene una función
gethostbyname2() que hace
lo mismo que
gethostbyname(), pero permite especificar la familia de
direcciones a la que la dirección debe pertenecer.
Glibc2 también tiene versiones reentrantes
gethostbyname_r() y
gethostbyname2_r(). Estas devuelven 0 en caso de éxito y un
valor distinto de cero en caso de error. El resultado de la llamada es
almacenado en la estructura con la dirección
ret. Después
de la llamada, *
result valdrá NULL en caso de error o
apuntará al resultado en caso de éxito. Los datos auxiliares son
almacenados en el buffer
buf de longitud
buflen. (Si el buffer
es demasiado pequeño, estas funciones devolverán
ERANGE.)
Ninguna variable global
h_errno es modificada, pero se pasa en
h_errnop la dirección de una variable donde almacenar
números de error.
POSIX 1003.1-2001 señala que
gethostbyaddr() y
gethostbyname() están anticuadas, e introduce
struct hostent *getipnodebyaddr (const void *restrict addr,
socklen_t len, int type, int *restrict error_num);
struct hostent *getipnodebyname (const char *name,
int type, int flags, int *error_num);
VÉASE TAMBIÉN¶
resolver(3),
hosts(5),
hostname(7),
resolv+(8),
named(8)