mirror of https://github.com/getdnsapi/getdns.git
175 lines
5.7 KiB
Groff
175 lines
5.7 KiB
Groff
|
.\" The "BSD-New" License
|
||
|
|
.\"
|
||
|
|
.\" Copyright (c) 2013, NLNet Labs, Versign, 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 name of the <organization> 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_set 3 "@date@" "getdns @version@" getdns
|
||
|
|
.SH NAME
|
||
|
|
.B getdns_context_set_context_update_callback,
|
||
|
|
.B getdns_context_set_dns_transport,
|
||
|
|
.B getdns_context_set_limit_outstanding_queries,
|
||
|
|
.B getdns_context_set_namespaces,
|
||
|
|
.B getdns_context_set_resolution_type,
|
||
|
|
.B getdns_context_set_timeout
|
||
|
|
-- getdns context manipulation routines
|
||
|
|
|
||
|
|
.SH LIBRARY
|
||
|
|
DNS Resolver library (libgetdns, -lgetdns)
|
||
|
|
|
||
|
|
.SH SYNOPSIS
|
||
|
|
#include <getdns.h>
|
||
|
|
|
||
|
|
getdns_return_t
|
||
|
|
.br
|
||
|
|
.B getdns_context_set_context_update_callback
|
||
|
|
(getdns_context_t context,
|
||
|
|
.RS 3
|
||
|
|
.br
|
||
|
|
(*callback)(struct getdns_context *context, uint16_t changed_item))
|
||
|
|
.RE
|
||
|
|
|
||
|
|
getdns_return_t
|
||
|
|
.br
|
||
|
|
.B getdns_context_set_dns_transport
|
||
|
|
(getdns_context_t context,
|
||
|
|
.RS 3
|
||
|
|
.br
|
||
|
|
uint16_t transport)
|
||
|
|
.RE
|
||
|
|
|
||
|
|
getdns_return_t
|
||
|
|
.br
|
||
|
|
.B getdns_context_set_limit_outstanding_queries
|
||
|
|
(getdns_context_t context,
|
||
|
|
.RS 3
|
||
|
|
.br
|
||
|
|
uint16_t limit)
|
||
|
|
.RE
|
||
|
|
|
||
|
|
getdns_return_t
|
||
|
|
.br
|
||
|
|
.B getdns_context_set_namespaces
|
||
|
|
(getdns_context_t context,
|
||
|
|
.RS 3
|
||
|
|
.br
|
||
|
|
size_t namespace_count,
|
||
|
|
.br
|
||
|
|
uint16_t *namespaces)
|
||
|
|
.RE
|
||
|
|
|
||
|
|
getdns_return_t
|
||
|
|
.br
|
||
|
|
.B getdns_context_set_resolution_type
|
||
|
|
(getdns_context_t context,
|
||
|
|
.RS 3
|
||
|
|
uint16_t restype)
|
||
|
|
.RE
|
||
|
|
|
||
|
|
getdns_return_t
|
||
|
|
.br
|
||
|
|
.B getdns_context_set_timeout
|
||
|
|
(getdns_context_t context,
|
||
|
|
.RS 3
|
||
|
|
uint16_t timeout)
|
||
|
|
.RE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
|
||
|
|
.LP
|
||
|
|
These functions are used to manipulate a previously allocated and initialized context, see getdns_context (3) for more details on the functions used to allocate, initialized and destroy contexts and for a more detailed discussion of the getdns_context in general.
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I context
|
||
|
|
.RP
|
||
|
|
a previously allocated and initialized getdns_context
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I callback
|
||
|
|
.RP
|
||
|
|
a callback function that will be called when changes are made to the system files (/etc/resolv.conf and /etc/hosts) for contexts created with set_from_os = 1. When this function is called the changed_item parameter indicates which item in the context has changed.
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I transport
|
||
|
|
.RP
|
||
|
|
may be one of GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP, GETDNS_CONTEXT_UDP_ONLY, GETDNS_CONTEXT_TCP_ONLY, GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN. If you need more information on what each of these means reread the mnemonic and take a guess ;)
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I limit
|
||
|
|
.RP
|
||
|
|
the maximum number of concurrent outstanding (unanswered) DNS queries, if exceeeded the API will queue queries and issue them as the number of outstanding queries drops. A value of 0 indicates that there is no limit.
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I namespaces
|
||
|
|
.RP
|
||
|
|
The namespaces array contains an ordered list of namespaces that will be queried. Important: this context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other funtions. The values are GETDNS_CONTEXT_NAMESPACE_DNS, GETDNS_CONTEXT_NAMESPACE_LOCALNAMES, GETDNS_CONTEXT_NAMESPACE_NETBIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMESPACE_NIS. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS.
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I restype
|
||
|
|
.RP
|
||
|
|
can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or GETDNS_CONTEXT_STUB (requires that forwarders be specified by the caller).
|
||
|
|
|
||
|
|
.HP 3
|
||
|
|
.I timeout
|
||
|
|
.RP
|
||
|
|
the number of seconds the API will wait for a response, after which the callback will be invoked (or the synchronous function will return) with a timeout error.
|
||
|
|
|
||
|
|
.HP
|
||
|
|
.SH "RETURN VALUES"
|
||
|
|
|
||
|
|
Upon successful completion the functions return
|
||
|
|
.B GETDNS_RETURN_GOOD
|
||
|
|
, otherwise the following error values are returned:
|
||
|
|
|
||
|
|
.LP
|
||
|
|
.B GETDNS_RETURN_BAD_CONTEXT
|
||
|
|
if the context pointer is invalid
|
||
|
|
.LP
|
||
|
|
.B GETDNS_RETURN_CONTEXT_UPDATE_FAIL
|
||
|
|
if there was a problem updating the context
|
||
|
|
|
||
|
|
.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 (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).
|
||
|
|
|