dbiterator.h File Reference

The DNS DB Iterator interface allows iteration of all of the nodes in a database. More...

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

Go to the source code of this file.

Data Structures
struct	dns_dbiteratormethods
struct	dns_dbiterator
	This structure is actually just the common prefix of a DNS db implementation's version of a dns_dbiterator_t. More...
Defines
#define	DNS_DBITERATOR_H   1
#define	DNS_DBITERATOR_MAGIC   ISC_MAGIC('D','N','S','I')
#define	DNS_DBITERATOR_VALID(dbi)   ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC)
Typedefs
typedef ISC_LANG_BEGINDECLS struct dns_dbiteratormethods	dns_dbiteratormethods_t
Functions
void	dns_dbiterator_destroy (dns_dbiterator_t **iteratorp)
	Destroy '*iteratorp'.
isc_result_t	dns_dbiterator_first (dns_dbiterator_t *iterator)
	Move the node cursor to the first node in the database (if any).
isc_result_t	dns_dbiterator_last (dns_dbiterator_t *iterator)
	Move the node cursor to the last node in the database (if any).
isc_result_t	dns_dbiterator_seek (dns_dbiterator_t *iterator, dns_name_t *name)
	Move the node cursor to the node with name 'name'.
isc_result_t	dns_dbiterator_prev (dns_dbiterator_t *iterator)
	Move the node cursor to the previous node in the database (if any).
isc_result_t	dns_dbiterator_next (dns_dbiterator_t *iterator)
	Move the node cursor to the next node in the database (if any).
isc_result_t	dns_dbiterator_current (dns_dbiterator_t *iterator, dns_dbnode_t **nodep, dns_name_t *name)
	Return the current node.
isc_result_t	dns_dbiterator_pause (dns_dbiterator_t *iterator)
	Pause iteration.
isc_result_t	dns_dbiterator_origin (dns_dbiterator_t *iterator, dns_name_t *name)
	Return the origin to which returned node names are relative.
void	dns_dbiterator_setcleanmode (dns_dbiterator_t *iterator, isc_boolean_t mode)
	Indicate that the given iterator is/is not cleaning the DB.

---

Detailed Description

The DNS DB Iterator interface allows iteration of all of the nodes in a database.

The dns_dbiterator_t type is like a "virtual class". To actually use it, an implementation of the class is required. This implementation is supplied by the database.

It is the client's responsibility to call dns_db_detachnode() on all nodes returned.

XXX <more> XXX

MP:

• The iterator itself is not locked. The caller must ensure synchronization.

• The iterator methods ensure appropriate database locking.

Reliability:

• No anticipated impact.

Resources:

• TBS

Security:

• No anticipated impact.

Standards:

• None.

Definition in file dbiterator.h.

---

Define Documentation

#define DNS_DBITERATOR_H   1

Definition at line 21 of file dbiterator.h.

#define DNS_DBITERATOR_MAGIC   ISC_MAGIC('D','N','S','I')

Definition at line 89 of file dbiterator.h.

Referenced by createiterator().

#define DNS_DBITERATOR_VALID

(

dbi

)

ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC)

Definition at line 90 of file dbiterator.h.

Referenced by dns_dbiterator_current(), dns_dbiterator_destroy(), dns_dbiterator_first(), dns_dbiterator_last(), dns_dbiterator_next(), dns_dbiterator_origin(), dns_dbiterator_pause(), dns_dbiterator_prev(), dns_dbiterator_seek(), dns_dbiterator_setcleanmode(), and incremental_cleaning_action().

---

Typedef Documentation

typedef ISC_LANG_BEGINDECLS struct dns_dbiteratormethods dns_dbiteratormethods_t

---

Function Documentation

void dns_dbiterator_destroy

(

dns_dbiterator_t **

iteratorp

)

Destroy '*iteratorp'.

Requires:

• '*iteratorp' is a valid iterator.

Ensures:

• All resources used by the iterator are freed.

• *iteratorp == NULL.

Definition at line 30 of file dbiterator.c.

References DNS_DBITERATOR_VALID, ENSURE, and REQUIRE.

Referenced by begin_cleaning(), cache_cleaner_init(), cache_free(), check_hints(), check_ttls(), cleanup_zone(), cleartree(), diff_namespace(), dns_cache_clean(), dns_cache_flush(), dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), dns_rriterator_destroy(), dumpctx_create(), dumpctx_destroy(), end_cleaning(), incremental_cleaning_action(), integrity_checks(), namelist_append_subdomain(), next_active(), nsec3ify(), nsecify(), postsign(), receive_secure_db(), test_create(), test_reverse(), test_seek(), test_seek_empty(), test_seek_nx(), test_walk(), verifyzone(), zone_addnsec3chain(), zone_check_dup(), zone_free(), zone_nsec3chain(), and zone_sign().

isc_result_t dns_dbiterator_first

(

dns_dbiterator_t *

iterator

)

Move the node cursor to the first node in the database (if any).

Requires:

• 'iterator' is a valid iterator.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMORE There are no nodes in the database.

• Other results are possible, depending on the DB implementation.

Definition at line 44 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_dbiterator::methods, and REQUIRE.

Referenced by begin_cleaning(), check_hints(), check_ttls(), cleanup_zone(), diff_namespace(), dns_cache_clean(), dns_rriterator_first(), dumptostreaminc(), incremental_cleaning_action(), integrity_checks(), next_active(), nsec3ify(), nsecify(), receive_secure_db(), signapex(), test_walk(), verifyzone(), zone_addnsec3chain(), zone_check_dup(), zone_nsec3chain(), and zone_sign().

isc_result_t dns_dbiterator_last

(

dns_dbiterator_t *

iterator

)

Move the node cursor to the last node in the database (if any).

