ADNS.Base

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 OpaqueState

type AdnsState = Ptr OpaqueState

data OpaqueQuery

type Query = Ptr OpaqueQuery

data InitFlag

Constructors

NoEnv

do not look at environment

NoErrPrint

never print output to stderr (Debug overrides)

NoServerWarn

do not warn to stderr about duff nameservers etc

Debug

enable all output to stderr plus Debug msgs

LogPid

include process id in diagnostic output

NoAutoSys

do not make syscalls at every opportunity

Eintr

allow adnsSynch to return eINTR

NoSigPipe

application has SIGPIPE set to SIG_IGN, do not protect

CheckC_EntEx

do consistency checks on entry/exit to adns functions

CheckC_Freq

do consistency checks very frequently (slow!)

Instances

Bounded InitFlag

Methods

minBound :: InitFlag

maxBound :: InitFlag

Enum InitFlag

Methods

succ :: InitFlag -> InitFlag

pred :: InitFlag -> InitFlag

toEnum :: Int -> InitFlag

fromEnum :: InitFlag -> Int

enumFrom :: InitFlag -> [InitFlag]

enumFromThen :: InitFlag -> InitFlag -> [InitFlag]

enumFromTo :: InitFlag -> InitFlag -> [InitFlag]

enumFromThenTo :: InitFlag -> InitFlag -> InitFlag -> [InitFlag]

Eq InitFlag

Methods

(==) :: InitFlag -> InitFlag -> Bool

(/=) :: InitFlag -> InitFlag -> Bool

Show InitFlag

Methods

showsPrec :: Int -> InitFlag -> ShowS

show :: InitFlag -> String

showList :: [InitFlag] -> ShowS

data QueryFlag

Constructors

Search

use the searchlist

UseVC

use a virtual circuit (TCP connection)

Owner

fill in the owner field in the answer

QuoteOk_Query

allow special chars in query domain

QuoteOk_CName

allow special chars in CNAME we go via (default)

QuoteOk_AnsHost

allow special chars in things supposed to be hostnames

QuoteFail_CName

refuse if quote-req chars in CNAME we go via

CName_Loose

allow refs to CNAMEs - without, get _s_cname

CName_Forbid

don't follow CNAMEs, instead give _s_cname

Instances

Bounded QueryFlag

Methods

minBound :: QueryFlag

maxBound :: QueryFlag

Enum QueryFlag

Methods

succ :: QueryFlag -> QueryFlag

pred :: QueryFlag -> QueryFlag

toEnum :: Int -> QueryFlag

fromEnum :: QueryFlag -> Int

enumFrom :: QueryFlag -> [QueryFlag]

enumFromThen :: QueryFlag -> QueryFlag -> [QueryFlag]

enumFromTo :: QueryFlag -> QueryFlag -> [QueryFlag]

enumFromThenTo :: QueryFlag -> QueryFlag -> QueryFlag -> [QueryFlag]

Eq QueryFlag

Methods

(==) :: QueryFlag -> QueryFlag -> Bool

(/=) :: QueryFlag -> QueryFlag -> Bool

Show QueryFlag

Methods

showsPrec :: Int -> QueryFlag -> ShowS

show :: QueryFlag -> String

showList :: [QueryFlag] -> ShowS

data RRType

The record types we support.

Constructors

A

CNAME

MX

NS

PTR

NSEC

SRV

RRType Int

Instances

Enum RRType

Methods

succ :: RRType -> RRType

pred :: RRType -> RRType

toEnum :: Int -> RRType

fromEnum :: RRType -> Int

enumFrom :: RRType -> [RRType]

enumFromThen :: RRType -> RRType -> [RRType]

enumFromTo :: RRType -> RRType -> [RRType]

enumFromThenTo :: RRType -> RRType -> RRType -> [RRType]

Eq RRType

Methods

(==) :: RRType -> RRType -> Bool

(/=) :: RRType -> RRType -> Bool

Read RRType

Methods

readsPrec :: Int -> ReadS RRType

readList :: ReadS [RRType]

readPrec :: ReadPrec RRType

readListPrec :: ReadPrec [RRType]

Show RRType

Methods

showsPrec :: Int -> RRType -> ShowS

show :: RRType -> String

showList :: [RRType] -> ShowS

Storable RRType

Methods

sizeOf :: RRType -> Int

alignment :: RRType -> Int

peekElemOff :: Ptr RRType -> Int -> IO RRType

