dcursor.h File Reference

Functions to iterate over a sets and subsets of items stored in dlists. More...

#include <freeradius-devel/build.h>
#include <freeradius-devel/missing.h>
#include <freeradius-devel/util/dlist.h>
#include <freeradius-devel/util/talloc.h>
#include <stddef.h>
#include <stdbool.h>

Include dependency graph for dcursor.h:

Go to the source code of this file.

Data Structures
struct	fr_dcursor_s
struct	fr_dcursor_stack_t

Macros
#define	FR_DCURSOR(_name)   _name ## _dcursor_t
	Expands to the type name used for the dcursor wrapper structure. More...
#define	FR_DCURSOR_COPY(_name)   _name ## _copy_t
	Expands to the type name used for the dcursor copy function type. More...
#define	FR_DCURSOR_DLIST_TYPES(_name, _list_name, _element_type)
	Define type specific wrapper structs for dcursors. More...
#define	FR_DCURSOR_EVAL(_name)   _name ## _eval_t
	Expands to the type name used for the dcursor evaluator type. More...
#define	FR_DCURSOR_FUNCS(_name, _list_name, _element_type)
	Define type specific wrapper functions for dcursors. More...
#define	fr_dcursor_init(_cursor, _head)
	Initialise a cursor. More...
#define	FR_DCURSOR_INSERT(_name)   _name ## _insert_t
	Expands to the type name used for the dcursor insert function type. More...
#define	FR_DCURSOR_ITER(_name)   _name ## _iter_t
	Expands to the type name used for the dcursor iterator type. More...
#define	fr_dcursor_iter_init(_cursor, _head, _iter, _peek, _uctx)
	Initialise a cursor with a custom iterator. More...
#define	fr_dcursor_iter_mod_init(_cursor, _list, _iter, _peek, _iter_uctx, _insert, _remove, _mod_uctx)
	Initialise a cursor with a custom iterator. More...
#define	fr_dcursor_reinit(_cursor, _head)
	re-initialise a cursor, changing its list More...
#define	FR_DCURSOR_REMOVE(_name)   _name ## _remove_t
	Expands to the type name used for the dcursor remove function type. More...
#define	VALIDATE(_item)   do { if (cursor->dlist->type && (_item)) _talloc_get_type_abort(_item, cursor->dlist->type, __location__); } while (0)

Typedefs
typedef void(*	fr_dcursor_copy_t) (fr_dcursor_t *out, fr_dcursor_t const *in)
	Copy callback for duplicating complex dcursor state. More...
typedef bool(*	fr_dcursor_eval_t) (void const *item, void const *uctx)
	Type of evaluation functions to pass to the fr_dcursor_filter_*() functions. More...
typedef int(*	fr_dcursor_insert_t) (fr_dlist_head_t *list, void *to_insert, void *uctx)
	Callback for performing additional actions on insert. More...
typedef void *(*	fr_dcursor_iter_t) (fr_dlist_head_t *list, void *to_eval, void *uctx)
	Callback for implementing custom iterators. More...
typedef int(*	fr_dcursor_remove_t) (fr_dlist_head_t *list, void *to_delete, void *uctx)
	Callback for performing additional actions on removal. More...
typedef struct fr_dcursor_s	fr_dcursor_t

Functions
static void *	_fr_dcursor_init (fr_dcursor_t *cursor, fr_dlist_head_t const *head, fr_dcursor_iter_t iter, fr_dcursor_iter_t peek, void const *iter_uctx, fr_dcursor_insert_t insert, fr_dcursor_remove_t remove, void const *mod_uctx, bool is_const)
	Setup a cursor to iterate over attribute items in dlists. More...
static void	_fr_dcursor_list_reinit (fr_dcursor_t *cursor, fr_dlist_head_t const *head, bool is_const)
static void *	dcursor_current_set (fr_dcursor_t *cursor, void *current)
	If current is set to a NULL pointer, we record that fact. More...
static void *	dcursor_next (fr_dcursor_t *cursor, fr_dcursor_iter_t iter, void *current)
	Internal function to get the next item. More...
static int	fr_dcursor_append (fr_dcursor_t *cursor, void *v)
	Insert a single item at the end of the list. More...
