--- name: "wl_list" section: "3" platform: "linux" package: "wayland-docs" version: "1.26.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/wl_list" --- # wl\_list(3) Doubly-linked list. ## NAME wl\_list - Doubly-linked list. ## SYNOPSIS \#include \ ### Public Member Functions void **wl\_list\_init** (struct **wl\_list** \*list)\ void **wl\_list\_insert** (struct **wl\_list** \*list, struct **wl\_list** \*elm)\ void **wl\_list\_remove** (struct **wl\_list** \*elm)\ int **wl\_list\_length** (const struct **wl\_list** \*list)\ int **wl\_list\_empty** (const struct **wl\_list** \*list)\ void **wl\_list\_insert\_list** (struct **wl\_list** \*list, struct **wl\_list** \*other)\ ### Data Fields struct **wl\_list** \* **prev**\ struct **wl\_list** \* **next**\ ### Related Symbols (Note that these are not member symbols.) #define **wl\_list\_for\_each**(pos, head, member)\ \#define **wl\_list\_for\_each\_safe**(pos, tmp, head, member)\ \#define **wl\_list\_for\_each\_reverse**(pos, head, member)\ \#define **wl\_list\_for\_each\_reverse\_safe**(pos, tmp, head, member)\ ## Detailed Description Doubly-linked list. On its own, an instance of struct **wl\_list represents the sentinel head of a doubly-linked list, and must be initialized using wl\_list\_init(). When empty, the list head's next and prev members point to the list head itself, otherwise next references the first element in the list, and prev refers to the last element in the list.** **Use the** struct **wl\_list type to represent both the list head and the links between elements within the list. Use wl\_list\_empty() to determine if the list is empty in O(1).** **All elements in the list must be of the same type. The element type must have a** struct **wl\_list member, often named** link **by convention. Prior to insertion, there is no need to initialize an element's** link **- invoking wl\_list\_init() on an individual list element's** struct **wl\_list member is unnecessary if the very next operation is wl\_list\_insert(). However, a common idiom is to initialize an element's** link **prior to removal - ensure safety by invoking wl\_list\_init() before wl\_list\_remove().** **Consider a list reference** struct **wl\_list** foo\_list**, an element type as** struct element**, and an element's link member as** struct **wl\_list** link**.** **The following code initializes a list and adds three elements to it.** ``` struct wl_list foo_list; struct element { int foo; struct wl_list link; }; struct element e1, e2, e3; wl_list_init(&foo_list); wl_list_insert(&foo_list, &e1.link); // e1 is the first element wl_list_insert(&foo_list, &e2.link); // e2 is now the first element wl_list_insert(&e2.link, &e3.link); // insert e3 after e2 ``` **The list now looks like** *\[e2, e3, e1\]***.** **The wl\_list API provides some iterator macros. For example, to iterate a list in ascending order:** ``` struct element *e; wl_list_for_each(e, foo_list, link) { do_something_with_element(e); } ``` **See the documentation of each iterator for details.** **See also** **http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h** ## Member Function Documentation ### int wl\_list\_empty (const struct wl\_list \* list) **Determines if the list is empty.** **Parameters** *list* **List whose emptiness is to be determined** **Returns** **1 if empty, or 0 if not empty** ### void wl\_list\_init (struct wl\_list \* list) **Initializes the list.** **Parameters** *list* **List to initialize** ### void wl\_list\_insert (struct wl\_list \* list, struct wl\_list \* elm) **Inserts an element into the list, after the element represented by** list**. When** list **is a reference to the list itself (the head), set the containing struct of** elm **as the first element in the list.** **Note** **If** elm **is already part of a list, inserting it again will lead to list corruption.** **Parameters** *list* **List element after which the new element is inserted** \ *elm* **Link of the containing struct to insert into the list** ### void wl\_list\_insert\_list (struct wl\_list \* list, struct wl\_list \* other) **Inserts all of the elements of one list into another, after the element represented by** list**.** **Note** **This leaves** other **in an invalid state.** **Parameters** *list* **List element after which the other list elements will be inserted** \ *other* **List of elements to insert** ### int wl\_list\_length (const struct wl\_list \* list) **Determines the length of the list.** **Note** **This is an O(n) operation.** **Parameters** *list* **List whose length is to be determined** **Returns** **Number of elements in the list** ### void wl\_list\_remove (struct wl\_list \* elm) **Removes an element from the list.** **Note** **This operation leaves** elm **in an invalid state.** **Parameters** *elm* **Link of the containing struct to remove from the list** ## Friends And Related Symbol Documentation ### #define wl\_list\_for\_each( pos, head, member) \[related\] **Value:** ``` for (pos = wl_container_of((head)->next, pos, member); \ &pos->member != (head); \ pos = wl_container_of(pos->member.next, pos, member)) ``` **Iterates over a list.** **This macro expresses a for-each iterator for wl\_list. Given a list and wl\_list link member name (often named** link **by convention), this macro assigns each element in the list to** pos**, which can then be referenced in a trailing code block. For example, given a wl\_list of** struct message **elements:** ``` struct message { char *contents; wl_list link; }; struct wl_list *message_list; // Assume message_list now "contains" many messages struct message *m; wl_list_for_each(m, message_list, link) { do_something_with_message(m); } ``` **Parameters** *pos* **Cursor that each list element will be assigned to** \ *head* **Head of the list to iterate over** \ *member* **Name of the link member within the element struct** ### #define wl\_list\_for\_each\_reverse( pos, head, member) \[related\] **Value:** ``` for (pos = wl_container_of((head)->prev, pos, member); \ &pos->member != (head); \ pos = wl_container_of(pos->member.prev, pos, member)) ``` **Iterates backwards over a list.** **See also** **wl\_list\_for\_each()** **Parameters** *pos* **Cursor that each list element will be assigned to** \ *head* **Head of the list to iterate over** \ *member* **Name of the link member within the element struct** ### #define wl\_list\_for\_each\_reverse\_safe( pos, tmp, head, member) \[related\] **Value:** ``` for (pos = wl_container_of((head)->prev, pos, member), \ tmp = wl_container_of((pos)->member.prev, tmp, member); \ &pos->member != (head); \ pos = tmp, \ tmp = wl_container_of(pos->member.prev, tmp, member)) ``` **Iterates backwards over a list, safe against removal of the list element.** **Note** **Only removal of the current element,** pos**, is safe. Removing any other element during traversal may lead to a loop malfunction.** **See also** **wl\_list\_for\_each()** **Parameters** *pos* **Cursor that each list element will be assigned to** \ *tmp* **Temporary pointer of the same type as** pos \ *head* **Head of the list to iterate over** \ *member* **Name of the link member within the element struct** ### #define wl\_list\_for\_each\_safe( pos, tmp, head, member) \[related\] **Value:** ``` for (pos = wl_container_of((head)->next, pos, member), \ tmp = wl_container_of((pos)->member.next, tmp, member); \ &pos->member != (head); \ pos = tmp, \ tmp = wl_container_of(pos->member.next, tmp, member)) ``` **Iterates over a list, safe against removal of the list element.** **Note** **Only removal of the current element,** pos**, is safe. Removing any other element during traversal may lead to a loop malfunction.** **See also** **wl\_list\_for\_each()** **Parameters** *pos* **Cursor that each list element will be assigned to** \ *tmp* **Temporary pointer of the same type as** pos \ *head* **Head of the list to iterate over** \ *member* **Name of the link member within the element struct** ## Field Documentation ### struct wl\_list\* wl\_list::next **Next list element** ### struct wl\_list\* wl\_list::prev **Previous list element** ## Author **Generated automatically by Doxygen for Wayland from the source code.**