diff.h File Reference

A diff is a convenience type representing a list of changes to be made to a database. More...

#include <isc/lang.h>
#include <isc/magic.h>
#include <dns/name.h>
#include <dns/rdata.h>
#include <dns/types.h>

Go to the source code of this file.

Data Structures

struct dns_difftuple

struct dns_diff

Defines

#define DNS_DIFF_H   1

#define DNS_DIFFTUPLE_MAGIC   ISC_MAGIC('D','I','F','T')

#define DNS_DIFFTUPLE_VALID(t)   ISC_MAGIC_VALID(t, DNS_DIFFTUPLE_MAGIC)

#define DNS_DIFF_MAGIC   ISC_MAGIC('D','I','F','F')

#define DNS_DIFF_VALID(t)   ISC_MAGIC_VALID(t, DNS_DIFF_MAGIC)

Typedefs

typedef struct dns_difftuple dns_difftuple_t

typedef struct dns_diff dns_diff_t

A dns_diff_t represents a set of changes being applied to a zone. Diffs are also used to represent "RRset exists (value dependent)" prerequisites.

typedef int dns_diff_compare_func (const void *, const void *)

Enumerations

enum dns_diffop_t {
  DNS_DIFFOP_ADD = 0, DNS_DIFFOP_DEL = 1, DNS_DIFFOP_EXISTS = 2, DNS_DIFFOP_ADDRESIGN = 4,
  DNS_DIFFOP_DELRESIGN = 5
}

A dns_difftuple_t represents a single RR being added or deleted. The RR type and class are in the 'rdata' member; the class is always the real one, not a DynDNS meta-class, so that the rdatas can be compared using dns_rdata_compare(). The TTL is significant even for deletions, because a deletion/addition pair cannot be canceled out if the TTL differs (it might be an explicit TTL update). More...

Functions

ISC_LANG_BEGINDECLS isc_result_t dns_difftuple_create (isc_mem_t *mctx, dns_diffop_t op, dns_name_t *name, dns_ttl_t ttl, dns_rdata_t *rdata, dns_difftuple_t **tp)

Create a tuple. Deep copies are made of the name and rdata, so they need not remain valid after the call.

void dns_difftuple_free (dns_difftuple_t **tp)

Free a tuple.

isc_result_t dns_difftuple_copy (dns_difftuple_t *orig, dns_difftuple_t **copyp)

Copy a tuple.

void dns_diff_init (isc_mem_t *mctx, dns_diff_t *diff)

Initialize a diff.

void dns_diff_clear (dns_diff_t *diff)

Clear a diff, destroying all its tuples.

void dns_diff_append (dns_diff_t *diff, dns_difftuple_t **tuple)

Append a single tuple to a diff.

void dns_diff_appendminimal (dns_diff_t *diff, dns_difftuple_t **tuple)

Append 'tuple' to 'diff', removing any duplicate or conflicting updates as needed to create a minimal diff.

isc_result_t dns_diff_sort (dns_diff_t *diff, dns_diff_compare_func *compare)

Sort 'diff' in-place according to the comparison function 'compare'.

isc_result_t dns_diff_apply (dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver)

isc_result_t dns_diff_applysilently (dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver)

Apply 'diff' to the database 'db'.

isc_result_t dns_diff_load (dns_diff_t *diff, dns_addrdatasetfunc_t addfunc, void *add_private)

Like dns_diff_apply, but for use when loading a new database instead of modifying an existing one. This bypasses the database transaction mechanisms.

isc_result_t dns_diff_print (dns_diff_t *diff, FILE *file)

Print the differences to 'file' or if 'file' is NULL via the logging system.

Detailed Description

A diff is a convenience type representing a list of changes to be made to a database.

Definition in file diff.h.

Define Documentation

#define DNS_DIFF_H 1

Definition at line 21 of file diff.h.

#define DNS_DIFFTUPLE_MAGIC ISC_MAGIC('D','I','F','T')

Definition at line 78 of file diff.h.

Referenced by dns_difftuple_create().

#define DNS_DIFFTUPLE_VALID ( t ) ISC_MAGIC_VALID(t, DNS_DIFFTUPLE_MAGIC)

Definition at line 79 of file diff.h.

Referenced by diff_tuple_tordataset(), dns_diff_appendminimal(), and dns_difftuple_free().