static void	fr_dcursor_copy (fr_dcursor_t *out, fr_dcursor_t const *in)
	Copy cursor parameters and state. More...
static void	fr_dcursor_copy_iter (fr_dcursor_t *out, fr_dcursor_t const *in)
	Copy a read-only iterator from a parent to a child cursor. More...
static void *	fr_dcursor_current (fr_dcursor_t *cursor)
	Return the item the cursor current points to. More...
static void *	fr_dcursor_filter_current (fr_dcursor_t *cursor, fr_dcursor_eval_t eval, void const *uctx)
	Return the next item, starting with the current item, that satisfies an evaluation function. More...
static void *	fr_dcursor_filter_head (fr_dcursor_t *cursor, fr_dcursor_eval_t eval, void const *uctx)
	Return the first item that satisfies an evaluation function. More...
static void *	fr_dcursor_filter_next (fr_dcursor_t *cursor, fr_dcursor_eval_t eval, void const *uctx)
	Return the next item, skipping the current item, that satisfies an evaluation function. More...
static void	fr_dcursor_free_item (fr_dcursor_t *cursor)
	talloc_free the current item More...
static void	fr_dcursor_free_list (fr_dcursor_t *cursor)
	Free the current item and all items after it. More...
static void *	fr_dcursor_head (fr_dcursor_t *cursor)
	Rewind cursor to the start of the list. More...
static int	fr_dcursor_insert (fr_dcursor_t *cursor, void *v)
	Insert directly after the current item. More...
void *	fr_dcursor_intersect_head (fr_dcursor_t *a, fr_dcursor_t *b)
	Return the first item matching the iterator in cursor a and cursor b. More...
void *	fr_dcursor_intersect_next (fr_dcursor_t *a, fr_dcursor_t *b)
	Return the next item matching the iterator in cursor a and cursor b. More...
static void *	fr_dcursor_list_next_peek (fr_dcursor_t *cursor)
	Returns the next list item without advancing the cursor. More...
static void	fr_dcursor_merge (fr_dcursor_t *cursor, fr_dcursor_t *to_append)
	Moves items from one cursor to another. More...
static void *	fr_dcursor_next (fr_dcursor_t *cursor)
	Advanced the cursor to the next item. More...
static void *	fr_dcursor_next_peek (fr_dcursor_t *cursor)
	Return the next iterator item without advancing the cursor. More...
static int	fr_dcursor_prepend (fr_dcursor_t *cursor, void *v)
	Insert a single item at the start of the list. More...
static void *	fr_dcursor_remove (fr_dcursor_t *cursor)
	Remove the current item. More...
static void *	fr_dcursor_replace (fr_dcursor_t *cursor, void *r)
	Replace the current item. More...
static void *	fr_dcursor_set_current (fr_dcursor_t *cursor, void *item)
	Set the cursor to a specified item. More...
static fr_dcursor_stack_t *	fr_dcursor_stack_alloc (TALLOC_CTX *ctx, uint8_t depth)
	Allocate a stack of cursors for traversing trees. More...
static void *	fr_dcursor_tail (fr_dcursor_t *cursor)
	Wind cursor to the tail item in the list. More...

Detailed Description

Functions to iterate over a sets and subsets of items stored in dlists.

Copyright

2020 The FreeRADIUS server project

Definition in file dcursor.h.

---

Data Structure Documentation

fr_dcursor_s

struct fr_dcursor_s

Definition at line 93 of file dcursor.h.

Collaboration diagram for fr_dcursor_s:

Data Fields
bool	at_end	We're at the end of the list.
fr_dcursor_copy_t	copy	Copy dcursor state.
void *	current	The current item in the dlist.
fr_dlist_head_t *	dlist	Head of the doubly linked list being iterated over.
fr_dcursor_insert_t	insert	Callback function on insert.
bool	is_const	The list we're iterating over is immutable.
fr_dcursor_iter_t	iter	Iterator function.
void *	iter_uctx	to pass to iterator function.
void *	mod_uctx	to pass to modification functions.
fr_dcursor_iter_t	peek	Distinct "peek" function. This is sometimes necessary for iterators with complex state.
fr_dcursor_remove_t	remove	Callback function on delete.

fr_dcursor_stack_t

