Doubly-Linked List

Lightweight intrusive doubly-linked list (dl_list_t) used by many internal subsystems.

Source code:

• gobj.h

• gobj.c

dl_add()¶

Adds an item to the end of a doubly linked list dl.

int dl_add(dl_list_t *dl, void *item);

Parameters

Returns

Returns 0 on success, or -1 if the item already has links.

Notes

The function checks if the item already has links before adding it to the list.

dl_delete()¶

Removes a specified item from a doubly linked list and optionally frees its memory.

int dl_delete(
    dl_list_t *dl,
    void *curr_,
    void (*fnfree)(void *)
);

Parameters

Returns

Returns 0 on success, or -1 if an error occurs (e.g., null item, empty list, or item not found).

Notes

The function ensures that the list remains consistent after deletion. If fnfree is provided, it is called to free the memory of the removed item.

dl_find()¶

dl_find() searches for an item in a doubly linked list and returns a pointer to the item if found.

void *dl_find(
    dl_list_t *dl,
    void *item
);

Parameters

Returns

Returns a pointer to the item if found, otherwise returns NULL.

Notes

This function performs a linear search through the list and returns the first matching item.

dl_flush()¶

Removes all items from the given double-linked list and optionally frees them using the provided function.

void dl_flush(
    dl_list_t *dl,
    void (*fnfree)(void *)
);

Parameters

Returns

None.

Notes

Ensures that the list is completely emptied. If fnfree is provided, it is called for each item before removal.

dl_init()¶

Initializes a double-linked list structure by setting its head, tail, and item count to zero.

int dl_init(
    dl_list_t *dl,
    hgobj      gobj
);

Parameters

Returns

Returns 0 on successful initialization.

Notes

This function ensures that the list is empty before initialization. If the list is not empty, an error message is logged.

dl_insert()¶

Inserts an item at the head of a doubly linked list dl.

int dl_insert(
    dl_list_t *dl,
    void      *item
);

Parameters

Returns

Returns 0 on success, or -1 if the item already has links and cannot be inserted.

Notes

The function checks if the item already has links before inserting it. If the list is empty, the item becomes both the head and tail.

dl_delete_item()¶

Removes an item from its doubly linked list and optionally frees it. Unlike dl_delete(), this function does not require passing the list pointer -- it uses the item’s internal back-reference to its owning list.

int dl_delete_item(
    void *curr,
    void (*fnfree)(void *)
);

Parameters

Returns

Returns 0 on success, or -1 if curr is NULL or the item has no links (is not currently in a list).

Notes

The function delegates to dl_delete() using the item’s internally stored list pointer. After removal, the item’s link pointers are cleared. If fnfree is provided, it is called on the item after unlinking.

dl_nfind()¶

Finds and returns the Nth item in a doubly linked list, using 1-based indexing.

void * dl_nfind(
    dl_list_t *dl,
    size_t nitem
);

Parameters

Returns

Returns a pointer to the item at position nitem, or NULL if nitem is 0 or exceeds the number of items in the list.

Notes

The function traverses the list from the head. Position 1 returns the first item, position 2 the second, and so on.