From: Ian Jackson Date: Sun, 19 Oct 2014 22:36:57 +0000 (+0100) Subject: Documentation and webpage updates X-Git-Tag: adns-1.5.0-rc0~27 X-Git-Url: https://git.distorted.org.uk/~mdw/adns/commitdiff_plain/2a9e6abd955dc1d32f298ff99376096c634f47ff Documentation and webpage updates Signed-off-by: Ian Jackson --- diff --git a/INSTALL b/INSTALL index 3b6fac5..95a4f6d 100644 --- a/INSTALL +++ b/INSTALL @@ -61,7 +61,7 @@ free to send me patches to improve the situation. However, the Makefiles only know how to use GCC to make dynamic libraries. The adnsresfilter utility uses `tsearch' from the C library (a la SVID -and X/Open). If you don't have tsearch configure will arranges for +and X/Open). If you don't have tsearch configure will arrange for adnsresfilter not to be built. To fix this, install a C library containing tsearch, such as the GNU C library. It is best if tsearch uses an automatically-balancing tree algorithm, like the glibc version @@ -98,16 +98,17 @@ COPYRIGHT This file, INSTALL, contains installation instructions and other details for adns. It is - Copyright (C) 1997-2000 Ian Jackson + Copyright (C) 1997-2000 Ian Jackson adns is - Copyright (C) 1997-2000,2003,2006 Ian Jackson + Copyright (C) 1997-2000,2003,2006,2014 Ian Jackson + Copyright (C) 2014 Mark Wooding Copyright (C) 1999-2000,2003,2006 Tony Finch [1] Copyright (C) 1991 Massachusetts Institute of Technology [2] adns is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free -Software Foundation; either version 2 of the License, or (at your +Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but diff --git a/README b/README index 00c8140..97a38ee 100644 --- a/README +++ b/README @@ -1,35 +1,34 @@ + GNU adns - GNU adns - Advanced, easy to use, asynchronous-capable DNS client library and utilities. - + adns is a resolver library for C (and C++) programs, and a collection of useful DNS resolver utilities. - + C library In contrast with the standard interfaces, gethostbyname et al and libresolv, it has the following features: - * It is reasonably easy to use for simple programs which just want - to translate names to addresses, look up MX records, etc. + * It is reasonably easy to use for simple programs which just want to + translate names to addresses, look up MX records, etc. * It can be used in an asynchronous, non-blocking, manner. Many queries can be handled simultaneously. * Responses are decoded automatically into a natural representation - for a C program - there is no need to deal with DNS packet - formats. + for a C program - there is no need to deal with DNS packet and + RRDATA formats. * Sanity checking (eg, name syntax checking, reverse/forward - correspondence, CNAME pointing to CNAME) is performed - automatically. - * Time-to-live, CNAME and other similar information is returned in - an easy-to-use form, without getting in the way. + correspondence, CNAME pointing to CNAME) is performed automatically + by default. + * Time-to-live, CNAME and other similar information is returned in an + easy-to-use form, without getting in the way. * There is no global state in the library; resolver state is an opaque data structure which the client creates explicitly. A program can have several instances of the resolver. * Errors are reported to the application in a way that distinguishes the various causes of failure properly. - * Understands conventional resolv.conf, but this can overridden by - environment variables. + * adns understands conventional resolv.conf, but this can overridden + by environment variables. * Flexibility. For example, the application can tell adns to: ignore environment variables (for setuid programs), disable hostname syntax sanity checks to return arbitrary data, override or ignore @@ -38,7 +37,7 @@ C library TCP in case of long replies or queries, or to other nameservers if several are available. It has sensible handling of bad responses etc. - + DNS utility programs adns also comes with a number of utility programs for use from the @@ -49,150 +48,123 @@ DNS utility programs delaying the output. For example, you can usefully pipe the output of netstat -n, tcpdump -ln, and the like, into it. * adnshost is a general-purpose DNS lookup utility which can be used - easily in from the command line and from shell scripts to do - simple lookups. In a more advanced mode it can be used as a + easily in from the command line and from shell scripts to do simple + lookups. In a more advanced mode it can be used as a general-purpose DNS helper program for scripting languages which can invoke and communicate with subprocesses. See the [1]adnshost usage message for a summary of its capabilities. - -Forthcoming: - - I hope that future versions may also have the following features: - * The library should be useable by threads in a multithreaded - program in a natural way. It should multiplex many threads' - queries through a single query socket. - * IPv6 support. - * Some kind of awareness of DNSSEC. - * Possibly some very limited caching behaviour. - * There was, at one point, a draft native Perl interface from Tony - Finch. - + Documentation I'm afraid there is no manual yet. However, competent C programmers should be able to use the library based on the [2]commented adns.h header file, and the usage messages for the programs should be sufficient. - + Feedback I'd be pleased if you would let me know if you're using my library in your project, and what you think of it. - - If you are subscribed to adns-discuss please send feedback, including - bug reports, there; otherwise send mail to - adns-bugreports@chiark.greenend.org.uk. If you'd prefer that your - message wasn't forwarded to the adns-bugreports list, send it to - adns-maint@chiark.greenend.org.uk. - + + Bug reports should be reported to the [3]GNU Debbugs. Send an email to + submit@debbugs.gnu.org and at the top of your email, in a paragraph of + its own, write the single line +Package: adns + + Your bug report will be published via to the adns-discuss list. + + Feedback and discussion takes place on the adns-discuss list. You can + mail me privately at ijackson@chiark.greenend.org.uk. + Mailinglists I have set up mailinglists adns-announce and adns-discuss. The announcements list is moderated and will contain only announcements of - important bugs, new versions, etc. The bug reports address mentioned - above is also a mailing list; feel free to subscribe to it. - - There are [3]archives and subscription web pages, or you can subscribe + important bugs, new versions, etc. + + There are [4]archives and subscription web pages, or you can subscribe by sending mail containing the word `subscribe' to adns-announce-REQUEST@chiark.greenend.org.uk or adns-discuss-REQUEST@chiark.greenend.org.uk. - -Download - - Available for download from [4]chiark.greenend.org.uk are: - * The [5]current release as a gzipped tarfile. - * [6]adns.h API header file with comments, and [7]usage message for - adnshost (currently there is no manual, sorry). - * All versions released so far are also available via [8]anonymous - FTP and [9]HTTP. - - You can also access the project CVS repositories: - * A mirror of the source code repository is available via rsync from - rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns (use FTP - first to find your way around), or via [10]cvsweb. - * This web page is maintained in [11]Savannah, where you can browse - the [12]webpage CVS. - - adns is also available from the [13]GNU Project FTP servers and their - [14]mirrors. - -Technical note - - adns requires a real nameserver like [15]BIND or [16]Dents running on - the same system or a nearby one, which must be willing to provide - `recursive service'. I.e., adns is a `stub resolver'. All properly - configured UN*X and GNU systems will already have such nameserver(s); - they are usually listed in /etc/resolv.conf. - + +Documentation + + * [5]adns.h API header file with documentation comments + * [6]usage message for adnshost + +Download and source code + + * The [7]current release as a gzipped tarfile. + * [8]Previous versions. + * [9]master git (version control) repository browser. + + adns is also available from the [10]GNU Project FTP servers and their + [11]mirrors. + +Installation note + + adns requires a real nameserver like [12]BIND running on the same + system or a nearby one, which must be willing to provide `recursive + service'. I.e., adns is a `stub resolver'. + + adns requires that your real nameserver is on the same machine, or + connected via a secure network, so that an attacker cannot fake the + replies to adns's queries. + References and related projects - * [17]Python bindings by Andy Dustman. - * [18]Haskell bindings by Peter Simons. - * [19]liboop event loop library (by Dan Egnor) has a built-in - binding for adns. - * [20]port to MS Visual Studio 6 C++ by Jarle Aase. - + * [13]Python bindings by Andy Dustman. + * [14]liboop event loop library has a built-in binding for adns. + * [15]port to MS Visual Studio 6 C++ by Jarle Aase. + Copyright and licensing - adns is Copyright 1997-2000,2003,2006 Ian Jackson, Copyright - 1999-2000,2003,2006 Tony Finch, and Copyright (C) 1991 Massachusetts - Institute of Technology. - + adns is Copyright 1997-2000,2003,2006,2014 Ian Jackson, Copyright 2014 + Mark Wooding, Copyright 1999-2000,2003,2006 Tony Finch, and Copyright + (C) 1991 Massachusetts Institute of Technology. + adns is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free - Software Foundation; either version 2 of the License, or (at your + Software Foundation; either version 3 of the License, or (at your option) any later version. - + This program and documentation is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty - of merchantability or fitness for a particular purpose. See the - [21]GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with adns, or one should be available above; if not, write to - the [22]Free Software Foundation, 59 Temple Place - Suite 330, Boston, - MA 02111-1307, USA, or email adns-maint@chiark.greenend.org.uk. - _________________________________________________________________ - - [23]Ian Jackson / [24]adns-maint@chiark.greenend.org.uk; more [25]free - software by me. - - [26]GNU home page; [27]chiark home page; [28]site or mirror home page - - This web page is Copyright (C)1996-2005 Ian Jackson. See the - [29]Copyright/acknowledgements. - - Use any browser - [30]Campaign for a non-browser-specific WWW + of merchantability or fitness for a particular purpose. See the [16]GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License along + with adns, or one should be available above; if not, write to the + [17]Free Software Foundation or email ijackson@chiark.greenend.org.uk. + __________________________________________________________________ + + Ian Jackson / ijackson@chiark.greenend.org.uk. + + [18]GNU home page; [19]chiark home page; [20]site or mirror home page + + This web page is Copyright (C)1996-2005,2014 Ian Jackson. See the + [21]Copyright/acknowledgements. References 1. http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt 2. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt - 3. http://www.chiark.greenend.org.uk/mailman/listinfo - 4. http://www.chiark.greenend.org.uk/~ian/adns/ - 5. http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz - 6. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt - 7. http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt - 8. ftp://ftp.chiark.greenend.org.uk/users/ian/adns/ - 9. http://www.chiark.greenend.org.uk/~ian/adns/ftp/ - 10. http://www.chiark.greenend.org.uk/ucgi/~ijackson/cvsweb/adns/ - 11. http://savannah.gnu.org/ - 12. http://savannah.gnu.org/cgi-bin/viewcvs/software/adns/?cvsroot=www.gnu.org - 13. http://www.gnu.org/ - 14. http://www.gnu.org/order/ftp.html - 15. http://www.isc.org/view.cgi?/products/BIND/index.phtml - 16. http://www.dents.org/ - 17. http://dustman.net/andy/python/adns-python - 18. http://cryp.to/hsdns/ - 19. http://liboop.ofb.net/ref - 20. http://adns.jgaa.com/ - 21. http://www.chiark.greenend.org.uk/~ian/COPYING.txt - 22. http://www.fsf.org/ - 23. http://www.chiark.greenend.org.uk/ - 24. mailto:adns-maint@chiark.greenend.org.uk - 25. http://www.chiark.greenend.org.uk/~ian/software/ - 26. http://www.gnu.org/ - 27. http://www.chiark.greenend.org.uk/ - 28. file://localhost/ - 29. http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html - 30. http://www.anybrowser.org/campaign/ + 3. http://debbugs.gnu.org/ + 4. http://www.chiark.greenend.org.uk/mailman/listinfo + 5. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt + 6. http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt + 7. http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz + 8. http://www.chiark.greenend.org.uk/~ian/adns/ftp/ + 9. http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/adns.git/ + 10. http://www.gnu.org/ + 11. http://www.gnu.org/order/ftp.html + 12. http://www.isc.org/view.cgi?/products/BIND/index.phtml + 13. http://code.google.com/p/adns-python + 14. http://www.lysator.liu.se/liboop/ + 15. http://adns.jgaa.com/ + 16. http://www.chiark.greenend.org.uk/~ian/COPYING.txt + 17. http://www.fsf.org/ + 18. http://www.gnu.org/ + 19. http://www.chiark.greenend.org.uk/ + 20. file://localhost/ + 21. http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html diff --git a/README.html b/README.html index 86b4265..1eeee0b 100644 --- a/README.html +++ b/README.html @@ -37,10 +37,12 @@ to translate names to addresses, look up MX records, etc. queries can be handled simultaneously.
  • Responses are decoded automatically into a natural representation -for a C program - there is no need to deal with DNS packet formats. +for a C program - there is no need to deal with DNS packet and RRDATA +formats.
  • Sanity checking (eg, name syntax checking, reverse/forward -correspondence, CNAME pointing to CNAME) is performed automatically. +correspondence, CNAME pointing to CNAME) is performed automatically +by default.
  • Time-to-live, CNAME and other similar information is returned in an easy-to-use form, without getting in the way. @@ -52,8 +54,8 @@ can have several instances of the resolver.
  • Errors are reported to the application in a way that distinguishes the various causes of failure properly. -
  • Understands conventional resolv.conf, but this can overridden by -environment variables. +
  • adns understands conventional resolv.conf, but this can overridden +by environment variables.
  • Flexibility. For example, the application can tell adns to: ignore environment variables (for setuid programs), disable hostname @@ -91,26 +93,6 @@ usage message for a summary of its capabilities. -

    Forthcoming:

    - -I hope that future versions may also have the following features: - -
      - -
    • The library should be useable by threads in a multithreaded -program in a natural way. It should multiplex many threads' queries -through a single query socket. - -
    • IPv6 support. - -
    • Some kind of awareness of DNSSEC. - -
    • Possibly some very limited caching behaviour. - -
    • There was, at one point, a draft native Perl interface from Tony Finch. - -
    -

    Documentation

    I'm afraid there is no manual yet. However, competent C programmers @@ -126,19 +108,26 @@ your project, and what you think of it.

    -If you are subscribed to adns-discuss please send -feedback, including bug reports, there; otherwise send mail to -adns-bugreports@chiark.greenend.org.uk. If you'd prefer -that your message wasn't forwarded to the adns-bugreports -list, send it to adns-maint@chiark.greenend.org.uk. +Bug reports should be reported to the +GNU Debbugs. Send an email +to submit@debbugs.gnu.org and at the top of your email, +in a paragraph of its own, write the single line +

    +Package: adns