struct fr_dcursor_stack_t

Definition at line 112 of file dcursor.h.

Collaboration diagram for fr_dcursor_stack_t:

Data Fields
fr_dcursor_t	cursor[]	Stack of cursors.
uint8_t	depth	Which cursor is currently in use.

Macro Definition Documentation

FR_DCURSOR

#define FR_DCURSOR

(

_name

)

_name ## _dcursor_t

Expands to the type name used for the dcursor wrapper structure.

Parameters

[in]

_name

Prefix we add to type-specific structures.

Returns

<name>_dcursor_t

Definition at line 839 of file dcursor.h.

FR_DCURSOR_COPY

#define FR_DCURSOR_COPY

(

_name

)

_name ## _copy_t

Expands to the type name used for the dcursor copy function type.

Parameters

[in]

_name

Prefix we add to type-specific structures.

Returns

<name>_copy_t

Definition at line 874 of file dcursor.h.

FR_DCURSOR_DLIST_TYPES

#define FR_DCURSOR_DLIST_TYPES	(		_name,
			_list_name,
			_element_type
	)

Value:

        typedef struct { fr_dcursor_t dcursor; } FR_DCURSOR(_name); \
        typedef _element_type *(*FR_DCURSOR_ITER(_name))(FR_DLIST_HEAD(_list_name) *list, _element_type *to_eval, void *uctx); \
        typedef bool (*FR_DCURSOR_EVAL(_name))(_element_type const *item, void const *uctx); \
        typedef int (*FR_DCURSOR_INSERT(_name))(FR_DLIST_HEAD(_list_name) *list, FR_DLIST_ENTRY(_list_name) *to_insert, void *uctx); \
        typedef int (*FR_DCURSOR_REMOVE(_name))(FR_DLIST_HEAD(_list_name) *list, FR_DLIST_ENTRY(_list_name) *to_delete, void *uctx); \
        typedef void (*FR_DCURSOR_COPY(_name))(FR_DCURSOR(_name) *out, FR_DCURSOR(_name) const *in);

Define type specific wrapper structs for dcursors.

Parameters

[in]	_name	Prefix we add to type-specific structures.
[in]	_list_name	The identifier used for type qualifying dlists. Should be the same as that use for FR_DLIST_HEAD FR_DLIST_ENTRY FR_DLIST_TYPES FR_DLIST_FUNCS
[in]	_element_type	Type of element in the dlists.

Note

This macro should be used inside the header for the area of code which will use type specific functions.

Definition at line 890 of file dcursor.h.

FR_DCURSOR_EVAL

#define FR_DCURSOR_EVAL

(

_name

)

_name ## _eval_t

Expands to the type name used for the dcursor evaluator type.

Parameters

[in]

_name

Prefix we add to type-specific structures.

Returns

<name>_eval_t

Definition at line 853 of file dcursor.h.

FR_DCURSOR_FUNCS

#define FR_DCURSOR_FUNCS	(		_name,
			_list_name,
			_element_type
	)

Define type specific wrapper functions for dcursors.

Note

This macro should be used inside the source file that will use the type specific functions.

Parameters

[in]	_name	Prefix we add to type-specific dcursor functions.
[in]	_list_name	Prefix for type-specific dlist used by this dcursor.
[in]	_element_type	Type of structure that'll be inserted into the dlist and returned by the dcursor.

Definition at line 907 of file dcursor.h.

fr_dcursor_init

#define fr_dcursor_init	(		_cursor,
			_head
	)

Value:

        _fr_dcursor_init(_cursor, \
                         _head, \
                         NULL, \
                         NULL, \
                         NULL, \
                         NULL, \
                         NULL, \
                         NULL, \
                         IS_CONST(fr_dlist_head_t *, _head))

Initialise a cursor.

Parameters

[in]	_cursor	to initialise.
[in]	_head	of item list.

Returns

• NULL if _head does not point to any items.
• The first item in the list.

Definition at line 728 of file dcursor.h.

FR_DCURSOR_INSERT

#define FR_DCURSOR_INSERT

(

_name

)

_name ## _insert_t

Expands to the type name used for the dcursor insert function type.

Parameters

[in]

_name

Prefix we add to type-specific structures.

Returns

<name>_insert_t

