From fdd0dcbea9558cc9591df8bb65456e13a31f45d9 Mon Sep 17 00:00:00 2001
From: leitner <leitner>
Date: Tue, 17 Sep 2002 01:24:08 +0000
Subject: [PATCH] man pages for the DNS routines, too

---
 dns.h                  |  2 +-
 dns/dns_ip4.3          | 23 +++++++++++++++++++++++
 dns/dns_ip4_packet.3   | 16 ++++++++++++++++
 dns/dns_ip4_qualify.3  | 22 ++++++++++++++++++++++
 dns/dns_ip6.3          | 25 +++++++++++++++++++++++++
 dns/dns_ip6.c          |  4 ++--
 dns/dns_ip6_packet.3   | 16 ++++++++++++++++
 dns/dns_ip6_qualify.3  | 26 ++++++++++++++++++++++++++
 dns/dns_mx.3           | 18 ++++++++++++++++++
 dns/dns_mx_packet.3    | 15 +++++++++++++++
 dns/dns_name4.3        | 17 +++++++++++++++++
 dns/dns_name4_domain.3 | 14 ++++++++++++++
 dns/dns_name6.3        | 17 +++++++++++++++++
 dns/dns_name6_domain.3 | 15 +++++++++++++++
 dns/dns_name_packet.3  | 15 +++++++++++++++
 dns/dns_txt.3          | 17 +++++++++++++++++
 dns/dns_txt_packet.3   | 15 +++++++++++++++
 t.c                    |  2 --
 taia/taia_unpack.c     |  4 +---
 19 files changed, 275 insertions(+), 8 deletions(-)
 create mode 100644 dns/dns_ip4.3
 create mode 100644 dns/dns_ip4_packet.3
 create mode 100644 dns/dns_ip4_qualify.3
 create mode 100644 dns/dns_ip6.3
 create mode 100644 dns/dns_ip6_packet.3
 create mode 100644 dns/dns_ip6_qualify.3
 create mode 100644 dns/dns_mx.3
 create mode 100644 dns/dns_mx_packet.3
 create mode 100644 dns/dns_name4.3
 create mode 100644 dns/dns_name4_domain.3
 create mode 100644 dns/dns_name6.3
 create mode 100644 dns/dns_name6_domain.3
 create mode 100644 dns/dns_name_packet.3
 create mode 100644 dns/dns_txt.3
 create mode 100644 dns/dns_txt_packet.3

diff --git a/dns.h b/dns.h
index 6827512..a2c66f6 100644
--- a/dns.h
+++ b/dns.h
@@ -70,7 +70,7 @@ extern struct dns_transmit dns_resolve_tx;
 
 extern int dns_ip4_packet(stralloc *,const char *,unsigned int);
 extern int dns_ip4(stralloc *,const stralloc *);
-extern int dns_ip6_packet(stralloc *,char *,unsigned int);
+extern int dns_ip6_packet(stralloc *,const char *,unsigned int);
 extern int dns_ip6(stralloc *,stralloc *);
 extern int dns_name_packet(stralloc *,const char *,unsigned int);
 extern void dns_name4_domain(char *,const char *);