#define DNS_DIFF_MAGIC ISC_MAGIC('D','I','F','F')

Definition at line 99 of file diff.h.

Referenced by dns_diff_init().

#define DNS_DIFF_VALID ( t ) ISC_MAGIC_VALID(t, DNS_DIFF_MAGIC)

Definition at line 100 of file diff.h.

Referenced by diff_apply(), dns_diff_appendminimal(), dns_diff_clear(), dns_diff_load(), dns_diff_print(), dns_diff_sort(), dns_journal_writediff(), and temp_append().

Typedef Documentation

typedef struct dns_difftuple dns_difftuple_t

Definition at line 76 of file diff.h.

typedef struct dns_diff dns_diff_t

A dns_diff_t represents a set of changes being applied to a zone. Diffs are also used to represent "RRset exists (value dependent)" prerequisites.

Definition at line 97 of file diff.h.

typedef int dns_diff_compare_func(const void *, const void *)

Definition at line 109 of file diff.h.

Enumeration Type Documentation

enum dns_diffop_t

A dns_difftuple_t represents a single RR being added or deleted. The RR type and class are in the 'rdata' member; the class is always the real one, not a DynDNS meta-class, so that the rdatas can be compared using dns_rdata_compare(). The TTL is significant even for deletions, because a deletion/addition pair cannot be canceled out if the TTL differs (it might be an explicit TTL update).

Tuples are also used to represent complete RRs with owner names for a couple of other purposes, such as the individual RRs of a "RRset exists (value dependent)" prerequisite set. In this case, op==DNS_DIFFOP_EXISTS, and the TTL is ignored.

DNS_DIFFOP_*RESIGN will cause the 'resign' attribute of the resulting RRset to be recomputed to be 'resign' seconds before the earliest RRSIG timeexpire.

Enumerator:

DNS_DIFFOP_ADD	Add an RR.
DNS_DIFFOP_DEL	Delete an RR.
DNS_DIFFOP_EXISTS	Assert RR existence.
DNS_DIFFOP_ADDRESIGN	ADD + RESIGN.
DNS_DIFFOP_DELRESIGN	DEL + RESIGN.

Definition at line 68 of file diff.h.

Function Documentation

ISC_LANG_BEGINDECLS isc_result_t dns_difftuple_create	(	isc_mem_t *	mctx,
		dns_diffop_t	op,
		dns_name_t *	name,
		dns_ttl_t	ttl,
		dns_rdata_t *	rdata,
		dns_difftuple_t **	tp
	)

Create a tuple. Deep copies are made of the name and rdata, so they need not remain valid after the call.

Requires:

*tp != NULL && *tp == NULL.

Returns:

ISC_R_SUCCESS
ISC_R_NOMEMORY

Definition at line 57 of file diff.c.

References dns_rdata::data, DNS_DIFFTUPLE_MAGIC, dns_name_clone(), dns_name_init(), dns_rdata_clone(), dns_rdata_init(), INSIST, ISC_LINK_INIT, isc_mem_allocate, isc_mem_attach(), ISC_R_NOMEMORY, ISC_R_SUCCESS, dns_rdata::length, dns_name::length, dns_difftuple::magic, dns_difftuple::mctx, dns_difftuple::name, dns_name::ndata, dns_difftuple::op, dns_difftuple::rdata, REQUIRE, and dns_difftuple::ttl.

Referenced by add_nsec(), add_nsec3param_records(), add_placeholder_nsec(), add_rr_prepare_action(), add_signing_records(), axfr_putdata(), delete(), dns_db_createsoatuple(), dns_difftuple_copy(), dns_journal_print(), dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), dns_nsec3param_deletechains(), get_name_diff(), ixfr_putdata(), loadds(), namelist_append_name(), publish_key(), remove_key(), roll_forward(), rollback_private(), rrset_cleanup(), signset(), signwithkey(), sync_secure_journal(), temp_append(), update_one_rr(), and writeset().

void dns_difftuple_free ( dns_difftuple_t ** tp )

Free a tuple.

Requires:

**tp is a valid tuple.

Ensures:

*tp == NULL
All memory used by the tuple is freed.

Definition at line 107 of file diff.c.

References DNS_DIFFTUPLE_VALID, dns_name_invalidate(), isc_mem_detach(), isc_mem_free, dns_difftuple::magic, dns_difftuple::mctx, mctx, dns_difftuple::name, and REQUIRE.