Definition at line 860 of file dcursor.h.

FR_DCURSOR_ITER

#define FR_DCURSOR_ITER

(

_name

)

_name ## _iter_t

Expands to the type name used for the dcursor iterator type.

Parameters

[in]

_name

Prefix we add to type-specific structures.

Returns

<name>_iter_t

Definition at line 846 of file dcursor.h.

fr_dcursor_iter_init

#define fr_dcursor_iter_init	(		_cursor,
			_head,
			_iter,
			_peek,
			_uctx
	)

Value:

        _fr_dcursor_init(_cursor, \
                         _head, \
                         _iter, \
                         _peek, \
                         _uctx, \
                         NULL, \
                         NULL, \
                         NULL, \
                         IS_CONST(fr_dlist_head_t *, _head))

Initialise a cursor with a custom iterator.

Parameters

[in]	_cursor	to initialise.
[in]	_head	of item list.
[in]	_iter	function.
[in]	_peek	function. If NULL _iter will be used for peeking.
[in]	_uctx	_iter function _uctx.

Returns

• NULL if _head does not point to any items, or the iterator matches no items in the current list.
• The first item returned by the iterator.

Definition at line 709 of file dcursor.h.

fr_dcursor_iter_mod_init

#define fr_dcursor_iter_mod_init	(		_cursor,
			_list,
			_iter,
			_peek,
			_iter_uctx,
			_insert,
			_remove,
			_mod_uctx
	)

Value:

        _fr_dcursor_init(_cursor, \
                         _list, \
                         _iter, \
                         _peek, \
                         _iter_uctx, \
                         _insert, \
                         _remove, \
                         _mod_uctx, \
                         IS_CONST(fr_dlist_head_t *, _list))

Initialise a cursor with a custom iterator.

Parameters

[in]	_cursor	to initialise.
[in]	_list	to iterate over.
[in]	_iter	function.
[in]	_peek	function. If NULL _iter will be used for peeking.
[in]	_iter_uctx	_iter function _uctx.
[in]	_insert	function.
[in]	_remove	function.
[in]	_mod_uctx	_insert and _remove function _uctx.

Returns

• NULL if _head does not point to any items, or the iterator matches no items in the current list.
• The first item returned by the iterator.

Definition at line 686 of file dcursor.h.

fr_dcursor_reinit

#define fr_dcursor_reinit	(		_cursor,
			_head
	)

Value:

        _fr_dcursor_reinit(_cursor, \
                           _head, \
                           IS_CONST(fr_dlist_head_t *, _head))

re-initialise a cursor, changing its list

Parameters

[in]	_cursor	to re-initialise.
[in]	_head	of item list.

Returns

• NULL if _head does not point to any items.
• The first item in the list.

Definition at line 784 of file dcursor.h.

FR_DCURSOR_REMOVE

#define FR_DCURSOR_REMOVE

(

_name

)

_name ## _remove_t

Expands to the type name used for the dcursor remove function type.

Parameters

[in]

_name

Prefix we add to type-specific structures.

Returns

<name>_remove_t

Definition at line 867 of file dcursor.h.

VALIDATE

#define VALIDATE

(

_item

)

do { if (cursor->dlist->type && (_item)) _talloc_get_type_abort(_item, cursor->dlist->type, __location__); } while (0)

Definition at line 118 of file dcursor.h.

Typedef Documentation

fr_dcursor_copy_t

typedef void(* fr_dcursor_copy_t) (fr_dcursor_t *out, fr_dcursor_t const *in)

Copy callback for duplicating complex dcursor state.

Parameters

[out]	out	dcursor to copy to.
[in]	in	dcursor to copy from.

Definition at line 81 of file dcursor.h.

fr_dcursor_eval_t

typedef bool(* fr_dcursor_eval_t) (void const *item, void const *uctx)

Type of evaluation functions to pass to the fr_dcursor_filter_*() functions.

Parameters

[in]	item	the item to be evaluated
[in]	uctx	context that may assist with evaluation

Returns

• true if the evaluation function is satisfied.
• false if the evaluation function is not satisfied.

Definition at line 91 of file dcursor.h.

fr_dcursor_insert_t

typedef int(* fr_dcursor_insert_t) (fr_dlist_head_t *list, void *to_insert, void *uctx)

