/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef DNS_JOURNAL_H

[12] Fix | Delete

#define DNS_JOURNAL_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file dns/journal.h

[19] Fix | Delete

* \brief

[20] Fix | Delete

* Database journaling.

[21] Fix | Delete

*/

[22] Fix | Delete

[23] Fix | Delete

/***

[24] Fix | Delete

*** Imports

[25] Fix | Delete

***/

[26] Fix | Delete

[27] Fix | Delete

#include <inttypes.h>

[28] Fix | Delete

#include <stdbool.h>

[29] Fix | Delete

[30] Fix | Delete

#include <isc/lang.h>

[31] Fix | Delete

#include <isc/magic.h>

[32] Fix | Delete

[33] Fix | Delete

#include <dns/name.h>

[34] Fix | Delete

#include <dns/diff.h>

[35] Fix | Delete

#include <dns/rdata.h>

[36] Fix | Delete

#include <dns/types.h>

[37] Fix | Delete

[38] Fix | Delete

/***

[39] Fix | Delete

*** Defines.

[40] Fix | Delete

***/

[41] Fix | Delete

#define DNS_JOURNALOPT_RESIGN 0x00000001

[42] Fix | Delete

[43] Fix | Delete

#define DNS_JOURNAL_READ 0x00000000 /* false */

[44] Fix | Delete

#define DNS_JOURNAL_CREATE 0x00000001 /* true */

[45] Fix | Delete

#define DNS_JOURNAL_WRITE 0x00000002

[46] Fix | Delete

[47] Fix | Delete

/***

[48] Fix | Delete

*** Types

[49] Fix | Delete

***/

[50] Fix | Delete

[51] Fix | Delete

/*%

[52] Fix | Delete

* A dns_journal_t represents an open journal file. This is an opaque type.

[53] Fix | Delete

*

[54] Fix | Delete

* A particular dns_journal_t object may be opened for writing, in which case

[55] Fix | Delete

* it can be used for writing transactions to a journal file, or it can be

[56] Fix | Delete

* opened for reading, in which case it can be used for reading transactions

[57] Fix | Delete

* from (iterating over) a journal file. A single dns_journal_t object may

[58] Fix | Delete

* not be used for both purposes.

[59] Fix | Delete

*/

[60] Fix | Delete

typedef struct dns_journal dns_journal_t;

[61] Fix | Delete

[62] Fix | Delete

[63] Fix | Delete

/***

[64] Fix | Delete

*** Functions

[65] Fix | Delete

***/

[66] Fix | Delete

[67] Fix | Delete

ISC_LANG_BEGINDECLS

[68] Fix | Delete

[69] Fix | Delete

/**************************************************************************/

[70] Fix | Delete

[71] Fix | Delete

isc_result_t

[72] Fix | Delete

dns_db_createsoatuple(dns_db_t *db, dns_dbversion_t *ver, isc_mem_t *mctx,

[73] Fix | Delete

dns_diffop_t op, dns_difftuple_t **tp);

[74] Fix | Delete

/*!< brief

[75] Fix | Delete

* Create a diff tuple for the current database SOA.

[76] Fix | Delete

* XXX this probably belongs somewhere else.

[77] Fix | Delete

*/

[78] Fix | Delete

[79] Fix | Delete

[80] Fix | Delete

/*@{*/

[81] Fix | Delete

#define DNS_SERIAL_GT(a, b) ((int)(((a) - (b)) & 0xFFFFFFFF) > 0)

[82] Fix | Delete

#define DNS_SERIAL_GE(a, b) ((int)(((a) - (b)) & 0xFFFFFFFF) >= 0)

[83] Fix | Delete

/*!< brief

[84] Fix | Delete

* Compare SOA serial numbers. DNS_SERIAL_GT(a, b) returns true iff

[85] Fix | Delete

* a is "greater than" b where "greater than" is as defined in RFC1982.

[86] Fix | Delete

* DNS_SERIAL_GE(a, b) returns true iff a is "greater than or equal to" b.

[87] Fix | Delete

*/