diff --git a/dns/dns_ip4.3 b/dns/dns_ip4.3
new file mode 100644
index 0000000..7b6ef9f
--- /dev/null
+++ b/dns/dns_ip4.3
@@ -0,0 +1,23 @@
+.TH dns_ip4 3
+.SH NAME
+dns_ip4 \- look up IPv4 addresses
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_ip4\fP(stralloc* \fIout\fR,stralloc* \fIfqdn\fR);
+.SH DESCRIPTION
+dns_ip4 looks up 4-byte IP addresses for the fully-qualified domain name in
+\fIfqdn\fR. It puts the concatenation of the IP addresses into \fIout\fR and
+returns 0. If the domain does not exist in DNS, or has no IP addresses,
+\fIout\fR will be empty.
+
+If dns_ip4 has trouble with the DNS lookup or runs out of memory, it returns
+-1, setting errno appropriately. It may or may not change \fIout\fR.
+
+If \fIfqdn\fR is a dotted-decimal IP address, dns_ip4 puts that IP address into
+\fIout\fR without checking DNS. More generally, if \fIfqdn\fR is a
+dot-separated sequence of dotted-decimal IP addresses, dns_ip4 puts those IP
+addresses into out without checking DNS. Brackets may appear inside the
+dotted-decimal IP addresses; they are ignored.
+.SH "SEE ALSO"
+dns_ip4_packet(3), dns_ip6(3), dns_name4(3)
diff --git a/dns/dns_ip4_packet.3 b/dns/dns_ip4_packet.3
new file mode 100644
index 0000000..be47cd5
--- /dev/null
+++ b/dns/dns_ip4_packet.3
@@ -0,0 +1,16 @@
+.TH dns_ip4_packet 3
+.SH NAME
+dns_ip4_packet \- extract IPv4 address from DNS answer packet
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_ip4_packet\fP(stralloc* \fIout\fR,const char* \fIbuf\fR,
+                   unsigned int \fIlen\fR);
+.SH DESCRIPTION
+dns_ip4_packet is a low-level component of dns_ip4, designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from
+\fIbuf\fR, extracts IP addresses from the answer section of the packet,
+puts the addresses into \fIout\fR, and returns 0 or -1 the same way as
+dns_ip4.
+.SH "SEE ALSO"
+dns_ip4(3), dns_ip6_packet(3)
diff --git a/dns/dns_ip4_qualify.3 b/dns/dns_ip4_qualify.3
new file mode 100644
index 0000000..77f0d9f
--- /dev/null
+++ b/dns/dns_ip4_qualify.3
@@ -0,0 +1,22 @@
+.TH dns_ip4_qualify 3
+.SH NAME
+dns_ip4_qualify \- qualify name and look up IPv4 addresses
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_ip4_qualify\fP(stralloc* \fIout\fR,stralloc* \fIfqdn\fR,
+                    const stralloc* \fIudn\fR);
+.SH DESCRIPTION
+dns_ip4_qualify feeds the name \fIudn\fR through qualification and looks up
+4-byte IP addresses for the result. It puts the fully qualified domain name
+into \fIfqdn\fR, puts the concatenation of the IP addresses into \fIout\fR, and
+returns 0. If the domain does not exist in DNS, or has no IP addresses,
+\fIout\fR will be empty.
+
+If dns_ip4_qualify has trouble with the qualification, has trouble with DNS, or
+runs out of memory, it returns -1, setting errno appropriately. It may or may
+not change \fIout\fR and \fIfqdn\fR.
+.SH QUALIFICATION
+See http://cr.yp.to/djbdns/qualification.html
+.SH "SEE ALSO"
+dns_ip4(3), dns_ip4_packet(3), dns_ip6_qualify(3)
diff --git a/dns/dns_ip6.3 b/dns/dns_ip6.3
new file mode 100644
index 0000000..b370396
--- /dev/null
+++ b/dns/dns_ip6.3
@@ -0,0 +1,25 @@
+.TH dns_ip6 3
+.SH NAME
+dns_ip6 \- look up IPv4 addresses
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_ip6\fP(stralloc* \fIout\fR,stralloc* \fIfqdn\fR);
+.SH DESCRIPTION
+dns_ip6 looks up 16-byte IPv6 addresses for the fully-qualified domain name in
+\fIfqdn\fR. It puts the concatenation of the IPv6 addresses into \fIout\fR and
+returns 0. If the domain does not exist in DNS, or has no IP addresses,
+\fIout\fR will be empty.
+
+dns_ip6 also looks up 4-byte IPv4 addresses and converts them into
+IPv4-mapped IPv6 addresses (::ffff:1.2.3.4) to provide easy backwards
+compatibility for IPv6 applications.
+
+If dns_ip6 has trouble with the DNS lookup or runs out of memory, it returns
+-1, setting errno appropriately. It may or may not change \fIout\fR.
+
+If \fIfqdn\fR is an IPv6 address, dns_ip6 puts that IP address into
+\fIout\fR without checking DNS.  IPv4 addresses are also used directly
+without DNS lookup.
+.SH "SEE ALSO"
+dns_ip6_packet(3), dns_ip4(3), dns_name6(3)
diff --git a/dns/dns_ip6.c b/dns/dns_ip6.c
index 8df7f82..1a2ce08 100644
--- a/dns/dns_ip6.c
+++ b/dns/dns_ip6.c
@@ -5,7 +5,7 @@
 #include "ip4.h"
 #include "ip6.h"
 
