Use glossary for list

source/manpages/libunbound.rst

@@ -172,190 +172,192 @@ The functions are discussed in turn below.
 Functions
 ---------
 
-ub_ctx_create
-    Create a new context, initialised with defaults. The information from
-    :file:`/etc/resolv.conf` and :file:`/etc/hosts` is not utilised by default.
-    Use **ub_ctx_resolvconf** and **ub_ctx_hosts** to read them. Before you call
-    this, use the openssl functions **CRYPTO_set_id_callback** and
-    **CRYPTO_set_locking_callback** to set up asynchronous operation if you use
-    lib openssl (the application calls these functions once for initialisation).
-    Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback** function.
-
-ub_ctx_delete
-    Delete validation context and free associated resources. Outstanding async
-    queries are killed and callbacks are not called for them.
-
-ub_ctx_set_option
-    A power-user interface that lets you specify one of the options from the
-    config file format, see :manpage:`unbound.conf(5)`. Not all options are
-    relevant. For some specific options, such as adding trust anchors, special
-    routines exist. Pass the option name with the trailing ``':'``.
-
-ub_ctx_get_option
-    A power-user interface that gets an option value. Some options cannot be
-    gotten, and others return a newline separated list. Pass the option name
-    without trailing ``':'``. The returned value must be free(2)d by the caller.
-
-ub_ctx_config
-    A power-user interface that lets you specify an unbound config file, see
-    :manpage:`unbound.conf(5)`, which is read for configuration. Not all options
-    are relevant. For some specific options, such as adding trust anchors,
-    special routines exist. This function is thread-safe only if a single
-    instance of **ub_ctx** exists in the application. If several instances
-    exist the application has to ensure that **ub_ctx_config** is not called in
-    parallel by the different instances.
-
-ub_ctx_set_fwd
-    Set machine to forward DNS queries to, the caching resolver to use. IP4 or
-    IP6 address. Forwards all DNS requests to that machine, which is expected to
-    run a recursive resolver. If the proxy is not DNSSEC capable, validation may
-    fail. Can be called several times, in that case the addresses are used as
-    backup servers. At this time it is only possible to set configuration before
-    the first resolve is done.
-
-ub_ctx_set_stub
-    Set a stub zone, authoritative dns servers to use for a particular zone. IP4
-    or IP6 address. If the address is NULL the stub entry is removed. Set
-    isprime true if you configure root hints with it. Otherwise similar to the
-    stub zone item from unbound's config file. Can be called several times, for
-    different zones, or to add multiple addresses for a particular zone. At this
-    time it is only possible to set configuration before the first resolve is
-    done.
-
-ub_ctx_set_tls
-    Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**. At this
-    time it is only possible to set configuration before the first resolve is
-    done.
-
-ub_ctx_resolvconf
-    By default the root servers are queried and full resolver mode is used, but
-    you can use this call to read the list of nameservers to use from the
-    filename given. Usually :file:`"/etc/resolv.conf"`. Uses those nameservers
-    as caching proxies. If they do not support DNSSEC, validation may fail. Only
-    nameservers are picked up, the searchdomain, ndots and other settings from
-    *resolv.conf(5)* are ignored. If fname NULL is passed,
-    :file:`"/etc/resolv.conf"` is used (if on Windows, the system-wide
-    configured nameserver is picked instead). At this time it is only possible
-    to set configuration before the first resolve is done.
-
-ub_ctx_hosts
-    Read list of hosts from the filename given. Usually :file:`"/etc/hosts"`.
-    When queried for, these addresses are not marked DNSSEC secure. If fname
-    NULL is passed, :file:`"/etc/hosts"` is used (if on Windows,
-    :file:`etc/hosts` from WINDIR is picked instead). At this time it is only
-    possible to set configuration before the first resolve is done.
-
-ub_ctx_add_ta
-    Add a trust anchor to the given context. At this time it is only possible to
-    add trusted keys before the first resolve is done. The format is a string,
-    similar to the zone-file format, **[domainname]** **[type]** **[rdata
-    contents]**. Both DS and DNSKEY records are accepted.
-
-ub_ctx_add_ta_autr
-    Add filename with automatically tracked trust anchor to the given context.
-    Pass name of a file with the managed trust anchor. You can create this file
-    with :manpage:`unbound-anchor(8)` for the root anchor. You can also create
-    it with an initial file with one line with a DNSKEY or DS record. If the
-    file is writable, it is updated when the trust anchor changes. At this time
-    it is only possible to add trusted keys before the first resolve is done.
-
-ub_ctx_add_ta_file
-    Add trust anchors to the given context. Pass name of a file with DS and
-    DNSKEY records in zone file format. At this time it is only possible to add
-    trusted keys before the first resolve is done.
-
-ub_ctx_trustedkeys
-    Add trust anchors to the given context. Pass the name of a bind-style config
-    file with ``trusted-keys{}``. At this time it is only possible to add
-    trusted keys before the first resolve is done.
-
-ub_ctx_debugout
-    Set debug and error log output to the given stream. Pass NULL to disable
-    output. Default is stderr. File-names or using syslog can be enabled using
-    config options, this routine is for using your own stream.
-
-ub_ctx_debuglevel
-    Set debug verbosity for the context. Output is directed to stderr. Higher
-    debug level gives more output.
-
-ub_ctx_async
-    Set a context behaviour for asynchronous action. if set to true, enables
-    threading and a call to **ub_resolve_async** creates a thread to handle work
-    in the background. If false, a process is forked to handle work in the
-    background. Changes to this setting after **ub_resolve_async** calls have
-    been made have no effect (delete and re-create the context to change).
-
-ub_poll
-    Poll a context to see if it has any new results. Do not poll in a loop,
-    instead extract the **fd** below to poll for readiness, and then check, or
-    wait using the wait routine. Returns 0 if nothing to read, or nonzero if a
-    result is available. If nonzero, call **ub_process** to do callbacks.
-
-ub_wait
-    Wait for a context to finish with results. Calls **ub_process** after the
-    wait for you. After the wait, there are no more outstanding asynchronous
-    queries.
-
-ub_fd 
-    Get file descriptor. Wait for it to become readable, at this point answers
-    are returned from the asynchronous validating resolver. Then call the
-    **ub_process** to continue processing.
-
-ub_process
-    Call this routine to continue processing results from the validating
-    resolver (when the **fd** becomes readable). Will perform necessary
-    callbacks.
-
-ub_resolve
-    Perform resolution and validation of the target name. The name is a domain
-    name in a zero terminated text string. The rrtype and rrclass are DNS type
-    and class codes. The result structure is newly allocated with the resulting
-    data.
-
-ub_resolve_async
-    Perform asynchronous resolution and validation of the target name. Arguments
-    mean the same as for **ub_resolve** except no data is returned immediately,
-    instead a callback is called later. The callback receives a copy of the
-    mydata pointer, that you can use to pass information to the callback. The
-    callback type is a function pointer to a function declared as
-
-    .. code-block:: c
-
-        void my_callback_function(void* my_arg, int err,
-                          struct ub_result* result);
-
-    The **async_id** is returned so you can (at your option) decide to track it
-    and cancel the request if needed. If you pass a NULL pointer the
-    **async_id** is not returned.
-
-ub_cancel
-    Cancel an async query in progress. This may return an error if the query
-    does not exist, or the query is already being delivered, in that case you
-    may still get a callback for the query.
-
-ub_resolve_free
-    Free struct **ub_result** contents after use.
-
-ub_strerror
-    Convert error value from one of the unbound library functions to a human
-    readable string.
-
-ub_ctx_print_local_zones
-    Debug printout the local authority information to debug output.
-
-ub_ctx_zone_add
-    Add new zone to local authority info, like local-zone
-    :manpage:`unbound.conf(5)` statement.
-
-ub_ctx_zone_remove
-    Delete zone from local authority info.
-
-ub_ctx_data_add
-    Add resource record data to local authority info, like local-data
-    :manpage:`unbound.conf(5)` statement.
-
-ub_ctx_data_remove
-    Delete local authority data from the name given.
+.. Glossary::
+
+    ub_ctx_create
+        Create a new context, initialised with defaults. The information from
+        :file:`/etc/resolv.conf` and :file:`/etc/hosts` is not utilised by default.
+        Use **ub_ctx_resolvconf** and **ub_ctx_hosts** to read them. Before you call
+        this, use the openssl functions **CRYPTO_set_id_callback** and
+        **CRYPTO_set_locking_callback** to set up asynchronous operation if you use
+        lib openssl (the application calls these functions once for initialisation).
+        Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback** function.
+
+    ub_ctx_delete
+        Delete validation context and free associated resources. Outstanding async
+        queries are killed and callbacks are not called for them.
+
+    ub_ctx_set_option
+        A power-user interface that lets you specify one of the options from the
+        config file format, see :manpage:`unbound.conf(5)`. Not all options are
+        relevant. For some specific options, such as adding trust anchors, special
+        routines exist. Pass the option name with the trailing ``':'``.
+
+    ub_ctx_get_option
+        A power-user interface that gets an option value. Some options cannot be
+        gotten, and others return a newline separated list. Pass the option name
+        without trailing ``':'``. The returned value must be free(2)d by the caller.
+
+    ub_ctx_config
+        A power-user interface that lets you specify an unbound config file, see
+        :manpage:`unbound.conf(5)`, which is read for configuration. Not all options
+        are relevant. For some specific options, such as adding trust anchors,
+        special routines exist. This function is thread-safe only if a single
+        instance of **ub_ctx** exists in the application. If several instances
+        exist the application has to ensure that **ub_ctx_config** is not called in
+        parallel by the different instances.
+
+    ub_ctx_set_fwd
+        Set machine to forward DNS queries to, the caching resolver to use. IP4 or
+        IP6 address. Forwards all DNS requests to that machine, which is expected to
+        run a recursive resolver. If the proxy is not DNSSEC capable, validation may
+        fail. Can be called several times, in that case the addresses are used as
+        backup servers. At this time it is only possible to set configuration before
+        the first resolve is done.
+
+    ub_ctx_set_stub
+        Set a stub zone, authoritative dns servers to use for a particular zone. IP4
+        or IP6 address. If the address is NULL the stub entry is removed. Set
+        isprime true if you configure root hints with it. Otherwise similar to the
+        stub zone item from unbound's config file. Can be called several times, for
+        different zones, or to add multiple addresses for a particular zone. At this
+        time it is only possible to set configuration before the first resolve is
+        done.
+
+    ub_ctx_set_tls
+        Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**. At this
+        time it is only possible to set configuration before the first resolve is
+        done.
+
+    ub_ctx_resolvconf
+        By default the root servers are queried and full resolver mode is used, but
+        you can use this call to read the list of nameservers to use from the
+        filename given. Usually :file:`"/etc/resolv.conf"`. Uses those nameservers
+        as caching proxies. If they do not support DNSSEC, validation may fail. Only
+        nameservers are picked up, the searchdomain, ndots and other settings from
+        *resolv.conf(5)* are ignored. If fname NULL is passed,
+        :file:`"/etc/resolv.conf"` is used (if on Windows, the system-wide
+        configured nameserver is picked instead). At this time it is only possible
+        to set configuration before the first resolve is done.
+
+    ub_ctx_hosts
+        Read list of hosts from the filename given. Usually :file:`"/etc/hosts"`.
+        When queried for, these addresses are not marked DNSSEC secure. If fname
+        NULL is passed, :file:`"/etc/hosts"` is used (if on Windows,
+        :file:`etc/hosts` from WINDIR is picked instead). At this time it is only
+        possible to set configuration before the first resolve is done.
+
+    ub_ctx_add_ta
+        Add a trust anchor to the given context. At this time it is only possible to
+        add trusted keys before the first resolve is done. The format is a string,
+        similar to the zone-file format, **[domainname]** **[type]** **[rdata
+        contents]**. Both DS and DNSKEY records are accepted.
+
+    ub_ctx_add_ta_autr
+        Add filename with automatically tracked trust anchor to the given context.
+        Pass name of a file with the managed trust anchor. You can create this file
+        with :manpage:`unbound-anchor(8)` for the root anchor. You can also create
+        it with an initial file with one line with a DNSKEY or DS record. If the
+        file is writable, it is updated when the trust anchor changes. At this time
+        it is only possible to add trusted keys before the first resolve is done.
+
+    ub_ctx_add_ta_file
+        Add trust anchors to the given context. Pass name of a file with DS and
+        DNSKEY records in zone file format. At this time it is only possible to add
+        trusted keys before the first resolve is done.
+
+    ub_ctx_trustedkeys
+        Add trust anchors to the given context. Pass the name of a bind-style config
+        file with ``trusted-keys{}``. At this time it is only possible to add
+        trusted keys before the first resolve is done.
+
+    ub_ctx_debugout
+        Set debug and error log output to the given stream. Pass NULL to disable
+        output. Default is stderr. File-names or using syslog can be enabled using
+        config options, this routine is for using your own stream.
+
+    ub_ctx_debuglevel
+        Set debug verbosity for the context. Output is directed to stderr. Higher
+        debug level gives more output.
+
+    ub_ctx_async
+        Set a context behaviour for asynchronous action. if set to true, enables
+        threading and a call to **ub_resolve_async** creates a thread to handle work
+        in the background. If false, a process is forked to handle work in the
+        background. Changes to this setting after **ub_resolve_async** calls have
+        been made have no effect (delete and re-create the context to change).
+
+    ub_poll
+        Poll a context to see if it has any new results. Do not poll in a loop,
+        instead extract the **fd** below to poll for readiness, and then check, or
+        wait using the wait routine. Returns 0 if nothing to read, or nonzero if a
+        result is available. If nonzero, call **ub_process** to do callbacks.
+
+    ub_wait
+        Wait for a context to finish with results. Calls **ub_process** after the
+        wait for you. After the wait, there are no more outstanding asynchronous
+        queries.
+
+    ub_fd 
+        Get file descriptor. Wait for it to become readable, at this point answers
+        are returned from the asynchronous validating resolver. Then call the
+        **ub_process** to continue processing.
+
+    ub_process
+        Call this routine to continue processing results from the validating
+        resolver (when the **fd** becomes readable). Will perform necessary
+        callbacks.
+
+    ub_resolve
+        Perform resolution and validation of the target name. The name is a domain
+        name in a zero terminated text string. The rrtype and rrclass are DNS type
+        and class codes. The result structure is newly allocated with the resulting
+        data.
+
+    ub_resolve_async
+        Perform asynchronous resolution and validation of the target name. Arguments
+        mean the same as for **ub_resolve** except no data is returned immediately,
+        instead a callback is called later. The callback receives a copy of the
+        mydata pointer, that you can use to pass information to the callback. The
+        callback type is a function pointer to a function declared as
+
+        .. code-block:: c
+
+            void my_callback_function(void* my_arg, int err,
+                            struct ub_result* result);
+
+        The **async_id** is returned so you can (at your option) decide to track it
+        and cancel the request if needed. If you pass a NULL pointer the
+        **async_id** is not returned.
+
+    ub_cancel
+        Cancel an async query in progress. This may return an error if the query
+        does not exist, or the query is already being delivered, in that case you
+        may still get a callback for the query.
+
+    ub_resolve_free
+        Free struct **ub_result** contents after use.
+
+    ub_strerror
+        Convert error value from one of the unbound library functions to a human
+        readable string.
+
+    ub_ctx_print_local_zones
+        Debug printout the local authority information to debug output.
+
+    ub_ctx_zone_add
+        Add new zone to local authority info, like local-zone
+        :manpage:`unbound.conf(5)` statement.
+
+    ub_ctx_zone_remove
+        Delete zone from local authority info.
+
+    ub_ctx_data_add
+        Add resource record data to local authority info, like local-data
+        :manpage:`unbound.conf(5)` statement.
+
+    ub_ctx_data_remove
+        Delete local authority data from the name given.
 
 Result Data structure
 ---------------------