.\" 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 Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu)
.\" Translated 5 Feb 1998 by Vicente Pastor Gómez <VICPASTOR@santandersupernet.com , vicpastor@hotmail.com>
.TH RESOLVER 3  "21 mayo 1993" "BSD" "Manual del Programador de Linux"
.SH NOMBRE
res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, 
dn_comp, dn_expand \- rutinas "resolver" (de resolución)
.SH SINOPSIS
.nf
.B #include <netinet/in.h>
.B #include <arpa/nameser.h>
.B #include <resolv.h>
.B extern struct state _res;
.sp
.B int res_init(void);
.sp
.BI "int res_query(const char *" dname ", int " class ", int " type ,
.RS
.BI "unsigned char *" answer ", int " anslen );
.RE
.sp
.BI "int res_search(const char *" dname ", int " class ", int " type ,
.RS
.BI "unsigned char *" answer ", int " anslen );
.RE
.sp
.BI "int res_querydomain(const char *" name ", const char *" domain ,
.RS
.BI "int " class ", int " type ", unsigned char *" answer ", int " anslen );
.RE
.sp
.BI "int res_mkquery(int " op ", const char *" dname ", int " class ", int " type ,
.RS
.BI "char *" data ", int " datalen ", struct rrec *" newrr ", char *" buf , 
.BI "int " buflen );
.RE
.sp
.BI "int res_send(const char *" msg ", int " msglen ", char *" answer , 
.RS
.BI "int " anslen );
.RE
.sp
.BI "int dn_comp(unsigned char *" exp_dn ", unsigned char *" comp_dn ,
.RS
.BI "int " length ", unsigned char **" dnptrs ", unsigned char *" exp_dn ,
.BI "unsigned char **" lastdnptr );
.RE
.sp
.BI "int dn_expand(unsigned char *" msg ", unsigned char *" eomorig ,
.RS
.BI "unsigned char *" comp_dn ", unsigned char *" exp_dn ", int " length );
.RE
.fi
.SH DESCRIPCIÓN
Estas funciones hacen peticiones e interpretan las respuestas de los servidores
de nombres de dominio de Internet.
.PP
La función \fBres_init()\fP lee los ficheros de configuración (ver resolv+(8))
para conseguir el nombre del dominio por defecto, orden de búsqueda y la
dirección(es) del servidor(es) de nombres. Si no se proporciona servidor, se
intenta con el host local. Si no se proporciona dominio, se usa el asociado al
host local. Este puede sobreescribirse con la variable de entorno LOCALDOMAIN.
Normalmente \fBres_init()\fP es ejecutado por la primera llamada a una de las
otras funciones.
.PP
La función \fBres_query()\fP pide al servidor de nombres el nombre de dominio
completamente cualificado \fIname\fP de \fItype\fP y \fIclass\fP especificados.
La respuesta se deja en el buffer \fIanswer\fP de longitud \fIanslen\fP
proporcionado por quien realiza la llamada.
.PP
La función \fBres_search()\fP hace una petición y espera la respuesta como
\fBres_query()\fP, pero además implementa las reglas por defecto y las de
búsqueda controladas por RES_DEFNAMES y RES_DNSRCH (ver más abajo la
descripción de las opciones de \fI_res\fP).
.PP
La función \fBres_querydomain()\fP hace una petición utilizando
\fBres_query()\fP en la concatenación de \fIname\fP y \fIdomain\fP.
.PP
Las siguientes son funciones de un nivel más bajo utilizadas por
\fBres_query()\fP.
.PP
La función \fBres_mkquery()\fP construye un mensaje de petición en \fIbuf\fP
de longitud \fIbuflen\fP para el nombre de dominio \fIdname\fP.
El tipo de petición \fIop\fP normalmente es QUERY, pero puede ser cualquiera
de los tipos definidos en \fI<arpa/nameser.h>\fP. \fInewrr\fP actualmente no
se usa.
.PP
La función \fBres_send()\fP envía una petición preformateada, dada en
\fImsg\fP de longitud \fImsglen\fP y devuelve la respuesta en \fIanswer\fP
que tiene longitud \fIanslen\fP. Este llamará a \fBres_init()\fP, si aún no
ha sido llamado.
.PP
La función \fBdn_comp()\fP comprime el nombre de dominio \fIexp_dn\fP
y lo guarda en el buffer \fIcomp_dn\fP de longitud \fIlength\fP.
La compresión usa una matriz de punteros \fIdnptrs\fP a nombres previamente
comprimidos en el mensaje actual. El primero de los punteros apunta al
principio del mensaje y la lista termina con NULL. El límite de la matriz
está especificado por \fIlastdnptr\fP.  Si \fIdnptr\fP es NULL,
los nombres de dominio no se comprimen. Si \fIlastdnptr\fP es NULL, la lista
de etiquetas no se actualiza.
.PP
La función \fPdn_expand()\fP expande el nombre de dominio comprimido
\fIcomp_dn\fP a un nombre de dominio completo, y es puesto en el buffer
\fIexp_dn\fP de tamaño \fIlength\fP. El nombre comprimido está contenido
en una petición o mensaje de respuesta, y \fImsg\fP apunta al principio del
mensaje.
.PP
Las rutinas del "resolver" usan la configuración global e información del
estado contenida en la estructura \fI_res\fP, definida en \fI<resolv.h>\fP.
El único campo que puede manipular normalmente el usuario es
\fI_res.options\fP. Este campo puede contener un "o (OR) lógico" bit a bit
de las siguientes opciones:
.sp
.TP
.B RES_INIT
Cierto si \fBres_init()\fP ha sido llamado.
.TP
.B RES_DEBUG
Imprimir mensajes de depuración.
.TP
.B RES_AAONLY
Aceptar respuestas autoritativas solamente. \fBres_send()\fP continua hasta
que encuentra una respuesta autoritativa o devuelve un error. [Àún no
implementado].
.TP
.B RES_USEVC
Usar conexiones TCP para las peticiones, en vez de datagramas UDP.
.TP
.B RES_PRIMARY
Hacer petición solamente al servidor de nombres de dominio primario.
.TP
.B RES_IGNTC
Ignorar errores de truncado. No reintentar con TCP. [Aún no implementado].
.TP
.B RES_RECURSE
Poner a 1 el bit de recursión deseada en las peticiones. La recursión es
llevada a cabo por el servidor de nombres de dominio, no por \fBres_send()\fP.
[Activado por defecto].
.TP
.B RES_DEFNAMES
Si está puesto a 1, \fBres_search()\fP añadirá el nombre de dominio por defecto
a los nombres de componentes simples, p.ej. aquellos que no contienen punto.
[Activado por defecto].
.TP
.B RES_STAYOPEN
Usado con RES_USEVC para mantener la conexión TCP abierta entre peticiones.
.TP
.B RES_DNSRCH
Si está a 1, \fBres_search()\fP buscará nombres de host en el dominio actual y
en los dominios "padre". Esta opción es usada por
.BR gethostbyname (3).
[Activado por defecto].
.SH "VALOR DEVUELTO"
La función \fBres_init()\fP devuelve 0 si hay éxito, o \-1 si hubo un error.
.PP
Las funciones \fBres_query()\fP, \fBres_search()\fP, \fBres_querydomain()\fP,
\fBres_mkquery()\fP y \fBres_send()\fP devuelven la longitud de la respuesta, o
\-1 si hubo un error.
.PP
Las funciones \fBdn_comp()\fP y \fBdn_expand()\fP devuelven la longitud del
nombre comprimido, o \-1 si hubo un error.
.SH FICHEROS
.nf
/etc/resolv.conf          fichero de configuración de resolver
/etc/host.conf            fichero de configuración de resolver
.fi
.SH "CONFORME A"
BSD 4.3
.SH "VÉASE TAMBIÉN"
.BR gethostbyname "(3), " hostname "(7), " named "(8), " resolv+ (8)