[88] Fix | Delete

/*@}*/

[89] Fix | Delete

[90] Fix | Delete

/**************************************************************************/

[91] Fix | Delete

/*

[92] Fix | Delete

* Journal object creation and destruction.

[93] Fix | Delete

*/

[94] Fix | Delete

[95] Fix | Delete

isc_result_t

[96] Fix | Delete

dns_journal_open(isc_mem_t *mctx, const char *filename, unsigned int mode,

[97] Fix | Delete

dns_journal_t **journalp);

[98] Fix | Delete

/*%<

[99] Fix | Delete

* Open the journal file 'filename' and create a dns_journal_t object for it.

[100] Fix | Delete

*

[101] Fix | Delete

* DNS_JOURNAL_CREATE open the journal for reading and writing and create

[102] Fix | Delete

* the journal if it does not exist.

[103] Fix | Delete

* DNS_JOURNAL_WRITE open the journal for reading and writing.

[104] Fix | Delete

* DNS_JOURNAL_READ open the journal for reading only.

[105] Fix | Delete

*/

[106] Fix | Delete

[107] Fix | Delete

void

[108] Fix | Delete

dns_journal_destroy(dns_journal_t **journalp);

[109] Fix | Delete

/*%<

[110] Fix | Delete

* Destroy a dns_journal_t, closing any open files and freeing its memory.

[111] Fix | Delete

*/

[112] Fix | Delete

[113] Fix | Delete

/**************************************************************************/

[114] Fix | Delete

/*

[115] Fix | Delete

* Writing transactions to journals.

[116] Fix | Delete

*/

[117] Fix | Delete

[118] Fix | Delete

isc_result_t

[119] Fix | Delete

dns_journal_begin_transaction(dns_journal_t *j);

[120] Fix | Delete

/*%<

[121] Fix | Delete

* Prepare to write a new transaction to the open journal file 'j'.

[122] Fix | Delete

*

[123] Fix | Delete

* Requires:

[124] Fix | Delete

* \li 'j' is open for writing.

[125] Fix | Delete

*/

[126] Fix | Delete

[127] Fix | Delete

isc_result_t

[128] Fix | Delete

dns_journal_writediff(dns_journal_t *j, dns_diff_t *diff);

[129] Fix | Delete

/*%<

[130] Fix | Delete

* Write 'diff' to the current transaction of journal file 'j'.

[131] Fix | Delete

*

[132] Fix | Delete

* Requires:

[133] Fix | Delete

* \li 'j' is open for writing and dns_journal_begin_transaction()

[134] Fix | Delete

* has been called.

[135] Fix | Delete

*

[136] Fix | Delete

*\li 'diff' is a full or partial, correctly ordered IXFR

[137] Fix | Delete

* difference sequence.

[138] Fix | Delete

*/

[139] Fix | Delete

[140] Fix | Delete

isc_result_t

[141] Fix | Delete

dns_journal_commit(dns_journal_t *j);

[142] Fix | Delete

/*%<

[143] Fix | Delete

* Commit the current transaction of journal file 'j'.

[144] Fix | Delete

*

[145] Fix | Delete

* Requires:

[146] Fix | Delete

* \li 'j' is open for writing and dns_journal_begin_transaction()

[147] Fix | Delete

* has been called.

[148] Fix | Delete

*

[149] Fix | Delete

* \li dns_journal_writediff() has been called one or more times

[150] Fix | Delete

* to form a complete, correctly ordered IXFR difference

[151] Fix | Delete

* sequence.

[152] Fix | Delete

*/

[153] Fix | Delete

[154] Fix | Delete

isc_result_t

[155] Fix | Delete

dns_journal_write_transaction(dns_journal_t *j, dns_diff_t *diff);

[156] Fix | Delete