Callback for performing additional actions on insert.

Parameters

[in]	list	head of the dlist.
[in]	to_insert	The item being inserted into the cursor.
[in]	uctx	passed to fr_dcursor_init.

Returns

• 0 on success.
• -1 on failure.

Definition at line 62 of file dcursor.h.

fr_dcursor_iter_t

typedef void*(* fr_dcursor_iter_t) (fr_dlist_head_t *list, void *to_eval, void *uctx)

Callback for implementing custom iterators.

Parameters

[in]	list	head of the dlist.
[in]	to_eval	the next item in the list. Iterator should check to see if it matches the iterator's filter, and if it doesn't iterate over the items until one is found that does.
[in]	uctx	passed to fr_dcursor_init.

Returns

• to_eval if to_eval matched, or a subsequent attribute if that matched.
• NULL if no more matching attributes were found.

Definition at line 51 of file dcursor.h.

fr_dcursor_remove_t

typedef int(* fr_dcursor_remove_t) (fr_dlist_head_t *list, void *to_delete, void *uctx)

Callback for performing additional actions on removal.

Parameters

[in]	list	head of the dlist.
[in]	to_delete	The item being removed from the cursor.
[in]	uctx	passed to fr_dcursor_init.

Returns

• 0 on success if the caller should do the list removal.
• 1 on success if the callback has done the list removal.
• -1 on failure.

Definition at line 74 of file dcursor.h.

fr_dcursor_t

typedef struct fr_dcursor_s fr_dcursor_t

Definition at line 1 of file dcursor.h.

Function Documentation

_fr_dcursor_init()

static void* _fr_dcursor_init ( fr_dcursor_t *  cursor, fr_dlist_head_t const *  head, fr_dcursor_iter_t  iter, fr_dcursor_iter_t  peek, void const *  iter_uctx, fr_dcursor_insert_t  insert, fr_dcursor_remove_t  remove, void const *  mod_uctx, bool  is_const  )

inlinestatic

Setup a cursor to iterate over attribute items in dlists.

Parameters

[in]	cursor	Where to initialise the cursor (uses existing structure).
[in]	head	of dlist.
[in]	iter	Iterator callback.
[in]	peek	Iterator callback that should not modify iterator state.
[in]	iter_uctx	to pass to iterator function.
[in]	insert	Callback for inserts.
[in]	remove	Callback for removals.
[in]	mod_uctx	to pass to modification functions.
[in]	is_const	Don't allow modification of the underlying list.

Returns

the attribute pointed to by v.

Definition at line 755 of file dcursor.h.

Here is the call graph for this function:

_fr_dcursor_list_reinit()

static void _fr_dcursor_list_reinit ( fr_dcursor_t *  cursor, fr_dlist_head_t const *  head, bool  is_const  )

inlinestatic

Definition at line 790 of file dcursor.h.

dcursor_current_set()

static void* dcursor_current_set ( fr_dcursor_t *  cursor, void *  current  )

inlinestatic

If current is set to a NULL pointer, we record that fact.

This stops us jumping back to the start of the dlist.

Definition at line 127 of file dcursor.h.

Here is the caller graph for this function:

dcursor_next()

static void* dcursor_next ( fr_dcursor_t *  cursor, fr_dcursor_iter_t  iter, void *  current  )

inlinestatic

Internal function to get the next item.

Parameters

[in]	cursor	to operate on.
[in]	iter	function.
[in]	current	attribute.

Returns

• The next attribute.
• NULL if no more attributes.

Definition at line 146 of file dcursor.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_dcursor_append()

static int fr_dcursor_append ( fr_dcursor_t *  cursor, void *  v  )

inlinestatic

Insert a single item at the end of the list.

Note

Does not change the current pointer.

Parameters

[in]	cursor	to operate on.
[in]	v	to insert.

Returns

• 0 on success.
• -1 if the insert callback failed or a modification was attempted on a const'd list.

Definition at line 405 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_copy()

static void fr_dcursor_copy ( fr_dcursor_t *  out, fr_dcursor_t const *  in  )

inlinestatic

Copy cursor parameters and state.

Parameters

[out]	out	Where to copy the cursor to.
[in]	in	cursor to copy.