Requires:

• 'iterator' is a valid iterator.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMORE There are no nodes in the database.

• Other results are possible, depending on the DB implementation.

Definition at line 55 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_dbiterator::methods, and REQUIRE.

Referenced by dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), next_active(), and test_reverse().

isc_result_t dns_dbiterator_seek	(	dns_dbiterator_t *	iterator,
		dns_name_t *	name
	)

Move the node cursor to the node with name 'name'.

Requires:

• 'iterator' is a valid iterator.

• 'name' is a valid name.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOTFOUND

• Other results are possible, depending on the DB implementation.

Definition at line 66 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_dbiterator::methods, and REQUIRE.

Referenced by cleartree(), dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), namelist_append_subdomain(), next_active(), signapex(), test_seek(), test_seek_empty(), and test_seek_nx().

isc_result_t dns_dbiterator_prev

(

dns_dbiterator_t *

iterator

)

Move the node cursor to the previous node in the database (if any).

Requires:

• 'iterator' is a valid iterator.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMORE There are no more nodes in the database.

• Other results are possible, depending on the DB implementation.

Definition at line 77 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_dbiterator::methods, and REQUIRE.

Referenced by dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), next_active(), and test_reverse().

isc_result_t dns_dbiterator_next

(

dns_dbiterator_t *

iterator

)

Move the node cursor to the next node in the database (if any).

Requires:

• 'iterator' is a valid iterator.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMORE There are no more nodes in the database.

• Other results are possible, depending on the DB implementation.

Definition at line 88 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_dbiterator::methods, and REQUIRE.

Referenced by assignwork(), check_hints(), check_ttls(), cleanup_zone(), cleartree(), diff_namespace(), dns_cache_clean(), dns_rriterator_first(), dns_rriterator_nextrrset(), dumptostreaminc(), incremental_cleaning_action(), integrity_checks(), namelist_append_subdomain(), next_active(), nsec3ify(), nsecify(), receive_secure_db(), test_seek(), test_walk(), verifyzone(), zone_check_dup(), zone_nsec3chain(), and zone_sign().

isc_result_t dns_dbiterator_current	(	dns_dbiterator_t *	iterator,
		dns_dbnode_t **	nodep,
		dns_name_t *	name
	)

Return the current node.

Notes:

• If 'name' is not NULL, it will be set to the name of the node.

Requires:

• 'iterator' is a valid iterator.

• nodep != NULL && *nodep == NULL

• The node cursor of 'iterator' is at a valid location (i.e. the result of last call to a cursor movement command was ISC_R_SUCCESS).

• 'name' is NULL, or is a valid name with a dedicated buffer.

Returns:

• ISC_R_SUCCESS
• DNS_R_NEWORIGIN If this iterator was created with 'relative_names' set to ISC_TRUE, then DNS_R_NEWORIGIN will be returned when the origin the names are relative to changes. This result can occur only when 'name' is not NULL. This is also a successful result.

• Other results are possible, depending on the DB implementation.

Definition at line 99 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_name_hasbuffer(), dns_dbiterator::methods, and REQUIRE.

Referenced by assignwork(), check_hints(), check_ttls(), cleanup_zone(), cleartree(), dns_cache_clean(), dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), dns_rriterator_first(), dns_rriterator_nextrrset(), dumptostreaminc(), get_name_diff(), incremental_cleaning_action(), integrity_checks(), namelist_append_subdomain(), next_active(), nsec3ify(), nsecify(), receive_secure_db(), signapex(), test_reverse(), test_seek(), test_walk(), verifyzone(), zone_check_dup(), zone_nsec3chain(), and zone_sign().

isc_result_t dns_dbiterator_pause

(

dns_dbiterator_t *

iterator

)

Pause iteration.

Calling a cursor movement method or dns_dbiterator_current() may cause database locks to be acquired. Rather than reacquire these locks every time one of these routines is called, the locks may simply be held. Calling dns_dbiterator_pause() releases any such locks. Iterator clients should call this routine any time they are not going to execute another iterator method in the immediate future.

Requires:

• 'iterator' is a valid iterator.

Ensures:

• Any database locks being held for efficiency of iterator access are released.

Returns:

• ISC_R_SUCCESS

• Other results are possible, depending on the DB implementation.

Definition at line 114 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_dbiterator::methods, and REQUIRE.

Referenced by begin_cleaning(), dns_nsec3_addnsec3(), dns_nsec3_delnsec3(), dns_rriterator_pause(), dumptostreaminc(), end_cleaning(), incremental_cleaning_action(), next_active(), nsec3ify(), nsecify(), zone_addnsec3chain(), zone_nsec3chain(), and zone_sign().

isc_result_t dns_dbiterator_origin	(	dns_dbiterator_t *	iterator,
		dns_name_t *	name
	)

Return the origin to which returned node names are relative.

Requires:

• 'iterator' is a valid relative_names iterator.

• 'name' is a valid name with a dedicated buffer.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOSPACE

• Other results are possible, depending on the DB implementation.

Definition at line 125 of file dbiterator.c.

References DNS_DBITERATOR_VALID, dns_name_hasbuffer(), dns_dbiterator::methods, dns_dbiterator::relative_names, and REQUIRE.

Referenced by dumptostreaminc().

void dns_dbiterator_setcleanmode	(	dns_dbiterator_t *	iterator,
		isc_boolean_t	mode
	)

Indicate that the given iterator is/is not cleaning the DB.

Notes:

• When 'mode' is ISC_TRUE,

Requires:

• 'iterator' is a valid iterator.

Definition at line 139 of file dbiterator.c.

References dns_dbiterator::cleaning, DNS_DBITERATOR_VALID, and REQUIRE.

Referenced by begin_cleaning().

---