Referenced by dns_diff_appendminimal(), dns_diff_clear(), dns_diff_subtract(), do_one_tuple(), ns_xfr_start(), receive_secure_serial(), soa_rrstream_destroy(), sync_secure_db(), sync_secure_journal(), uniqify_name_list(), update_soa_serial(), and xfrin_send_request().

isc_result_t dns_difftuple_copy	(	dns_difftuple_t *	orig,
		dns_difftuple_t **	copyp
	)

Copy a tuple.

Requires:

'orig' points to a valid tuple
copyp != NULL && *copyp == NULL

Definition at line 122 of file diff.c.

References dns_difftuple_create(), dns_difftuple::mctx, dns_difftuple::name, dns_difftuple::op, dns_difftuple::rdata, and dns_difftuple::ttl.

Referenced by update_soa_serial().

void dns_diff_init	(	isc_mem_t *	mctx,
		dns_diff_t *	diff
	)

Initialize a diff.

Requires:

'diff' points to an uninitialized dns_diff_t
allocated by the caller.

Ensures:

'*diff' is a valid, empty diff.

Definition at line 128 of file diff.c.

References DNS_DIFF_MAGIC, ISC_LIST_INIT, dns_diff::magic, and dns_diff::mctx.

Referenced by add_nsec3param_records(), add_signing_records(), add_soa(), ATF_TC_BODY(), build_final_keylist(), cleanup_zone(), diff_namespace(), dns_db_diff(), dns_journal_print(), dns_update_signaturesinc(), do_one_tuple(), keydone(), keyfetch_done(), loadds(), receive_secure_serial(), remove_orphaned_ds(), restore_nsec3param(), roll_forward(), rollback_private(), signname(), sync_keyzone(), temp_check(), update_action(), writeset(), xfrin_create(), zone_nsec3chain(), zone_refreshkeys(), zone_resigninc(), zone_sign(), and zone_unchanged().

void dns_diff_clear ( dns_diff_t * diff )

Clear a diff, destroying all its tuples.

Requires:

'diff' points to a valid dns_diff_t.

Ensures:

Any tuples in the diff are destroyed. The diff now empty, but it is still valid and may be reused without calling dns_diff_init again. The only memory used is that of the dns_diff_t structure itself.

Notes:

Managing the memory of the dns_diff_t structure itself is the caller's responsibility.

Definition at line 135 of file diff.c.

References DNS_DIFF_VALID, dns_difftuple_free(), ENSURE, ISC_LIST_EMPTY, ISC_LIST_HEAD, ISC_LIST_UNLINK, and REQUIRE.

Referenced by add_nsec3param_records(), add_signing_records(), add_soa(), ATF_TC_BODY(), axfr_apply(), build_final_keylist(), cleanup_zone(), diff_namespace(), dns_db_diff(), dns_journal_print(), dns_update_signaturesinc(), do_diff(), ixfr_apply(), keydone(), keyfetch_done(), loadds(), maybe_free(), receive_secure_serial(), restore_nsec3param(), roll_forward(), rollback_private(), signname(), sync_keyzone(), temp_check(), update_action(), writeset(), xfrin_reset(), zone_nsec3chain(), zone_refreshkeys(), zone_resigninc(), zone_sign(), and zone_unchanged().

void dns_diff_append	(	dns_diff_t *	diff,
		dns_difftuple_t **	tuple
	)

Append a single tuple to a diff.

'diff' is a valid diff.
'*tuple' is a valid tuple.

Ensures:

*tuple is NULL.
The tuple has been freed, or will be freed when the diff is cleared.

Definition at line 146 of file diff.c.

References ISC_LIST_APPEND.

Referenced by add_rr_prepare_action(), axfr_putdata(), dns_journal_print(), get_name_diff(), ixfr_putdata(), loadds(), namelist_append_name(), roll_forward(), rrset_cleanup(), signset(), signwithkey(), and writeset().

void dns_diff_appendminimal	(	dns_diff_t *	diff,
		dns_difftuple_t **	tuple
	)

Append 'tuple' to 'diff', removing any duplicate or conflicting updates as needed to create a minimal diff.

Requires:

'diff' is a minimal diff.

Ensures:

'diff' is still a minimal diff.
*tuple is NULL.
The tuple has been freed, or will be freed when the diff is cleared.

Definition at line 155 of file diff.c.

