.\" Copyright 2000 Sam Varshavchik .\" .\" 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 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 .B #include .B #include .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)