Definition at line 191 of file dcursor.h.

fr_dcursor_copy_iter()

static void fr_dcursor_copy_iter ( fr_dcursor_t *  out, fr_dcursor_t const *  in  )

inlinestatic

Copy a read-only iterator from a parent to a child cursor.

Parameters

[out]	out	Where to copy the cursor to.
[in]	in	cursor to copy.

Definition at line 206 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_current()

static void* fr_dcursor_current ( fr_dcursor_t *  cursor )

inlinestatic

Return the item the cursor current points to.

Parameters

[in]

cursor

to operate on.

Returns

• The item the cursor currently points to.
• NULL if the list is empty, or the cursor has advanced past the end of the list.

Definition at line 336 of file dcursor.h.

fr_dcursor_filter_current()

static void* fr_dcursor_filter_current ( fr_dcursor_t *  cursor, fr_dcursor_eval_t  eval, void const *  uctx  )

inlinestatic

Return the next item, starting with the current item, that satisfies an evaluation function.

Parameters

[in]	cursor	to operate on
[in]	eval	evaluation function
[in]	uctx	context for the evaluation function

Returns

the next item satisfying eval, or NULL if no such item exists

Definition at line 582 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_filter_head()

static void* fr_dcursor_filter_head ( fr_dcursor_t *  cursor, fr_dcursor_eval_t  eval, void const *  uctx  )

inlinestatic

Return the first item that satisfies an evaluation function.

Parameters

[in]	cursor	to operate on
[in]	eval	evaluation function
[in]	uctx	context for the evaluation function

Returns

the first item satisfying eval, or NULL if no such item exists

Definition at line 563 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_filter_next()

static void* fr_dcursor_filter_next ( fr_dcursor_t *  cursor, fr_dcursor_eval_t  eval, void const *  uctx  )

inlinestatic

Return the next item, skipping the current item, that satisfies an evaluation function.

Parameters

[in]	cursor	to operate on
[in]	eval	evaluation function
[in]	uctx	context for the evaluation function

Returns

the next item satisfying eval, or NULL if no such item exists

Definition at line 543 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_free_item()

static void fr_dcursor_free_item ( fr_dcursor_t *  cursor )

inlinestatic

talloc_free the current item

Parameters

[in]

cursor

to free items from.

Definition at line 801 of file dcursor.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_dcursor_free_list()

static void fr_dcursor_free_list ( fr_dcursor_t *  cursor )

inlinestatic

Free the current item and all items after it.

Note

Use fr_dcursor_remove and talloc_free to free single items.

Current should be the item after the one freed.

Parameters

[in]

cursor

to free items in.

Definition at line 659 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_head()

static void* fr_dcursor_head ( fr_dcursor_t *  cursor )

inlinestatic

Rewind cursor to the start of the list.

Parameters

[in]

cursor

to operate on.

Returns

item at the start of the list.

Definition at line 233 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_insert()

static int fr_dcursor_insert ( fr_dcursor_t *  cursor, void *  v  )

inlinestatic

Insert directly after the current item.

Note

Does not change the current pointer.

Parameters

[in]	cursor	to operate on.
[in]	v	Item to insert.

Returns

• 0 on success.
• -1 if the insert callback failed or a modification was attempted on a const'd list.

Definition at line 434 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_intersect_head()

void* fr_dcursor_intersect_head	(	fr_dcursor_t *	a,
		fr_dcursor_t *	b
	)

Return the first item matching the iterator in cursor a and cursor b.

If a and b are not currently set to the same item, b will be reset, and wound to the item before a's current item.

Note

Both cursors must operate on the same list of items.

Parameters

[in]	a	First cursor.
[in]	b	Second cursor.

Returns

item at the start of the list.

Definition at line 47 of file dcursor.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_dcursor_intersect_next()

void* fr_dcursor_intersect_next	(	fr_dcursor_t *	a,
		fr_dcursor_t *	b
	)

Return the next item matching the iterator in cursor a and cursor b.

If a and b are not currently set to the same item, b will be reset, and wound to the item before a's current item.

The purpose of this function is to return items that match both iterators.

Note

Both cursors must operate on the same list of items.

Parameters

[in]	a	First cursor.
[in]	b	Second cursor.

