hsdns-1.4: Asynchronous DNS Resolver





This module provides bindings to GNU ADNS, a domain name resolver library written in C. ADNS is available from http://www.gnu.org/software/adns/.

You will most likely not need this module directly: ADNS provides a simpler API for the Haskell world; this module contains mostly marshaling code.


Marshaled ADNS Data Types

data InitFlag Source



do not look at environment


never print output to stderr (Debug overrides)


do not warn to stderr about duff nameservers etc


enable all output to stderr plus Debug msgs


include process id in diagnostic output


do not make syscalls at every opportunity


allow adnsSynch to return eINTR


application has SIGPIPE set to SIG_IGN, do not protect


do consistency checks on entry/exit to adns functions


do consistency checks very frequently (slow!)

data QueryFlag Source



use the searchlist


use a virtual circuit (TCP connection)


fill in the owner field in the answer


allow special chars in query domain


allow special chars in CNAME we go via (default)


allow special chars in things supposed to be hostnames


refuse if quote-req chars in CNAME we go via


allow refs to CNAMEs - without, get _s_cname


don't follow CNAMEs, instead give _s_cname

data RRType Source

The record types we support.


RRType Int 

newtype Status Source

The status codes recognized by ADNS vary in different versions of the library. So instead of providing an Enum, the Status type contains the numeric value as returned by ADNS itself. For common status codes, helper functions like sOK or sNXDOMAIN are provided. The functions adnsErrTypeAbbrev, adnsErrAbbrev, and adnsStrerror can also be used to map these codes into human readable strings.


StatusCode Int 


sINCONSISTENT :: StatusSource

Original definition:

    typedef struct {
      int len;
      union {
        struct sockaddr sa;
        struct sockaddr_in inet;
      } addr;
    } adns_rr_addr;

Note: Anything but sockaddr_in will cause peek to call fail, when marshaling this structure. poke is not defined.

newtype RRAddr Source


RRAddr HostAddress 

data RRHostAddr Source

Original definition:

    typedef struct {
      char *host;
      adns_status astatus;
      int naddrs; /* temp fail => -1, perm fail => 0, s_ok => >0
      adns_rr_addr *addrs;
    } adns_rr_hostaddr;

The naddrs field is not available in RRHostAddr because I couldn't see how that information wouldn't be available in the astatus field too. If I missed anything, please let me know.

Note: The data type should probably contain HostAddress rather than RRAddr. I'm using the former only because it has nicer output with show. poke is not defined.

data RRIntHostAddr Source

Original definition:

    typedef struct {
      int i;
      adns_rr_hostaddr ha;
    } adns_rr_inthostaddr;

data RRByteblock Source

Original definition:

    typedef struct {
      int len;
      unsigned char *data;
    } adns_rr_byteblock;


RRByteblock Int (Ptr CChar) 

data Answer Source




status :: Status

Status code for this query.

cname :: Maybe String

Always Nothing for CNAME queries

owner :: Maybe String

Only set if Owner was requested for query.

expires :: CTime

Only defined if status is sOK, sNXDOMAIN, or sNODATA.

rrs :: [Response]

The list will be empty if an error occured.

peekResp :: RRType -> Ptr b -> Int -> Int -> IO [Response]Source

This function parses the Response union found in Answer. It cannot be defined via Storable because it needs to know the type of the record to expect. This is, by the way, the function to look at, if you want to add support for additional RRType records.

peekFQDNAndAdvance :: Ptr a -> Int -> IO (String, Ptr a)Source

This function parses a FQDN in uncompressed wire format and advances the pointer to the next byte after the parsed name.

ADNS Library Functions

adnsInit :: [InitFlag] -> (AdnsState -> IO a) -> IO aSource

Run the given IO computation with an initialized resolver. As of now, the diagnose stream is always set to System.IO.stderr. Initialize the library with NoErrPrint if you don't wont to see any error output. All resources are freed when adnsInit returns.

adnsInitCfg :: [InitFlag] -> String -> (AdnsState -> IO a) -> IO aSource

Similar to adnsInit, but reads the resolver configuration from a string rather than from /etc/resolv.conf. Supported are the usual commands: nameserver, search, domain, sortlist, and options.

Additionally, these non-standard commands may be used:

  • clearnameservers: Clears the list of nameservers.
  • include filename: The specified file will be read.

adnsSynch :: AdnsState -> String -> RRType -> [QueryFlag] -> IO AnswerSource

Perform a synchronous query for a record. In case of an I/O error, an System.IO.Error.IOException is thrown. If the query fails for other reasons, the Status code in the Answer will signify that.

adnsSubmit :: AdnsState -> String -> RRType -> [QueryFlag] -> IO QuerySource

Submit an asynchronous query. The returned Query can be tested for completion with adnsCheck.

adnsCheck :: AdnsState -> Query -> IO (Maybe Answer)Source

Check the status of an asynchronous query. If the query is complete, the Answer will be returned. The Query becomes invalid after that.

adnsWait :: AdnsState -> IO (Maybe (Query, Answer))Source

Wait for a response to arrive. The returned Query is invalid and must not be passed to ADNS again. If Nothing is returned, the resolver is empty.

adnsCancel :: Query -> IO ()Source

Cancel an open Query.

adns_wait :: AdnsState -> Ptr Query -> Ptr (Ptr Answer) -> Ptr (Ptr a) -> IO CIntSource

Wait for the next Query to become available.

adnsQueries :: AdnsState -> IO [Query]Source

Return the list of all currently open queries.

adnsStrerror :: Status -> IO StringSource

Map a Status code to a human-readable error description. For example:

    *ADNS> adnsStrerror sNXDOMAIN >>= print
    "No such domain"

Use this function with great care: It will crash the process when called with a status code that ADNS doesn't know about. So use it only to print values you got from the resolver!

adnsErrAbbrev :: Status -> IO StringSource

Map a Status code to a short error name. Don't use this function to print a status code unless you've obtained it from the resolver!

adnsErrTypeAbbrev :: Status -> IO StringSource

Map a Status code to a short description of the type of error. Don't use this function to print a status code unless you've obtained it from the resolver!

Unmarshaled Low-Level C Functions

Helper Functions

wrapAdns :: (Ptr (Ptr b) -> IO CInt) -> (Ptr (Ptr b) -> IO a) -> IO aSource

Internel helper function to handle result passing from ADNS via Ptr (Ptr a), and to generate human-readable IO exceptions in case of an error.

mkFlags :: Enum a => [a] -> CIntSource

Map a list of flags (Enum types) into a CInt suitable for adns calls.