NOMBRE
getnameinfo − traducción dirección-a-nombre de forma independiente del protocolo
SINOPSIS
#include
<sys/socket.h>
#include <netdb.h>
int
getnameinfo(const struct sockaddr *sa,
socklen_t salen,
char *host, size_t hostlen,
char *serv, size_t servlen,
int flags);
DESCRIPCIÓN
La función getnameinfo(3) se define para la traducción dirección-a-nombrenodo de manera independiente del protocolo. Combina la funcionalidad de gethostbyaddr(3) y getservbyport(3) y es la inversa de getaddrinfo(3). El argumento sa es un puntero a una estructura genérica de dirección de conector (socket) (de tipo sockaddr_in o sockaddr_in6) de tamaño salen que contiene la dirección IP y el número del puerto de entrada. Los argumentos host y serv son punteros a buffers (de tamaño hostlen y servlen respectivamente) que se utilizan para almacenar los valores devueltos.
El invocador puede especificar que no se solicita ningún nombre de host (o nombre de servicio) pasando como argumento host (o serv) el valor NULL o asignando cero al parámetro hostlen (o servlen). Sin embargo, al menos uno de los dos, nombre de host o nombre de servicio, debe ser solicitado.
El argumento
flags modifica el comportamiento de
getnameinfo(3) como sigue:
NI_NOFQDN
Si se activa, devuelve solamente la parte del nombre de host correspondiente al FQDN para hosts locales.
NI_NUMERICHOST
Si se activa, se devuelve la forma numérica del nombre de host. (Si no se activa, devolverá igualmente este valor en el caso en que el nombre de nodo no pueda ser buscado.)
NI_NAMEREQD
Si se activa, se devuelve un error cuando el nombre de host no puede ser buscado.
NI_NUMERICSERV
Si se activa, la dirección del servicio se devuelve en formato numérico, por ejemplo, mediante su número de puerto.
NI_DGRAM
Si se activa, el servicio se basa en datagramas (UDP) en vez de basarse en flujos (TCP). Se necesita para los pocos puertos (512-514) que tienen servicios diferentes para UDP y TCP.
VALOR DEVUELTO
Cuando tiene éxito se devuelve 0 y los nombres de nodo y de servicio, si se solicitan, se rellenan con cadenas terminadas en NUL, posiblemente truncadas para ajustarse al tamaño especificado de los buffers. En caso de error se devuelve un valor distinto de cero y se modifica errno apropiadamente.
ERRORES
EAI_AGAIN
El nombre no pudo resolverse en este instante. Pruebe de nuevo más tarde.
EAI_BADFLAGS
El parámetro flags tiene un valor inválido.
EAI_FAIL
Ocurrió un error no recuperable.
EAI_FAMILY
No se reconoció la familia de direcciones o la longitud de la dirección es inválida para la familia especificada.
EAI_MEMORY
Memoria insuficiente.
EAI_NONAME
El nombre no se resuelve para los parámetros pasados. Se especificó la opción NI_NAMEREQD y el nombre de host no pudo ser localizado o ni el nombre de host ni el nombre de servicio fueron solicitados.
EAI_SYSTEM
Ocurrió un error de sistema. El código de error puede encontrarse en errno.
FICHEROS
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf
NOTA
Con el objetivo de ayudar al programador a elegir tamaños razonables para los buffers suministrados, <netdb.h> define las constantes
# define NI_MAXHOST 1025
# define NI_MAXSERV 32
La primera es la constante MAXDNAME en versiones recientes del fichero de cabecera <arpa/nameser.h> de BIND. La última es una suposición basada en los servicios listados en el actual RFC de Numeros Asignados.
EJEMPLOS
El código siguiente trata de obtener el nombre de host y el nombre de servicio en formato numérico, para una dirección de conector dada. Observe que no hay una referencia explícita a una familia de direcciones particular.
struct sockaddr
*sa; /* entrada */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if
(getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
printf("host=%s, serv=%s\n", hbuf, sbuf);
La siguiente versión comprueba si la dirección de conector tiene una correspondencia inversa.
struct sockaddr
*sa; /* entrada */
char hbuf[NI_MAXHOST];
if
(getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
NULL, 0, NI_NAMEREQD))
printf("could not resolve hostname");
else
printf("host=%s\n", hbuf);
CONFORME A
RFC 2553. (Véase también XNS, apartado 5.2.)
VÉASE TAMBIÉN
getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3), inet_ntop(3), socket(3), hosts(5), services(5), hostname(7), named(8)
R. Gilligan, S. Thomson, J. Bound y W. Stevens, Basic Socket Interface Extensions for IPv6, RFC 2553, Marzo de 1999.
Tatsuya Jinmei y Atsushi Onoe, An Extension of Format for IPv6 Scoped Addresses, internet draft, work in progress. ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt
Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track: 2000 USENIX annual technical conference, June 2000. http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html