Returns

next item in the list.

Definition at line 76 of file dcursor.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_dcursor_list_next_peek()

static void* fr_dcursor_list_next_peek ( fr_dcursor_t *  cursor )

inlinestatic

Returns the next list item without advancing the cursor.

Note

This returns the next item in the list, which may not match the next iterator value. It's mostly used for debugging. You probably want fr_dcursor_next_peek.

Parameters

[in]

cursor

to operator on.

Returns

• Next item in list.
• NULL if the list is empty, or the cursor has advanced past the end of the list.

Definition at line 321 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_merge()

static void fr_dcursor_merge ( fr_dcursor_t *  cursor, fr_dcursor_t *  to_append  )

inlinestatic

Moves items from one cursor to another.

Move multiple items from one cursor to another.

Note

Will only move items from the current position of to_append up to the end of to_append. Items will be removed from the original cursor. Items will be inserted after the current position of the destination cursor (which will not be changed).

Parameters

[in]	cursor	to operate on.
[in]	to_append	Items to append.

Definition at line 519 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_next()

static void* fr_dcursor_next ( fr_dcursor_t *  cursor )

inlinestatic

Advanced the cursor to the next item.

Parameters

[in]

cursor

to operate on.

Returns

• Next item.
• NULL if the list is empty, or the cursor has advanced past the end of the list.

Definition at line 287 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_next_peek()

static void* fr_dcursor_next_peek ( fr_dcursor_t *  cursor )

inlinestatic

Return the next iterator item without advancing the cursor.

Parameters

[in]

cursor

to operate on.

Returns

• Next item.
• NULL if the list is empty, or the cursor has advanced past the end of the list.

Definition at line 302 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_prepend()

static int fr_dcursor_prepend ( fr_dcursor_t *  cursor, void *  v  )

inlinestatic

Insert a single item at the start of the list.

Note

Will not advance cursor position to r attribute, but will set cursor to this attribute, if it's the head one in the list.

Insert a void at the start of the list.

Parameters

cursor	to operate on.
v	to insert.

Definition at line 375 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_remove()

static void* fr_dcursor_remove ( fr_dcursor_t *  cursor )

inlinestatic

Remove the current item.

The current item will be set to the one after the item being removed. An example check and remove loop:

for (v = fr_dcursor_init(&cursor, head);
     v;
     v = fr_dcursor_current(&cursor) {
     if (<condition>) {
         v = fr_dcursor_remove(&cursor);
         talloc_free(v);
         continue;
     }
     v = fr_dcursor_next(&cursor);
}

Parameters

[in]

cursor

to remove the current item from.

Returns

• item we just removed.
• NULL on error.

Definition at line 479 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_replace()

static void* fr_dcursor_replace ( fr_dcursor_t *  cursor, void *  r  )

inlinestatic

Replace the current item.

After replacing the current item, the cursor will be rewound, and the next item selected by the iterator function will become current.

Parameters

[in]	cursor	to replace the current item in.
[in]	r	item to insert.

Returns

• item we just replaced.
• NULL on error.

Definition at line 606 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_set_current()

static void* fr_dcursor_set_current ( fr_dcursor_t *  cursor, void *  item  )

inlinestatic

Set the cursor to a specified item.

Parameters

[in]	cursor	to operate on.
[in]	item	to point the cursor at

Returns

• item cursor points at.
• NULL if the list is empty.

Definition at line 352 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_stack_alloc()

static fr_dcursor_stack_t* fr_dcursor_stack_alloc ( TALLOC_CTX *  ctx, uint8_t  depth  )

inlinestatic

Allocate a stack of cursors for traversing trees.

Parameters

[in]	ctx	to allocate the cursor stack in.
[in]	depth	Maximum depth of the cursor stack.

Returns

• A new cursor stack.
• NULL on error.

Definition at line 816 of file dcursor.h.

Here is the call graph for this function:

fr_dcursor_tail()

static void* fr_dcursor_tail ( fr_dcursor_t *  cursor )

inlinestatic

Wind cursor to the tail item in the list.

Parameters

[in]

cursor

to operate on.

Returns

item at the end of the list.

Definition at line 258 of file dcursor.h.

Here is the call graph for this function: