mirror of https://github.com/getdnsapi/getdns.git
233 lines
8.6 KiB
Groff
233 lines
8.6 KiB
Groff
.\" The "BSD-New" License
|
|
.\"
|
|
.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are met:
|
|
.\" * Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" * Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" * Neither the names of the copyright holders nor the
|
|
.\" names of its contributors may be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY
|
|
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
|
|
.TH getdns_context 3 "@date@" "getdns @version@" getdns
|
|
.SH NAME
|
|
.B getdns_context_create,
|
|
.B getdns_context_create_with_memory_functions,
|
|
.B getdns_context_create_with_extended_memory_functions,
|
|
.B getdns_context_destroy,
|
|
.B getdns_context_get_api_information
|
|
-- getdns context create and destroy routines
|
|
|
|
.SH LIBRARY
|
|
DNS Resolver library (libgetdns, -lgetdns)
|
|
|
|
.SH SYNOPSIS
|
|
#include <getdns.h>
|
|
|
|
getdns_return_t
|
|
.br
|
|
.B getdns_context_create
|
|
(getdns_context ** context,
|
|
.RS 3
|
|
.br
|
|
int set_from_os)
|
|
.RE
|
|
|
|
getdns_return_t
|
|
.br
|
|
.B getdns_context_create_with_memory_functions
|
|
(getdns_context ** context,
|
|
.RS 3
|
|
.br
|
|
int set_from_os,
|
|
.br
|
|
void *(*malloc) (size_t),
|
|
.br
|
|
void *(*realloc) (void *, size_t),
|
|
.br
|
|
void (*free) (void *))
|
|
.RE
|
|
|
|
getdns_return_t
|
|
.br
|
|
.B getdns_context_create_with_extended_memory_functions
|
|
(getdns_context **context,
|
|
.RS 3
|
|
.br
|
|
int set_from_os,
|
|
.br
|
|
void *userarg,
|
|
.br
|
|
void *(*malloc) (void *userarg, size_t),
|
|
.br
|
|
void *(*realloc) (void *userarg, void *, size_t),
|
|
.br
|
|
void (*free) (void *userarg, void *))
|
|
.RE
|
|
|
|
void
|
|
.br
|
|
.B getdns_context_destroy
|
|
(getdns_context *context)
|
|
|
|
getdns_dict *
|
|
.br
|
|
.B getdns_context_get_api_information
|
|
(getdns_context *context)
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
Calls to getdns functions require a DNS context, which is a group of API
|
|
settings that affect how DNS calls are made. For most applications, a default
|
|
context is sufficient.
|
|
|
|
.LP
|
|
To create a new DNS context, use the function:
|
|
.RS 3
|
|
.br
|
|
getdns_return_t
|
|
.B getdns_context_create
|
|
(getdns_context_t *context, bool set_from_os)
|
|
.RE
|
|
|
|
.LP
|
|
The call to getdns_context_create immediately returns a context that can be
|
|
used with other API calls; that context contains the API's default values. Most
|
|
applications will want set_from_os set to true.
|
|
|
|
.LP
|
|
To clean up the context, including cleaning up all outstanding transactions
|
|
that were called using this context, use the function:
|
|
.RS 3
|
|
.br
|
|
void
|
|
.B getdns_context_destroy
|
|
(getdns_context_t context)
|
|
.RE
|
|
|
|
.LP
|
|
When getdns_context_destroy() returns, the application knows that all
|
|
outstanding transactions associated with this context will have been called;
|
|
callbacks that had not been called before getdns_context_destroy() was called
|
|
will be called with a callback_type of GETDNS_CALLBACK_CANCEL.
|
|
getdns_context_destroy() returns after all of the needed cleanup is done and
|
|
callbacks are made.
|
|
|
|
.HP 3
|
|
.I context
|
|
.RP
|
|
Used to return the pointer to an opaque structure. The caller passes the address of a pointer (decl: getdns_context *context; passed as &context) which will be populated as a result of returning from the function. The result is a newly allocated and initialized context (if there are no errors). In the getdns_destroy_context function this is the context whose associated memory will be released.
|
|
|
|
.HP 3
|
|
.I set_from_os
|
|
.RP
|
|
If set_from_os is 0 then the caller must provide forwarding name servers if running in stub mode. If set_from_os is 1 then the system files are used to initialize the context. /etc/resolv.conf is used to populate forwarders when running as a stub resolver (only "nameserver" lines are recognized). If set_from_os is 1 /etc/hosts entries are preferred before resorting to a DNS query. Errors in the system files will not prevent the context form being constructed.
|
|
|
|
.HP 3
|
|
.I userarg
|
|
.RP
|
|
In the extended use case this argument is passed unchanged to each of the memory management functions each time they are called.
|
|
|
|
.HP 3
|
|
.I malloc
|
|
.RP
|
|
The function that will be used for creating response dicts (and the members within the response dicts). By default the system malloc is used.
|
|
|
|
.HP 3
|
|
.I realloc
|
|
.RP
|
|
The function that will be used for creating response dicts (and the members within the response dicts). By default the system realloc is used.
|
|
|
|
.HP 3
|
|
.I free
|
|
.RP
|
|
The function that will be used for releasing storage for response dicts (and the members within the response dicts). By default the system free is used.
|
|
|
|
|
|
.SH DESCRIPTION (LONG)
|
|
|
|
.LP
|
|
Many calls in the DNS API require a DNS context. A DNS context contains the information that the API needs in order to process DNS calls, such as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. The internal structure of the DNS context is opaque, and might be different on each OS. When a context is passed to any function, it must be an allocated context; the context must not be NULL.
|
|
|
|
.LP
|
|
A typical application using this API doesn't need to know anything about contexts. Basically, the application creates a default context, uses it in the functions that require a context, and then deallocates it when done. Context manipulation is available for more DNS-aware programs, but is unlikely to be of interest to applications that just want the results of lookups for A, AAAA, SRV, and PTR records.
|
|
|
|
.LP
|
|
It is expected that contexts in implementations of the API will not necessarily be thread-safe, but they will not be thread-hostile. A context should not be used by multiple threads: create a new context for use on a different thread. It is just fine for an application to have many contexts, and some DNS-heavy applications will certainly want to have many even if the application uses a single thread.
|
|
|
|
.LP
|
|
When the context is used in the API for the first time and set_from_os is 1, the API starts replacing some of the values with values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on, then proceeds with the new function. Some advanced users will not want the API to change the values to the OS's defaults; if set_from_os is 0, the API will not do any updates to the initial values based on changes in the OS. For example, this might be useful if the API is acting as a stub resolver that is using a specific upstream recursive resolver chosen by the application, not the one that might come back from DHCP.
|
|
|
|
.HP
|
|
.SH "RETURN VALUES"
|
|
|
|
Upon successful completion each of these functions return
|
|
.B GETDNS_RETURN_GOOD
|
|
, otherwise the following error values are returned:
|
|
|
|
.LP
|
|
.B GETDNS_RETURN_GENERIC_ERROR
|
|
memory allocation failed or some other untoward thing happened while initializing the context
|
|
|
|
.LP
|
|
.B GETDNS_RETURN_BAD_CONTEXT
|
|
if the context pointer is invalid (getdns_context_destroy)
|
|
|
|
.LP
|
|
The getdns_dict returned by getdns_context_get_api_information must be
|
|
destroyed by the called and includes the following name/value pairs:
|
|
|
|
.IP version_string
|
|
a bindata containing a printable string of the version of the DNS API implemented by this library
|
|
|
|
.IP implementation_string
|
|
a bindata containing a printable string set by the implementation
|
|
|
|
.IP resolution_type
|
|
an int equal to GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB
|
|
|
|
.IP all_context
|
|
a getdns_dict with names for all the types of context, feed it to getdns_pretty_print_dict (3) for something easily readable
|
|
|
|
.SH EXAMPLES
|
|
|
|
TBD
|
|
|
|
.SH FILES
|
|
.br
|
|
/etc/hosts
|
|
.br
|
|
/etc/resolv.conf
|
|
|
|
.SH SEE ALSO
|
|
.BR libgetdns (3),
|
|
.BR getdns_address (3),
|
|
.BR getdns_address_sync (3),
|
|
.BR getdns_context_set (3),
|
|
.BR getdns_context_set_context_update_callback (3),
|
|
.BR getdns_general (3),
|
|
.BR getdns_general_sync (3),
|
|
.BR getdns_hostname (3),
|
|
.BR getdns_hostname_sync (3),
|
|
.BR getdns_service (3),
|
|
.BR getdns_service_sync (3).
|
|
|