References DNS_DIFF_VALID, dns_difftuple_free(), DNS_DIFFTUPLE_VALID, dns_name_caseequal(), dns_rdata_compare(), ENSURE, ISC_LIST_APPEND, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LIST_UNLINK, dns_difftuple::name, dns_difftuple::op, dns_difftuple::rdata, REQUIRE, dns_difftuple::ttl, and UNEXPECTED_ERROR.

Referenced by add_nsec3param_records(), dns_update_signaturesinc(), do_one_tuple(), publish_key(), remove_key(), remove_orphaned_ds(), sync_secure_journal(), and update_sigs().

isc_result_t dns_diff_sort	(	dns_diff_t *	diff,
		dns_diff_compare_func *	compare
	)

Sort 'diff' in-place according to the comparison function 'compare'.

Definition at line 537 of file diff.c.

References DNS_DIFF_VALID, INSIST, ISC_LIST_APPEND, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LIST_UNLINK, isc_mem_get, isc_mem_put, ISC_R_NOMEMORY, ISC_R_SUCCESS, dns_diff::mctx, and REQUIRE.

Referenced by dns_diff_subtract(), dns_journal_write_transaction(), dns_update_signaturesinc(), temp_check(), uniqify_name_list(), and update_action().

isc_result_t dns_diff_apply	(	dns_diff_t *	diff,
		dns_db_t *	db,
		dns_dbversion_t *	ver
	)

Definition at line 454 of file diff.c.

References diff_apply(), and ISC_TRUE.

Referenced by do_one_tuple(), ixfr_apply(), loadds(), receive_secure_serial(), roll_forward(), and writeset().

isc_result_t dns_diff_applysilently	(	dns_diff_t *	diff,
		dns_db_t *	db,
		dns_dbversion_t *	ver
	)

Apply 'diff' to the database 'db'.

dns_diff_apply() logs warnings about updates with no effect or with inconsistent TTLs; dns_diff_applysilently() does not.

For efficiency, the diff should be sorted by owner name. If it is not sorted, operation will still be correct, but less efficient.

Requires:

*diff is a valid diff (possibly empty), containing tuples of type DNS_DIFFOP_ADD and/or For DNS_DIFFOP_DEL tuples, the TTL is ignored.

Definition at line 459 of file diff.c.

References diff_apply(), and ISC_FALSE.

Referenced by build_final_keylist(), cleanup_zone(), and signname().

isc_result_t dns_diff_load	(	dns_diff_t *	diff,
		dns_addrdatasetfunc_t	addfunc,
		void *	add_private
	)

Like dns_diff_apply, but for use when loading a new database instead of modifying an existing one. This bypasses the database transaction mechanisms.

Requires:

'addfunc' is a valid dns_addradatasetfunc_t obtained from dns_db_beginload()

'add_private' points to a corresponding dns_dbload_t * (XXX why is it a void pointer, then?)

Definition at line 466 of file diff.c.

References CHECK, dns_rdatalist::covers, DIFF_COMMON_LOGARGS, DNS_DIFF_VALID, DNS_DIFFOP_ADD, dns_name_equal(), DNS_R_NXRRSET, DNS_R_UNCHANGED, dns_rdatalist_init(), dns_rdatalist_tordataset(), dns_rdataset_init(), dns_trust_ultimate, INSIST, ISC_LIST_APPEND, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LOG_WARNING, isc_log_write(), ISC_R_SUCCESS, dns_difftuple::name, name, dns_difftuple::op, dns_difftuple::rdata, rdata_covers(), dns_rdata::rdclass, dns_rdatalist::rdclass, REQUIRE, dns_rdataset::trust, dns_difftuple::ttl, dns_rdatalist::ttl, dns_rdatalist::type, and dns_rdata::type.

Referenced by axfr_apply().

isc_result_t dns_diff_print	(	dns_diff_t *	diff,
		FILE *	file
	)

Print the differences to 'file' or if 'file' is NULL via the logging system.

Require:

'diff' to be valid.
'file' to refer to a open file or NULL.

Returns:

Definition at line 594 of file diff.c.