-static int dns_ip6_packet_add(stralloc *out,char *buf,unsigned int len)
+static int dns_ip6_packet_add(stralloc *out,const char *buf,unsigned int len)
 {
   unsigned int pos;
   char header[16];
@@ -41,7 +41,7 @@ static int dns_ip6_packet_add(stralloc *out,char *buf,unsigned int len)
   return 0;
 }
 
-int dns_ip6_packet(stralloc *out,char *buf,unsigned int len) {
+int dns_ip6_packet(stralloc *out,const char *buf,unsigned int len) {
   if (!stralloc_copys(out,"")) return -1;
   return dns_ip6_packet_add(out,buf,len);
 }
diff --git a/dns/dns_ip6_packet.3 b/dns/dns_ip6_packet.3
new file mode 100644
index 0000000..cf793b6
--- /dev/null
+++ b/dns/dns_ip6_packet.3
@@ -0,0 +1,16 @@
+.TH dns_ip6_packet 3
+.SH NAME
+dns_ip6_packet \- extract IPv6 address from DNS answer packet
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_ip6_packet\fP(stralloc* \fIout\fR,const char* \fIbuf\fR,
+                   unsigned int \fIlen\fR);
+.SH DESCRIPTION
+dns_ip6_packet is a low-level component of dns_ip6, designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from
+\fIbuf\fR, extracts IPv4 and IPv6 addresses from the answer section of
+the packet, puts the addresses into \fIout\fR, and returns 0 or -1 the
+same way as dns_ip6.
+.SH "SEE ALSO"
+dns_ip6(3), dns_ip4_packet(3)
diff --git a/dns/dns_ip6_qualify.3 b/dns/dns_ip6_qualify.3
new file mode 100644
index 0000000..7b95412
--- /dev/null
+++ b/dns/dns_ip6_qualify.3
@@ -0,0 +1,26 @@
+.TH dns_ip6_qualify 3
+.SH NAME
+dns_ip6_qualify \- qualify name and look up IPv6 addresses
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_ip6_qualify\fP(stralloc* \fIout\fR,stralloc* \fIfqdn\fR,
+                    const stralloc* \fIudn\fR);
+.SH DESCRIPTION
+dns_ip6_qualify feeds the name \fIudn\fR through qualification and looks up
+16-byte IPv6 addresses for the result. It puts the fully qualified domain name
+into \fIfqdn\fR, puts the concatenation of the IP addresses into \fIout\fR, and
+returns 0. If the domain does not exist in DNS, or has no IP addresses,
+\fIout\fR will be empty.
+
+dns_ip6_qualify also looks up 4-byte IPv4 addresses and converts them
+into IPv4-mapped IPv6 addresses (::ffff:1.2.3.4) to provide easy
+backwards compatibility for IPv6 applications.
+
+If dns_ip6_qualify has trouble with the qualification, has trouble with DNS, or
+runs out of memory, it returns -1, setting errno appropriately. It may or may
+not change \fIout\fR and \fIfqdn\fR.
+.SH QUALIFICATION
+See http://cr.yp.to/djbdns/qualification.html
+.SH "SEE ALSO"
+dns_ip6(3), dns_ip6_packet(3), dns_ip4_qualify(3)
diff --git a/dns/dns_mx.3 b/dns/dns_mx.3
new file mode 100644
index 0000000..bf74177
--- /dev/null
+++ b/dns/dns_mx.3
@@ -0,0 +1,18 @@
+.TH dns_mx 3
+.SH NAME
+dns_mx \- look up Mail eXchanger
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_mx\fP(stralloc* \fIout\fR,stralloc* \fIfqdn\fR);
+.SH DESCRIPTION
+dns_ip4 looks up MX records for the fully-qualified domain name in
+\fIfqdn\fR. It puts the MX records into \fIout\fR and returns 0. Each MX
+record is a two-byte MX distance (big endian) followed by a
+\\0-terminated dot-encoded domain name. If the domain does not exist in
+DNS, or has no MX records, \fIout\fR will be empty.
+
+If dns_mx has trouble with the DNS lookup or runs out of memory, it returns
+-1, setting errno appropriately. It may or may not change \fIout\fR.
+.SH "SEE ALSO"
+dns_mx_packet(3), dns_ip4(3), dns_ip6(3)
diff --git a/dns/dns_mx_packet.3 b/dns/dns_mx_packet.3
new file mode 100644
index 0000000..b14ae6f
--- /dev/null
+++ b/dns/dns_mx_packet.3
@@ -0,0 +1,15 @@
+.TH dns_mx_packet 3
+.SH NAME
+dns_mx_packet \- extract MX records from DNS answer packet
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_mx_packet\fP(stralloc* \fIout\fR,const char* \fIbuf\fR,
+                  unsigned int \fIlen\fR);
+.SH DESCRIPTION
+dns_mx_packet is a low-level component of dns_mx, designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+extracts the MX records from the answer section of the packet, puts the
+result into \fIout\fR, and returns 0 or -1 the same way as dns_mx.
+.SH "SEE ALSO"
+dns_mx(3), dns_ip4(3), dns_ip6(3)
diff --git a/dns/dns_name4.3 b/dns/dns_name4.3
new file mode 100644
index 0000000..d98c1f2
--- /dev/null
+++ b/dns/dns_name4.3
@@ -0,0 +1,17 @@
+.TH dns_name4 3
+.SH NAME
+dns_name4 \- look up host name
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_name4\fP(stralloc* \fIout\fR,const char* \fIip\fR[4]);
+.SH DESCRIPTION
+dns_name4 looks up the domain name for the 4-byte IP address in \fIip\fR. It
+puts the (first) domain name into \fIout\fR and returns 0. If the relevant
+in-addr.arpa domain does not exist in DNS, or has no PTR records, \fIout\fR
+will be empty.
+
+If dns_name4 has trouble with the DNS lookup or runs out of memory, it returns
+-1, setting errno appropriately. It may or may not change \fIout\fR.
+.SH "SEE ALSO"
+dns_name_packet(3), dns_name4_domain(3), dns_name6(3), dns_ip4(3)
diff --git a/dns/dns_name4_domain.3 b/dns/dns_name4_domain.3
new file mode 100644
index 0000000..88b0909
--- /dev/null
+++ b/dns/dns_name4_domain.3
@@ -0,0 +1,14 @@
+.TH dns_name4_domain 3
+.SH NAME
+dns_name4_domain \- construct host name for reverse lookup
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_name4_domain\fP(char \fIq\fR[DNS_NAME4_DOMAIN],
+                     const char* \fIip\fR[4]);
+.SH DESCRIPTION
+dns_name4_domain is a low-level component of dns_name4.  It converts an
+IP address such as 1.2.3.4 into a domain name such as
+4.3.2.1.in-addr.arpa and places the packet-encoded domain name into \fIq\fR.
+.SH "SEE ALSO"
+dns_name4(3), dns_name6_domain(3)
diff --git a/dns/dns_name6.3 b/dns/dns_name6.3
new file mode 100644
index 0000000..d169ec5
--- /dev/null
+++ b/dns/dns_name6.3
@@ -0,0 +1,17 @@
+.TH dns_name6 3
+.SH NAME
+dns_name6 \- look up host name
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_name6\fP(stralloc* \fIout\fR,const char* \fIip\fR[16]);
+.SH DESCRIPTION
+dns_name6 looks up the domain name for the 16-byte IPv6 address in \fIip\fR. It
+puts the (first) domain name into \fIout\fR and returns 0. If the relevant
+ip6.int domain does not exist in DNS, or has no PTR records, \fIout\fR
+will be empty.
+
+If dns_name4 has trouble with the DNS lookup or runs out of memory, it returns
+-1, setting errno appropriately. It may or may not change \fIout\fR.
+.SH "SEE ALSO"
+dns_name_packet(3), dns_name6_domain(3), dns_name4(3), dns_ip6(3)
diff --git a/dns/dns_name6_domain.3 b/dns/dns_name6_domain.3
new file mode 100644
index 0000000..f9d2114
--- /dev/null
+++ b/dns/dns_name6_domain.3
@@ -0,0 +1,15 @@
+.TH dns_name6_domain 3
+.SH NAME
+dns_name6_domain \- construct host name for reverse lookup
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_name6_domain\fP(char \fIq\fR[DNS_NAME6_DOMAIN],
+                     const char* \fIip\fR[16]);
+.SH DESCRIPTION
+dns_name6_domain is a low-level component of dns_name6.  It converts an
+IP address such as 4321:0:1:2:3:4:567:89ab into a domain name such as
+b.a.9.8.7.6.5.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.0.0.0.0.1.2.3.4.IP6.INT
+and places the packet-encoded domain name into \fIq\fR.
+.SH "SEE ALSO"
+dns_name6(3), dns_name4_domain(3)
diff --git a/dns/dns_name_packet.3 b/dns/dns_name_packet.3
new file mode 100644
index 0000000..27f8d8c
--- /dev/null
+++ b/dns/dns_name_packet.3
@@ -0,0 +1,15 @@
+.TH dns_name_packet 3
+.SH NAME
+dns_name_packet \- extract names from DNS answer packet
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_name_packet\fP(stralloc* \fIout\fR,const char* \fIbuf\fR,
+                    unsigned int \fIlen\fR);
+.SH DESCRIPTION
+dns_name_packet is a low-level component of dns_name4, designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+extracts the first PTR record from the answer section of the packet, puts the
+result into \fIout\fR, and returns 0 or -1 the same way as dns_name4.
+.SH "SEE ALSO"
+dns_name4(3), dns_name4(3), dns_ip4_packet(3)
diff --git a/dns/dns_txt.3 b/dns/dns_txt.3
new file mode 100644
index 0000000..0f33306
--- /dev/null
+++ b/dns/dns_txt.3
@@ -0,0 +1,17 @@
+.TH dns_txt 3
+.SH NAME
+dns_txt \- look up TXT records
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_txt\fP(stralloc* \fIout\fR,stralloc* \fIfqdn\fR);
+.SH DESCRIPTION
+dns_ip4 looks up TXT records for the fully-qualified domain name in
+\fIfqdn\fR. It puts the concatenation of the TXT records into \fIout\fR
+and returns 0.  If the domain does not exist in DNS, or has no TXT
+records, \fIout\fR will be empty.
+
+If dns_txt has trouble with the DNS lookup or runs out of memory, it returns
+-1, setting errno appropriately. It may or may not change \fIout\fR.
+.SH "SEE ALSO"
+dns_txt_packet(3)
diff --git a/dns/dns_txt_packet.3 b/dns/dns_txt_packet.3
new file mode 100644
index 0000000..5e23bc0
--- /dev/null
+++ b/dns/dns_txt_packet.3
@@ -0,0 +1,15 @@
+.TH dns_txt_packet 3
+.SH NAME
+dns_txt_packet \- extract TXT records from DNS answer packet
+.SH SYNTAX
+.B #include <dns.h>
+
+int \fBdns_txt_packet\fP(stralloc* \fIout\fR,const char* \fIbuf\fR,
+                  unsigned int \fIlen\fR);
+.SH DESCRIPTION
+dns_txt_packet is a low-level component of dns_mx, designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+extracts the TXT records from the answer section of the packet, puts the
+result into \fIout\fR, and returns 0 or -1 the same way as dns_mx.
+.SH "SEE ALSO"
+dns_mx(3)
diff --git a/t.c b/t.c
index e622281..d7106a7 100644
--- a/t.c
+++ b/t.c
@@ -24,8 +24,6 @@
 int main(int argc,char* argv[]) {
   printf("%d\n",case_starts("fnordhausen","FnOrD"));
   printf("%d\n",case_starts("fnordhausen","blah"));
-  printf("%d\n",case_startb("fnordhausen",5,"FnOrD"));
-  printf("%d\n",case_startb("fnordhausen",1,"foo"));
 #if 0
   char buf[]="FnOrD";
   case_lowers(buf);
diff --git a/taia/taia_unpack.c b/taia/taia_unpack.c
index b1de093..f55ae86 100644
--- a/taia/taia_unpack.c
+++ b/taia/taia_unpack.c
@@ -1,8 +1,6 @@
 #include "taia.h"
 
-void taia_unpack(s,t)
-char *s;
-struct taia *t;
+void taia_unpack(const char* s,struct taia* t)
 {
   unsigned long x;