.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" References consulted:
.\"     Linux libc source code
.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\"     386BSD man pages
.\" Modified Sat May 22 18:43:54 1993, David Metcalfe
.\" Modified Sun Jul 25 10:42:30 1993, Rik Faith (faith@cs.unc.edu)
.\" Modified Sun Feb 16 13:23:10 1997, Andries Brouwer (aeb@cwi.nl)
.\" Modified Mon Dec 21 14:49:33 1998, Andries Brouwer (aeb@cwi.nl)
.\" Modified Sat Aug 12 18:11:32 2000, Andries Brouwer (aeb@cwi.nl)
.\" Modified Sat May 19 23:37:50 2001, Andries Brouwer (aeb@cwi.nl)
.\"
.\" Traducido al castellano (con permiso) por:
.\" Sebastian Desimone (chipy@argenet.com.ar) (desimone@fasta.edu.ar)
.\" Translation revised and fixed on Wed Apr 29 18:30:20 CEST 1998 by
.\"             Gerardo Aburruzaga García <gerardo.aburruzaga@uca.es>
.\" Translation revised Wed Dec 30 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Modified Mon Dec 21 14:49:33 1998, Andries Brouwer (aeb@cwi.nl)
.\" Translation revised Sun Apr  4 1999 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Tue Apr 18 2000 by Juan Piernas <piernas@ditec.um.es>
.\" Traducción revisada por Miguel Pérez Ibars <mpi79470@alu.um.es> el 2-marzo-2005
.\"
.TH GETHOSTBYNAME 3  "12 agosto 2000" "BSD" "Manual del Programador de Linux"
.SH NOMBRE
gethostbyname, gethostbyaddr, sethostent, endhostent, herror, hstrerror \- obtienen una
entrada de anfitrión de red
.SH SINOPSIS
.nf
.B #include <netdb.h>
.B extern int h_errno;
.sp
.BI "struct hostent *gethostbyname(const char *" name );
.sp
.B #include <sys/socket.h> "      " /* para AF_INET */
.BI "struct hostent *gethostbyaddr(const char *" addr ,
.BI "  int " len ", int " type );
.sp
.BI "void sethostent(int " stayopen );
.sp
.B void endhostent(void);
.sp
.BI "void herror(const char *" s );
.sp
.BI "const char *hstrerror(int " err );
.sp 2
/* extensiones de GNU */
.br
.BI "struct hostent *gethostbyname2(const char *" name ", int " af );
.sp
.BI "int gethostbyname_r (const char *" name ,
.BI "  struct hostent *" ret ", char *" buf ", size_t " buflen ,
.BI "  struct hostent **" result ", int *" h_errnop );
.sp
.BI "int gethostbyname2_r (const char *" name ", int " af,
.BI "  struct hostent *" ret ", char *" buf ", size_t " buflen ,
.BI "  struct hostent **" result ", int *" h_errnop );
.fi
.SH DESCRIPCIÓN
La función \fBgethostbyname()\fP devuelve una estructura del tipo \fIhostent\fP
para el anfitrión (host) dado \fIname\fP. 
.\"El dominio corriente y sus ascendientes son
.\"buscados amenos que \fIname\fP termine con un punto. 
Aquí, \fIname\fP 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
.I name
es una dirección IPv4 o IPv6, no se realiza ninguna búsqueda y
.BR gethostbyname ()
simplemente copia
.I name
en el campo
.I h_name
y su equivalente
.I struct in_addr
en el campo
.I h_addr_list[0]
de la estructura
.I hostent
devuelta.
Si \fIname\fP no termina con un punto
y la variable de ambiente \fBHOSTALIASES\fP está
asignada, 
se buscará primero \fIname\fP en el 
fichero de alias señalado por \fBHOSTALIASES\fP
(vea
.BR hostname (7)
para saber cómo es el formato del fichero).
Se buscan el dominio actual y sus ancestros a menos que \fIname\fP
termine en punto.
.PP
La función \fBgethostbyaddr()\fP devuelve una estructura del tipo \fIhostent\fP
para la dirección de anfitrión dada \fIaddr\fP de longitud \fIlen\fP y de tipo
\fItype\fP. El único tipo de dirección válido actualmente es 
.BR AF_INET.
.PP
La función \fBsethostent()\fP especifica, si \fIstayopen\fP 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.
.PP
La función \fBendhostent()\fP termina el uso de una conexión TCP para las 
peticiones al servidor de nombres.
.PP
La (obsoleta) función \fBherror()\fP muestra en stderr un mensaje de error
asociado con el valor actual de \fIh_errno\fP.
.PP
La (obsoleta) función \fBhstrerror()\fP toma un número de error
(habitualmente \fIh_errno\fP) y devuelve la cadena del mensaje correspondiente.
.PP
Las preguntas al servidor de nombres llevadas a cabo por \fBgethostbyname()\fP
y \fBgethostbyaddr()\fP usan una combinación de uno o todos los servidores de
nombres \fBnamed\fP(8), una declaración en \fI/etc/hosts\fP, y el
Servicio de Información de Red (NIS, antes Páginas Amarillas, YP),
dependiendo de los contenidos de la línea 
\fIorder\fP en \fI/etc/host.conf\fP. (Vea 
.BR resolv+ (8)).
La acción predeterminada es preguntar a \fBnamed\fP(8), seguido por
\fI/etc/hosts\fP.
.PP
La estructura \fIhostent\fP se define en \fI<netdb.h>\fP como sigue:
.sp
.RS
.nf
.ne 7
.ta 8n 16n 32n
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 */
.ta
.fi
.RE
.PP
Los miembros de la estructura \fIhostent\fP son:
.TP
.I h_name
El nombre oficial de un anfitrión.
.TP
.I h_aliases
Una cadena terminada en el carácter nulo de los nombres alternativos
para el anfitrión. 
.TP
.I h_addrtype
El tipo de dirección; siempre 
.B AF_INET 
de momento.
.TP
.I h_length
La longitud de la dirección en bytes.
.TP
.I h_addr_list
Una cadena terminada en nulo de direcciones de red para el anfitrión
en orden de bytes de red.
.TP
.I h_addr
La primera dirección en \fIh_addr_list\fP por compatibilidad hacia atrás.
.SH VALOR DEVUELTO
Las funciones \fBgethostbyname()\fP y \fBgethostbyaddr()\fP devuelven la
estructura \fIhostent\fP, o un puntero NULL si ha ocurrido un error. En caso
de error, la variable \fIh_errno\fP contiene un número de error.
.SH "ERRORES"
La variable \fIh_errno\fP puede tener los siguientes valores:
.TP
.B HOST_NOT_FOUND
El anfitrión especificado es desconocido.
.TP
.BR NO_ADDRESS " o " NO_DATA
El nombre pedido es válido pero no tiene una dirrección IP.
.TP
.B NO_RECOVERY
Ha ocurrido un error no recuperable del servidor de nombres.
.TP
.B TRY_AGAIN
Ha ocurrido un error temporal sobre un servidor de nombres con
autoridad. Intente luego más tarde.
.SH FICHEROS
.TP
.I /etc/host.conf
fichero de configuración del resolvedor
.TP
.I /etc/hosts
fichero de base de datos de anfitriones
.fi
.SH "CONFORME A"
BSD 4.3.
.SH OBSERVACIONES
El estandar SUS-v2 contiene fallos y declara el parámetro
.I len
de
.B gethostbyaddr()
de tipo
.IR size_t .
(Esto está equivocado, porque tiene que ser de tipo
.IR int ,
y
.I size_t
no lo es. POSIX 1003.1-2001 lo especifica de tipo
.IR socklen_t ,
lo cual es correcto.)
.LP
Las funciones
.BR gethostbyname ()
y
.BR gethostbyaddr ()
pueden devolver punteros a datos estáticos, que pueden ser sobreescritos por
llamadas posteriores. Copiar la estructura
.I hostent
no es suficiente, puesto que contiene punteros - se requiere una copia en profundidad.
.LP
Glibc2 también tiene una función
.B gethostbyname2()
que hace lo mismo que
.BR gethostbyname() ,
pero permite especificar la familia de direcciones a la que la dirección debe pertenecer.
.LP
Glibc2 también tiene versiones reentrantes
.B gethostbyname_r()
y
.BR 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
.IR ret .
Después de la llamada,
.RI * result
valdrá NULL en caso de error o apuntará al resultado en caso de éxito.
Los datos auxiliares son almacenados en el buffer
.I buf
de longitud
.IR buflen .
(Si el buffer es demasiado pequeño, estas funciones devolverán
.BR ERANGE .)
Ninguna variable global
.I h_errno
es modificada, pero se pasa en
.IR h_errnop
la dirección de una variable donde almacenar números de error.
.PP
POSIX 1003.1-2001 señala que
.B gethostbyaddr()
y
.B gethostbyname()
están anticuadas, e introduce
.sp
.nf
.BI "struct hostent *getipnodebyaddr (const void *restrict " addr ,
.BI "  socklen_t " len ", int " type ", int *restrict " error_num );
.sp
.BI "struct hostent *getipnodebyname (const char *" name ,
.BI "  int " type ", int " flags ", int *" error_num );
.SH "VÉASE TAMBIÉN"
.BR resolver (3),
.BR hosts (5),
.BR hostname (7),
.BR resolv+ (8),
.BR named (8)