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