+
    +Your bug report will be published via to the adns-discuss list. + +

    + +Feedback and discussion takes place on the adns-discuss +list. You can mail me privately +at ijackson@chiark.greenend.org.uk.

    Mailinglists

    I have set up mailinglists adns-announce and adns-discuss. The announcements list is moderated and will contain only announcements of important bugs, new versions, etc. -The bug reports address mentioned above is also a mailing list; feel -free to subscribe to it.

    @@ -149,74 +138,67 @@ containing the word `subscribe' to adns-announce-REQUEST@chiark.greenend.org.uk or adns-discuss-REQUEST@chiark.greenend.org.uk. -

    Download

    +

    Documentation

    -Available for download from -chiark.greenend.org.uk -are: -You can also access the project CVS repositories: +

    Download and source code

    + adns is also available from the GNU Project FTP servers and their mirrors. -

    Technical note

    +

    Installation note

    adns requires a real nameserver like BIND -or -Dents running on +running on the same system or a nearby one, which must be willing to provide -`recursive service'. I.e., adns is a `stub resolver'. All properly -configured UN*X and GNU systems will already have such nameserver(s); -they are usually listed in /etc/resolv.conf. +`recursive service'. I.e., adns is a `stub resolver'. + +

    +adns requires that your real nameserver is on the same machine, or +connected via a secure network, so that an attacker cannot fake the +replies to adns's queries.

    References and related projects

    Copyright and licensing

    -adns is Copyright 1997-2000,2003,2006 Ian Jackson, -Copyright 1999-2000,2003,2006 Tony Finch, and Copyright (C) 1991 -Massachusetts Institute of Technology. +adns is Copyright 1997-2000,2003,2006,2014 Ian Jackson, +Copyright 2014 Mark Wooding, Copyright 1999-2000,2003,2006 Tony Finch, +and Copyright (C) 1991 Massachusetts Institute of Technology.

    adns is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or (at +the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

    @@ -232,18 +214,13 @@ General Public License for more details. You should have received a copy of the GNU General Public License along with adns, or one should be available above; if not, -write to the -Free Software Foundation, -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, -or email adns-maint@chiark.greenend.org.uk. +write to the Free Software Foundation +or email ijackson@chiark.greenend.org.uk.

    -Ian Jackson / -adns-maint@chiark.greenend.org.uk; -more free -software by me. +Ian Jackson / ijackson@chiark.greenend.org.uk.

    GNU home page; @@ -251,12 +228,8 @@ software by me. site or mirror home page

    -This web page is Copyright (C)1996-2005 Ian Jackson. See the +This web page is Copyright (C)1996-2005,2014 Ian Jackson. See the Copyright/acknowledgements. -

    - -Use any browser - -Campaign for a non-browser-specific WWW