pokeElemOff :: Ptr RRType -> Int -> RRType -> IO ()

peekByteOff :: Ptr b -> Int -> IO RRType

pokeByteOff :: Ptr b -> Int -> RRType -> IO ()

peek :: Ptr RRType -> IO RRType

poke :: Ptr RRType -> RRType -> IO ()

newtype Status

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.

Constructors

StatusCode Int

Instances

Eq Status

Methods

(==) :: Status -> Status -> Bool

(/=) :: Status -> Status -> Bool

Show Status

Methods

showsPrec :: Int -> Status -> ShowS

show :: Status -> String

showList :: [Status] -> ShowS

sOK :: Status

sNOMEMORY :: Status

sUNKNOWNRRTYPE :: Status

sSYSTEMFAIL :: Status

sMAX_LOCALFAIL :: Status

sTIMEOUT :: Status

sALLSERVFAIL :: Status

sNORECURSE :: Status

sINVALIDRESPONSE :: Status

sUNKNOWNFORMAT :: Status

sMAX_REMOTEFAIL :: Status

sRCODESERVFAIL :: Status

sRCODEFORMATERROR :: Status

sRCODENOTIMPLEMENTED :: Status

sRCODEREFUSED :: Status

sRCODEUNKNOWN :: Status

sMAX_TEMPFAIL :: Status

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.

sINCONSISTENT :: Status

sPROHIBITEDCNAME :: Status

sANSWERDOMAININVALID :: Status

sANSWERDOMAINTOOLONG :: Status

sINVALIDDATA :: Status

sMAX_MISCONFIG :: Status

newtype RRAddr

Constructors

RRAddr HostAddress

Instances

Eq RRAddr

Methods

(==) :: RRAddr -> RRAddr -> Bool

(/=) :: RRAddr -> RRAddr -> Bool

Show RRAddr

Methods

showsPrec :: Int -> RRAddr -> ShowS

show :: RRAddr -> String

showList :: [RRAddr] -> ShowS

Storable RRAddr

Methods

sizeOf :: RRAddr -> Int

alignment :: RRAddr -> Int

peekElemOff :: Ptr RRAddr -> Int -> IO RRAddr

pokeElemOff :: Ptr RRAddr -> Int -> RRAddr -> IO ()

peekByteOff :: Ptr b -> Int -> IO RRAddr

pokeByteOff :: Ptr b -> Int -> RRAddr -> IO ()

peek :: Ptr RRAddr -> IO RRAddr

poke :: Ptr RRAddr -> RRAddr -> IO ()

sQUERYDOMAINWRONG :: Status

sQUERYDOMAININVALID :: Status

sQUERYDOMAINTOOLONG :: Status

sMAX_MISQUERY :: Status

sNXDOMAIN :: Status

sNODATA :: Status

sMAX_PERMFAIL :: Status

data RRHostAddr

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.

Constructors

RRHostAddr HostName Status [RRAddr]

Instances

Show RRHostAddr

Methods

showsPrec :: Int -> RRHostAddr -> ShowS

show :: RRHostAddr -> String

showList :: [RRHostAddr] -> ShowS

Storable RRHostAddr

Methods

sizeOf :: RRHostAddr -> Int

alignment :: RRHostAddr -> Int

peekElemOff :: Ptr RRHostAddr -> Int -> IO RRHostAddr

pokeElemOff :: Ptr RRHostAddr -> Int -> RRHostAddr -> IO ()

peekByteOff :: Ptr b -> Int -> IO RRHostAddr

pokeByteOff :: Ptr b -> Int -> RRHostAddr -> IO ()

peek :: Ptr RRHostAddr -> IO RRHostAddr

poke :: Ptr RRHostAddr -> RRHostAddr -> IO ()

data RRIntHostAddr

Original definition:

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

Constructors

RRIntHostAddr Int RRHostAddr

Instances

Show RRIntHostAddr

Methods

showsPrec :: Int -> RRIntHostAddr -> ShowS

show :: RRIntHostAddr -> String

showList :: [RRIntHostAddr] -> ShowS

Storable RRIntHostAddr

Methods

sizeOf :: RRIntHostAddr -> Int

alignment :: RRIntHostAddr -> Int

peekElemOff :: Ptr RRIntHostAddr -> Int -> IO RRIntHostAddr

pokeElemOff :: Ptr RRIntHostAddr -> Int -> RRIntHostAddr -> IO ()

