.\" 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 .\" Translation revised Wed Dec 30 1998 by Juan Piernas .\" Modified Mon Dec 21 14:49:33 1998, Andries Brouwer (aeb@cwi.nl) .\" Translation revised Sun Apr 4 1999 by Juan Piernas .\" Translation revised Tue Apr 18 2000 by Juan Piernas .\" Traducción revisada por Miguel Pérez Ibars 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 .B extern int h_errno; .sp .BI "struct hostent *gethostbyname(const char *" name ); .sp .B #include " " /* 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\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)