/*%

[157] Fix | Delete

* Write a complete transaction at once to a journal file,

[158] Fix | Delete

* sorting it if necessary, and commit it. Equivalent to calling

[159] Fix | Delete

* dns_diff_sort(), dns_journal_begin_transaction(),

[160] Fix | Delete

* dns_journal_writediff(), and dns_journal_commit().

[161] Fix | Delete

*

[162] Fix | Delete

* Requires:

[163] Fix | Delete

*\li 'j' is open for writing.

[164] Fix | Delete

*

[165] Fix | Delete

* \li 'diff' contains exactly one SOA deletion, one SOA addition

[166] Fix | Delete

* with a greater serial number, and possibly other changes,

[167] Fix | Delete

* in arbitrary order.

[168] Fix | Delete

*/

[169] Fix | Delete

[170] Fix | Delete

/**************************************************************************/

[171] Fix | Delete

/*

[172] Fix | Delete

* Reading transactions from journals.

[173] Fix | Delete

*/

[174] Fix | Delete

[175] Fix | Delete

uint32_t

[176] Fix | Delete

dns_journal_first_serial(dns_journal_t *j);

[177] Fix | Delete

uint32_t

[178] Fix | Delete

dns_journal_last_serial(dns_journal_t *j);

[179] Fix | Delete

/*%<

[180] Fix | Delete

* Get the first and last addressable serial number in the journal.

[181] Fix | Delete

*/

[182] Fix | Delete

[183] Fix | Delete

isc_result_t

[184] Fix | Delete

dns_journal_iter_init(dns_journal_t *j,

[185] Fix | Delete

uint32_t begin_serial, uint32_t end_serial);

[186] Fix | Delete

/*%<

[187] Fix | Delete

* Prepare to iterate over the transactions that will bring the database

[188] Fix | Delete

* from SOA serial number 'begin_serial' to 'end_serial'.

[189] Fix | Delete

*

[190] Fix | Delete

* Returns:

[191] Fix | Delete

*\li ISC_R_SUCCESS

[192] Fix | Delete

*\li ISC_R_RANGE begin_serial is outside the addressable range.

[193] Fix | Delete

*\li ISC_R_NOTFOUND begin_serial is within the range of addressable

[194] Fix | Delete

* serial numbers covered by the journal, but

[195] Fix | Delete

* this particular serial number does not exist.

[196] Fix | Delete

*/

[197] Fix | Delete

[198] Fix | Delete

/*@{*/

[199] Fix | Delete

isc_result_t

[200] Fix | Delete

dns_journal_first_rr(dns_journal_t *j);

[201] Fix | Delete

isc_result_t

[202] Fix | Delete

dns_journal_next_rr(dns_journal_t *j);

[203] Fix | Delete

/*%<

[204] Fix | Delete

* Position the iterator at the first/next RR in a journal

[205] Fix | Delete

* transaction sequence established using dns_journal_iter_init().

[206] Fix | Delete

*

[207] Fix | Delete

* Requires:

[208] Fix | Delete

* \li dns_journal_iter_init() has been called.

[209] Fix | Delete

*

[210] Fix | Delete

*/

[211] Fix | Delete

/*@}*/

[212] Fix | Delete

[213] Fix | Delete

void

[214] Fix | Delete

dns_journal_current_rr(dns_journal_t *j, dns_name_t **name, uint32_t *ttl,

[215] Fix | Delete

dns_rdata_t **rdata);

[216] Fix | Delete

/*%<

[217] Fix | Delete

* Get the name, ttl, and rdata of the current journal RR.

[218] Fix | Delete

*

[219] Fix | Delete

* Requires:

[220] Fix | Delete

* \li The last call to dns_journal_first_rr() or dns_journal_next_rr()

[221] Fix | Delete

* returned ISC_R_SUCCESS.

[222] Fix | Delete

*/

[223] Fix | Delete

[224] Fix | Delete

/**************************************************************************/

[225] Fix | Delete

/*

[226] Fix | Delete

* Database roll-forward.

[227] Fix | Delete

*/

[228] Fix | Delete

[229] Fix | Delete

isc_result_t

[230] Fix | Delete

dns_journal_rollforward(isc_mem_t *mctx, dns_db_t *db, unsigned int options,

[231] Fix | Delete

const char *filename);

[232] Fix | Delete