peekByteOff :: Ptr b -> Int -> IO RRIntHostAddr

pokeByteOff :: Ptr b -> Int -> RRIntHostAddr -> IO ()

peek :: Ptr RRIntHostAddr -> IO RRIntHostAddr

poke :: Ptr RRIntHostAddr -> RRIntHostAddr -> IO ()

data RRByteblock

Original definition:

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

Constructors

RRByteblock Int (Ptr CChar)

Instances

Storable RRByteblock

Methods

sizeOf :: RRByteblock -> Int

alignment :: RRByteblock -> Int

peekElemOff :: Ptr RRByteblock -> Int -> IO RRByteblock

pokeElemOff :: Ptr RRByteblock -> Int -> RRByteblock -> IO ()

peekByteOff :: Ptr b -> Int -> IO RRByteblock

pokeByteOff :: Ptr b -> Int -> RRByteblock -> IO ()

peek :: Ptr RRByteblock -> IO RRByteblock

poke :: Ptr RRByteblock -> RRByteblock -> IO ()

data RRSrvRaw

Original definition:

   typedef struct {
     int priority, weight, port;
     char *host;
   } adns_rr_srvraw;

Constructors

RRSrvRaw Int Int Int (Ptr CChar)

Instances

Storable RRSrvRaw

Methods

sizeOf :: RRSrvRaw -> Int

alignment :: RRSrvRaw -> Int

peekElemOff :: Ptr RRSrvRaw -> Int -> IO RRSrvRaw

pokeElemOff :: Ptr RRSrvRaw -> Int -> RRSrvRaw -> IO ()

peekByteOff :: Ptr b -> Int -> IO RRSrvRaw

pokeByteOff :: Ptr b -> Int -> RRSrvRaw -> IO ()

peek :: Ptr RRSrvRaw -> IO RRSrvRaw

poke :: Ptr RRSrvRaw -> RRSrvRaw -> IO ()

data Answer

Constructors

Answer

Fields

• 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.

Instances

Show Answer

Methods

showsPrec :: Int -> Answer -> ShowS

show :: Answer -> String

showList :: [Answer] -> ShowS

Storable Answer

Methods

sizeOf :: Answer -> Int

alignment :: Answer -> Int

peekElemOff :: Ptr Answer -> Int -> IO Answer

pokeElemOff :: Ptr Answer -> Int -> Answer -> IO ()

peekByteOff :: Ptr b -> Int -> IO Answer

pokeByteOff :: Ptr b -> Int -> Answer -> IO ()

peek :: Ptr Answer -> IO Answer

poke :: Ptr Answer -> Answer -> IO ()

data Response

Constructors

RRA RRAddr

RRCNAME String

RRMX Int RRHostAddr

RRNS RRHostAddr

RRPTR String

RRNSEC String

RRUNKNOWN String

RRSRV Int Int Int String

Instances

Show Response

Methods

showsPrec :: Int -> Response -> ShowS

show :: Response -> String

showList :: [Response] -> ShowS

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

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)

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 a

Run the given IO computation with an initialized resolver. As of now, the diagnose stream is always set to 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 a

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 Answer

Perform a synchronous query for a record. In case of an I/O error, an 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 Query

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

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

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))

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 ()

Cancel an open Query.

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

Wait for the next Query to become available.

adnsQueries :: AdnsState -> IO [Query]

Return the list of all currently open queries.

adnsStrerror :: Status -> IO String

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 String

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 String

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

adns_init :: Ptr AdnsState -> CInt -> Ptr CFile -> IO CInt

adns_init_strcfg :: Ptr AdnsState -> CInt -> Ptr CFile -> CString -> IO CInt

adns_finish :: AdnsState -> IO ()

adns_submit :: AdnsState -> CString -> CInt -> CInt -> Ptr a -> Ptr Query -> IO CInt

adns_check :: AdnsState -> Ptr Query -> Ptr (Ptr Answer) -> Ptr (Ptr a) -> IO CInt

adns_synchronous :: AdnsState -> CString -> CInt -> CInt -> Ptr (Ptr Answer) -> IO CInt

adns_forallqueries_begin :: AdnsState -> IO ()

adns_forallqueries_next :: AdnsState -> Ptr (Ptr a) -> IO Query

adns_strerror :: CInt -> IO CString

adns_errabbrev :: CInt -> IO CString

adns_errtypeabbrev :: CInt -> IO CString

Helper Functions

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

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] -> CInt

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