References isc_region::base, isc_buffer::base, cleanup(), DIFF_COMMON_LOGARGS, diff_tuple_tordataset(), DNS_DIFF_VALID, DNS_DIFFOP_ADD, DNS_DIFFOP_ADDRESIGN, DNS_DIFFOP_DEL, DNS_DIFFOP_DELRESIGN, DNS_DIFFOP_EXISTS, DNS_RDATA_INIT, dns_rdataset_totext(), dns_result_totext(), INSIST, isc_buffer_init, isc_buffer_usedregion, ISC_FALSE, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LOG_DEBUG, isc_log_write(), isc_mem_get, isc_mem_put, ISC_R_NOMEMORY, ISC_R_NOSPACE, ISC_R_SUCCESS, ISC_R_UNEXPECTED, isc_region::length, dns_diff::mctx, dns_difftuple::name, dns_difftuple::op, r, REQUIRE, UNEXPECTED_ERROR, and isc_buffer::used.

Referenced by dns_journal_print(), dns_journal_writediff(), and roll_forward().

Generated on Tue Apr 28 17:41:09 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha


Data Structures
struct	dns_difftuple
struct	dns_diff
Defines
#define	DNS_DIFF_H 1
#define	DNS_DIFFTUPLE_MAGIC ISC_MAGIC('D','I','F','T')
#define	DNS_DIFFTUPLE_VALID(t) ISC_MAGIC_VALID(t, DNS_DIFFTUPLE_MAGIC)
#define	DNS_DIFF_MAGIC ISC_MAGIC('D','I','F','F')
#define	DNS_DIFF_VALID(t) ISC_MAGIC_VALID(t, DNS_DIFF_MAGIC)
Typedefs
typedef struct dns_difftuple	dns_difftuple_t
typedef struct dns_diff	dns_diff_t
	A dns_diff_t represents a set of changes being applied to a zone. Diffs are also used to represent "RRset exists (value dependent)" prerequisites.
typedef int	dns_diff_compare_func (const void , const void )
Enumerations
enum	dns_diffop_t { DNS_DIFFOP_ADD = 0, DNS_DIFFOP_DEL = 1, DNS_DIFFOP_EXISTS = 2, DNS_DIFFOP_ADDRESIGN = 4, DNS_DIFFOP_DELRESIGN = 5 }
	A dns_difftuple_t represents a single RR being added or deleted. The RR type and class are in the 'rdata' member; the class is always the real one, not a DynDNS meta-class, so that the rdatas can be compared using dns_rdata_compare(). The TTL is significant even for deletions, because a deletion/addition pair cannot be canceled out if the TTL differs (it might be an explicit TTL update). More...
Functions
ISC_LANG_BEGINDECLS isc_result_t	dns_difftuple_create (isc_mem_t mctx, dns_diffop_t op, dns_name_t name, dns_ttl_t ttl, dns_rdata_t rdata, dns_difftuple_t *tp)
	Create a tuple. Deep copies are made of the name and rdata, so they need not remain valid after the call.
void	dns_difftuple_free (dns_difftuple_t **tp)
	Free a tuple.
isc_result_t	dns_difftuple_copy (dns_difftuple_t orig, dns_difftuple_t *copyp)
	Copy a tuple.
void	dns_diff_init (isc_mem_t mctx, dns_diff_t diff)
	Initialize a diff.
void	dns_diff_clear (dns_diff_t *diff)
	Clear a diff, destroying all its tuples.
void	dns_diff_append (dns_diff_t diff, dns_difftuple_t *tuple)
	Append a single tuple to a diff.
void	dns_diff_appendminimal (dns_diff_t diff, dns_difftuple_t *tuple)
	Append 'tuple' to 'diff', removing any duplicate or conflicting updates as needed to create a minimal diff.
isc_result_t	dns_diff_sort (dns_diff_t diff, dns_diff_compare_func compare)
	Sort 'diff' in-place according to the comparison function 'compare'.
isc_result_t	dns_diff_apply (dns_diff_t diff, dns_db_t db, dns_dbversion_t *ver)
isc_result_t	dns_diff_applysilently (dns_diff_t diff, dns_db_t db, dns_dbversion_t *ver)
	Apply 'diff' to the database 'db'.
isc_result_t	dns_diff_load (dns_diff_t diff, dns_addrdatasetfunc_t addfunc, void add_private)
	Like dns_diff_apply, but for use when loading a new database instead of modifying an existing one. This bypasses the database transaction mechanisms.
isc_result_t	dns_diff_print (dns_diff_t diff, FILE file)
	Print the differences to 'file' or if 'file' is NULL via the logging system.