1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
|
/*
* Copyright (C) 2004-2008 Internet Systems Consortium, Inc. ("ISC")
* Copyright (C) 1999-2001 Internet Software Consortium.
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
* REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
* AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
* INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
* LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
* OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
/* $Id: journal.h,v 1.33 2008/04/01 23:47:10 tbox Exp $ */
#ifndef DNS_JOURNAL_H
#define DNS_JOURNAL_H 1
/*****
***** Module Info
*****/
/*! \file dns/journal.h
* \brief
* Database journalling.
*/
/***
*** Imports
***/
#include <isc/lang.h>
#include <isc/magic.h>
#include <dns/name.h>
#include <dns/diff.h>
#include <dns/rdata.h>
#include <dns/types.h>
/***
*** Defines.
***/
#define DNS_JOURNALOPT_RESIGN 0x00000001
/***
*** Types
***/
/*%
* A dns_journal_t represents an open journal file. This is an opaque type.
*
* A particular dns_journal_t object may be opened for writing, in which case
* it can be used for writing transactions to a journal file, or it can be
* opened for reading, in which case it can be used for reading transactions
* from (iterating over) a journal file. A single dns_journal_t object may
* not be used for both purposes.
*/
typedef struct dns_journal dns_journal_t;
/***
*** Functions
***/
ISC_LANG_BEGINDECLS
/**************************************************************************/
isc_result_t
dns_db_createsoatuple(dns_db_t *db, dns_dbversion_t *ver, isc_mem_t *mctx,
dns_diffop_t op, dns_difftuple_t **tp);
/*!< brief
* Create a diff tuple for the current database SOA.
* XXX this probably belongs somewhere else.
*/
/*@{*/
#define DNS_SERIAL_GT(a, b) ((int)(((a) - (b)) & 0xFFFFFFFF) > 0)
#define DNS_SERIAL_GE(a, b) ((int)(((a) - (b)) & 0xFFFFFFFF) >= 0)
/*!< brief
* Compare SOA serial numbers. DNS_SERIAL_GT(a, b) returns true iff
* a is "greater than" b where "greater than" is as defined in RFC1982.
* DNS_SERIAL_GE(a, b) returns true iff a is "greater than or equal to" b.
*/
/*@}*/
/**************************************************************************/
/*
* Journal object creation and destruction.
*/
isc_result_t
dns_journal_open(isc_mem_t *mctx, const char *filename, isc_boolean_t write,
dns_journal_t **journalp);
/*%<
* Open the journal file 'filename' and create a dns_journal_t object for it.
*
* If 'write' is ISC_TRUE, the journal is open for writing. If it does
* not exist, it is created.
*
* If 'write' is ISC_FALSE, the journal is open for reading. If it does
* not exist, ISC_R_NOTFOUND is returned.
*/
void
dns_journal_destroy(dns_journal_t **journalp);
/*%<
* Destroy a dns_journal_t, closing any open files and freeing its memory.
*/
/**************************************************************************/
/*
* Writing transactions to journals.
*/
isc_result_t
dns_journal_begin_transaction(dns_journal_t *j);
/*%<
* Prepare to write a new transaction to the open journal file 'j'.
*
* Requires:
* \li 'j' is open for writing.
*/
isc_result_t
dns_journal_writediff(dns_journal_t *j, dns_diff_t *diff);
/*%<
* Write 'diff' to the current transaction of journal file 'j'.
*
* Requires:
* \li 'j' is open for writing and dns_journal_begin_transaction()
* has been called.
*
*\li 'diff' is a full or partial, correctly ordered IXFR
* difference sequence.
*/
isc_result_t
dns_journal_commit(dns_journal_t *j);
/*%<
* Commit the current transaction of journal file 'j'.
*
* Requires:
* \li 'j' is open for writing and dns_journal_begin_transaction()
* has been called.
*
* \li dns_journal_writediff() has been called one or more times
* to form a complete, correctly ordered IXFR difference
* sequence.
*/
isc_result_t
dns_journal_write_transaction(dns_journal_t *j, dns_diff_t *diff);
/*%
* Write a complete transaction at once to a journal file,
* sorting it if necessary, and commit it. Equivalent to calling
* dns_diff_sort(), dns_journal_begin_transaction(),
* dns_journal_writediff(), and dns_journal_commit().
*
* Requires:
*\li 'j' is open for writing.
*
* \li 'diff' contains exactly one SOA deletion, one SOA addition
* with a greater serial number, and possibly other changes,
* in arbitrary order.
*/
/**************************************************************************/
/*
* Reading transactions from journals.
*/
isc_uint32_t
dns_journal_first_serial(dns_journal_t *j);
isc_uint32_t
dns_journal_last_serial(dns_journal_t *j);
/*%<
* Get the first and last addressable serial number in the journal.
*/
isc_result_t
dns_journal_iter_init(dns_journal_t *j,
isc_uint32_t begin_serial, isc_uint32_t end_serial);
/*%<
* Prepare to iterate over the transactions that will bring the database
* from SOA serial number 'begin_serial' to 'end_serial'.
*
* Returns:
*\li ISC_R_SUCCESS
*\li ISC_R_RANGE begin_serial is outside the addressable range.
*\li ISC_R_NOTFOUND begin_serial is within the range of adressable
* serial numbers covered by the journal, but
* this particular serial number does not exist.
*/
/*@{*/
isc_result_t
dns_journal_first_rr(dns_journal_t *j);
isc_result_t
dns_journal_next_rr(dns_journal_t *j);
/*%<
* Position the iterator at the first/next RR in a journal
* transaction sequence established using dns_journal_iter_init().
*
* Requires:
* \li dns_journal_iter_init() has been called.
*
*/
/*@}*/
void
dns_journal_current_rr(dns_journal_t *j, dns_name_t **name, isc_uint32_t *ttl,
dns_rdata_t **rdata);
/*%<
* Get the name, ttl, and rdata of the current journal RR.
*
* Requires:
* \li The last call to dns_journal_first_rr() or dns_journal_next_rr()
* returned ISC_R_SUCCESS.
*/
/**************************************************************************/
/*
* Database roll-forward.
*/
isc_result_t
dns_journal_rollforward(isc_mem_t *mctx, dns_db_t *db, unsigned int options,
const char *filename);
/*%<
* Roll forward (play back) the journal file "filename" into the
* database "db". This should be called when the server starts
* after a shutdown or crash.
*
* Requires:
*\li 'mctx' is a valid memory context.
*\li 'db' is a valid database which does not have a version
* open for writing.
*\li 'filename' is the name of the journal file belonging to 'db'.
*
* Returns:
*\li DNS_R_NOJOURNAL when journal does not exist.
*\li ISC_R_NOTFOUND when current serial in not in journal.
*\li ISC_R_RANGE when current serial in not in journals range.
*\li ISC_R_SUCCESS journal has been applied successfully to database.
* others
*/
isc_result_t
dns_journal_print(isc_mem_t *mctx, const char *filename, FILE *file);
/* For debugging not general use */
isc_result_t
dns_db_diff(isc_mem_t *mctx,
dns_db_t *dba, dns_dbversion_t *dbvera,
dns_db_t *dbb, dns_dbversion_t *dbverb,
const char *journal_filename);
/*%<
* Compare the databases 'dba' and 'dbb' and generate a journal
* entry containing the changes to make 'dba' from 'dbb' (note
* the order). This journal entry will consist of a single,
* possibly very large transaction. Append the journal
* entry to the journal file specified by 'journal_filename'.
*/
isc_result_t
dns_journal_compact(isc_mem_t *mctx, char *filename, isc_uint32_t serial,
isc_uint32_t target_size);
/*%<
* Attempt to compact the journal if it is greater that 'target_size'.
* Changes from 'serial' onwards will be preserved. If the journal
* exists and is non-empty 'serial' must exist in the journal.
*/
ISC_LANG_ENDDECLS
#endif /* DNS_JOURNAL_H */
|
