.\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
.\"
.\" 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: RFC 2553
.\"
.\" Traducido por Miguel Pérez Ibars <mpi79470@alu.um.es> el 25-julio-2004
.\"
.TH getaddrinfo 3 "18 diciembre 2000" "Linux Man Page" "Manual del Programador de Linux"
.SH NOMBRE
getaddrinfo \- traducción de servicios y direcciones de red
.SH SINOPSIS
.nf
.B #include <sys/types.h>
.B #include <sys/socket.h>
.B #include <netdb.h>
.sp
.BI "int getaddrinfo(const char *" "node" ", const char *" "service" ,
.BI "                const struct addrinfo *" "hints" ,
.BI "                struct addrinfo **" "res" );
.sp
.BI "void freeaddrinfo(struct addrinfo *" "res" );
.sp
.BI "const char *gai_strerror(int " "errcode" );
.fi
.SH DESCRIPCIÓN
La función
.BR getaddrinfo (3)
combina la funcionalidad provista por las funciones
.BR getipnodebyname (3),
.BR getipnodebyaddr (3),
.BR getservbyname (3),
y
.BR getservbyport (3)
en una única interfaz.
La función hilo-seguro
.BR getaddrinfo (3)
crea una o más estructuras de dirección de socket que pueden ser utilizadas
por las llamadas al sistema
.BR bind (2)
y
.BR connect (2)
para crear un socket cliente o servidor.
.PP
La función
.BR getaddrinfo (3)
no se limita a la creación de estructuras de dirección de socket IPv4;
puede crear estructuras de dirección de socket IPv6 si el soporte para IPv6 está disponible.
Estas estructuras de dirección de socket pueden ser usadas directamente por
.BR bind (2)
o
.BR connect (2),
para preparar un socket cliente o servidor.
.PP
La estructura
.B addrinfo
usada por esta función contiene los siguientes miembros:
.sp
.nf
.B struct addrinfo {
.BI "    int     " "ai_flags" ";"
.BI "    int     " "ai_family" ";"
.BI "    int     " "ai_socktype" ";"
.BI "    int     " "ai_protocol" ";"
.BI "    size_t  " "ai_addrlen" ";"
.BI "    struct sockaddr *" "ai_addr" ";"
.BI "    char   *" "ai_canonname" ";"
.BI "    struct addrinfo *" "ai_next" ";"
.B };
.fi
.PP
.BR getaddrinfo (3)
modifica
.I res
para que apunte a la lista dinámica enlazada de estructuras
.B addrinfo
, enlazada por el miembro
.I ai_next.
Hay muchas razones por las que
la lista enlazada puede tener más de 
una estructura
.B addrinfo
, incluyendo: si el host tiene más de una
dirección IP; o si el mismo servicio
está disponible desde múltiples protocolos de socket (uno
desde una dirección
.B SOCK_STREAM
y otro desde una dirección
.B SOCK_DGRAM
, por ejemplo).
.PP
Los miembros
.IR ai_family ,
.IR ai_socktype ,
y
.I ai_protocol
tienen el mismo significado que los correspondientes parámetros 
de la llamada
.BR socket (2).
La función
.BR getaddrinfo (3)
devuelve direcciones de socket en la familia de direcciones IPv4 o IPv6,
.RI "(" "ai_family"
contendrá
.B PF_INET
o
.BR PF_INET6 ).
.PP
El parámetro
.I hints
especifica el tipo de socket o protocolo preferido.
Un valor de NULL en
.I hints
especifica que cualquier dirección de red o protocolo es aceptable.
Si este parámetro es distinto de
.B NULL
apunta a una estructura
.B addrinfo
cuyos miembros
.IR ai_family ,
.IR ai_socktype ,
y
.I ai_protocol
especifican el tipo de socket preferido.
.B PF_UNSPEC
en
.I ai_family
especifica cualquier familia de protocolos (bien IPv4 o IPv6, por ejemplo).
Un valor de 0 en
.I ai_socktype
o
.I ai_protocol
especifica que cualquier tipo de socket o protocolo es aceptable también.
El miembro
.I ai_flags
especifica opciones adicionales, definidas más abajo.
Se pueden especificar múltiples opciones mediante un OR lógica de todas ellas.
Todos los demás miembros en el parámetro
.I hints
deben contener o bien 0, un puntero null.
.PP
El parámetro
.I node
o
.I service
, pero no ambos, pueden ser NULL.
.I node
especifica o bien una dirección de red numérica
(en formato decimal con puntos para IPv4, format hexadecimal para IPv6)
o un nombre de host, cuyas direcciones de red son buscadas y resueltas.
Si el miembro
.I ai_flags
en el parámetro
.I hints
contiene la opción
.B AI_NUMERICHOST
el parámetro
.I node
debe ser una dirección de red numérica.
La opción
.B AI_NUMERICHOST
suprime cualquier búsqueda larga potencial de direcciones de host.
.PP
La función
.BR getaddrinfo (3)
crea una lista enlazada de estructuras
.B addrinfo
, una para cada dirección de red sujeta a cualquier restricción impuesta
por el parámetro
.I hints.
.I ai_canonname
se modifica para que apunte al nombre oficial del host, si
.I ai_flags
en
.I hints
incluye la opción
.B AI_CANONNAME.
.IR ai_family ,
.IR ai_socktype ,
y
.I ai_protocol
especifican los parámetros de creación del socket.
Se guarda un puntero a la dirección de socket en el miembro
.I ai_addr
, y la longitud de la dirección de socket, en bytes,
se deja en el miembro
.I ai_addrlen.
.PP
Si
.I node
es distinto de NULL,
la 
dirección de red en cada estructura socket es inicializada según la opción
.B AI_PASSIVE
, que es activada en el miembro
.I ai_flags
del parámetro
.I hints.
La dirección de red en cada estructura socket se quedará sin definir
si la opción
.B AI_PASSIVE
está activa.
Ésto es usado por aplicaciones servidoras, que intentan aceptar
conexiones del cliente en cualquier dirección de red.
A la dirección de red se le asignará la dirección de la interfaz de loopback
si la opción
.B AI_PASSIVE
no está activa.
Ésto es usado por aplicaciones cliente, que intentan conectar con
servidores que se ejecutan en el mismo host.
.PP
.I service
establece el número de puerto en la dirección de red de cada estructura socket.
Si
.I service
es NULL el número de puerto se dejará sin inicializar.
.PP
La función
.BR freeaddrinfo (3)
libera la memoria que fue asignada a la
lista dinámica enlazada
.IR res .
.SH "VALOR DEVUELTO"
.BR getaddrinfo (3)
devuelve 0 si tiene éxito, o uno de los siguientes códigos de error:
.TP
.B EAI_FAMILY
La familia de direcciones solicitada no está soportada en absoluto.
.TP
.B EAI_SOCKTYPE
El tipo de socket solicitado no está soportado en absoluto.
.TP
.B EAI_BADFLAGS
.I ai_flags
contiene opciones no válidas.
.TP
.B EAI_NONAME
El nodo
.I node
o el servicio
.I service
no son conocidos.
Este error también se devuelve si tanto
.I node
como
.I service
son NULL.
.TP
.B EAI_SERVICE
El servicio solicitado no está disponible para el tipo de socket solicitado.
Puede estar disponible a través de otro tipo de socket.
.TP
.B EAI_ADDRFAMILY
El host especificado no tiene ninguna dirección de red en la familia
de direcciones especificada.
.TP
.B EAI_NODATA
El host especificado existe, pero no tiene ninguna dirección
de red definida.
.TP
.B EAI_MEMORY
Memoria insuficiente.
.TP
.B EAI_FAIL
El servidor de nombres devolvió una indicación de fallo permanente.
.TP
.B EAI_AGAIN
El servidor de nombres devolvió una indicación de fallo temporal.
Pruebe más tarde.
.TP
.B EAI_SYSTEM
Otro error de sistema, compruebe
.I errno
para más detalles.
.PP
La función
.BR gai_strerror (3)
transforma estos códigos de erro en una cadena comprensible,
adecuada para el informe de errores.
.SH "VÉASE TAMBIÉN"
.BR getipnodebyname (3),
.BR getipnodebyaddr (3)