/*%<

[233] Fix | Delete

* Roll forward (play back) the journal file "filename" into the

[234] Fix | Delete

* database "db". This should be called when the server starts

[235] Fix | Delete

* after a shutdown or crash.

[236] Fix | Delete

*

[237] Fix | Delete

* Requires:

[238] Fix | Delete

*\li 'mctx' is a valid memory context.

[239] Fix | Delete

*\li 'db' is a valid database which does not have a version

[240] Fix | Delete

* open for writing.

[241] Fix | Delete

*\li 'filename' is the name of the journal file belonging to 'db'.

[242] Fix | Delete

*

[243] Fix | Delete

* Returns:

[244] Fix | Delete

*\li DNS_R_NOJOURNAL when journal does not exist.

[245] Fix | Delete

*\li ISC_R_NOTFOUND when current serial in not in journal.

[246] Fix | Delete

*\li ISC_R_RANGE when current serial in not in journals range.

[247] Fix | Delete

*\li ISC_R_SUCCESS journal has been applied successfully to database.

[248] Fix | Delete

* others

[249] Fix | Delete

*/

[250] Fix | Delete

[251] Fix | Delete

isc_result_t

[252] Fix | Delete

dns_journal_print(isc_mem_t *mctx, const char *filename, FILE *file);

[253] Fix | Delete

/* For debugging not general use */

[254] Fix | Delete

[255] Fix | Delete

isc_result_t

[256] Fix | Delete

dns_db_diff(isc_mem_t *mctx,

[257] Fix | Delete

dns_db_t *dba, dns_dbversion_t *dbvera,

[258] Fix | Delete

dns_db_t *dbb, dns_dbversion_t *dbverb,

[259] Fix | Delete

const char *journal_filename);

[260] Fix | Delete

[261] Fix | Delete

isc_result_t

[262] Fix | Delete

dns_db_diffx(dns_diff_t *diff, dns_db_t *dba, dns_dbversion_t *dbvera,

[263] Fix | Delete

dns_db_t *dbb, dns_dbversion_t *dbverb,

[264] Fix | Delete

const char *journal_filename);

[265] Fix | Delete

/*%<

[266] Fix | Delete

* Compare the databases 'dba' and 'dbb' and generate a diff/journal

[267] Fix | Delete

* entry containing the changes to make 'dba' from 'dbb' (note

[268] Fix | Delete

* the order). This journal entry will consist of a single,

[269] Fix | Delete

* possibly very large transaction. Append the journal

[270] Fix | Delete

* entry to the journal file specified by 'journal_filename' if

[271] Fix | Delete

* non-NULL.

[272] Fix | Delete

*/

[273] Fix | Delete

[274] Fix | Delete

isc_result_t

[275] Fix | Delete

dns_journal_compact(isc_mem_t *mctx, char *filename, uint32_t serial,

[276] Fix | Delete

uint32_t target_size);

[277] Fix | Delete

/*%<

[278] Fix | Delete

* Attempt to compact the journal if it is greater that 'target_size'.

[279] Fix | Delete

* Changes from 'serial' onwards will be preserved. If the journal

[280] Fix | Delete

* exists and is non-empty 'serial' must exist in the journal.

[281] Fix | Delete

*/

[282] Fix | Delete

[283] Fix | Delete

bool

[284] Fix | Delete

dns_journal_get_sourceserial(dns_journal_t *j, uint32_t *sourceserial);

[285] Fix | Delete

void

[286] Fix | Delete

dns_journal_set_sourceserial(dns_journal_t *j, uint32_t sourceserial);

[287] Fix | Delete

/*%<

[288] Fix | Delete

* Get and set source serial.

[289] Fix | Delete

*

[290] Fix | Delete

* Returns:

[291] Fix | Delete

* true if sourceserial has previously been set.

[292] Fix | Delete

*/

[293] Fix | Delete

[294] Fix | Delete

ISC_LANG_ENDDECLS

[295] Fix | Delete

[296] Fix | Delete

#endif /* DNS_JOURNAL_H */

[297] Fix | Delete

[298] Fix | Delete