NAME
        treso - Resolver

SYNOPSIS
        package require Tcl 8.6

        package require treso 0.2
        namespace import ::treso::*

        treso::resolve ?-option ...? what ?-option ...?
        treso::resolvers
        treso::running
        treso::cancel runId

DESCRIPTION
        This extension uses the system's resolver to resolve
        names to addresses or addresses to names. When resolving
        addresses to names, the first address found is returned
        unless one of the return options is given.
        A single return option returns the option's value.
        More than one return option or the -all return
        option will return a dict of option/value pairs.
        Lookups are performed in the inet domain by default.

RESOLVERS
        The resolvers command returns a list of available resolvers
        that may be passed as parameters to the -resolver option of
        the resolve command. At minimum, four resolvers are available:

                none        Returns a result based on the input and options.
                        Doesn't attempt to resolve anything.
                        Possibly useful for testing.
                        Nonblocking.

                simple        Simple resolver.
                        Returns result directly.
                        Most likely blocking.

                direct        Direct resolver.
                        Calls callback immediately, before the resolve command returns.
                        Callback is called with one extra argument: the requested return data.
                        Returns an empty string.
                        Most likely blocking.

                basync        Blocking async resolver.
                        Creates an event that should happen immediately
                        and calls the callback from the event handler.
                        Callback is called with one extra argument: the requested return data.
                        Returns an identifier.
                        Needs event loop.
                        Most likely blocking.

        The following resolvers may also be available:

                thread        Threaded resolver.
                        All potentially blocking operations happen in a thread.
                        Callback is called with one extra argument: the requested return data.
                        Returns an identifier.
                        Needs threads.
                        Needs event loop.
                        Nonblocking.

                async        Asynchronous resolver.
                        Callback is called with one extra argument: the requested return data.
                        Returns an identifier.
                        Needs event loop.
                        Nonblocking.


RESOLVERS COMMAND
        The resolvers command returns a list of available resolvers.


RESOLVE COMMAND
        The resolve command performs name resolution.

PARAMETERS
        what                Name or numeric address

RESOLVER OPTIONS
        -domain   domain        Domain, inet or inet6
        -resolver resolver        Resolver to use
        -answerto cmdprefix        Callback
        -to       to                Resolve to a name or addr, default name.

RETURN OPTIONS
        -name                Name
        -aliases        List of aliases
        -addresses        List of addresses
        -domain                Domain
        -resolver        Resolver
        -to                To
        -all                All of the above


RUNNING COMMAND
        The running command returns a list of running queries.

CANCEL COMMAND
        The cancel command cancels a running query.
        Returns an empty string.

PARAMETERS
        runId        Run id to cancel


EXAMPLES
        resolve localhost
        resolve -aliases localhost -domain inet -addresses
        resolve -domain -domain inet6 localhost
        resolve -aliases -resolver basync localhost -answerto list myproc someparm -name

COPYRIGHT
        Copyright (c) 2012 Stuart Cassoff