1=pod
2
3=head1 NAME
4
5DEFINE_LIST_OF, OSSL_LIST_MEMBER, OSSL_LIST,
6ossl_list_TYPE_init, ossl_list_TYPE_init_elem,
7ossl_list_TYPE_is_empty, ossl_list_TYPE_num,
8ossl_list_TYPE_head, ossl_list_TYPE_tail,
9ossl_list_TYPE_next, ossl_list_TYPE_prev,
10ossl_list_TYPE_remove, ossl_list_TYPE_insert_head, ossl_list_TYPE_insert_tail,
11ossl_list_TYPE_insert_before, ossl_list_TYPE_after
12- doubly linked list
13
14=head1 SYNOPSIS
15
16=for openssl generic
17
18 #include "internal/list.h"
19
20 OSSL_LIST(name);
21 OSSL_LIST_MEMBER(NAME, TYPE);
22 DEFINE_LIST_OF(NAME, TYPE);
23
24 void ossl_list_TYPE_init(OSSL_LIST(name) *list);
25 void ossl_list_TYPE_init_elem(type *elem);
26
27 int ossl_list_TYPE_is_empty(const OSSL_LIST(name) *list);
28 size_t ossl_list_TYPE_num(const OSSL_LIST(name) *list);
29 type *ossl_list_TYPE_head(const OSSL_LIST(name) *list);
30 type *ossl_list_TYPE_tail(const OSSL_LIST(name) *list);
31
32 type *ossl_list_TYPE_next(const type *elem);
33 type *ossl_list_TYPE_prev(const type *elem);
34
35 void ossl_list_TYPE_remove(OSSL_LIST(name) *list, type *elem);
36 void ossl_list_TYPE_insert_head(OSSL_LIST(name) *list, type *elem);
37 void ossl_list_TYPE_insert_tail(OSSL_LIST(name) *list, type *elem);
38 void ossl_list_TYPE_insert_before(OSSL_LIST(name) *list, type *existing,
39                                   type *elem);
40 void ossl_list_TYPE_insert_after(OSSL_LIST(name) *list, type *existing, type *elem);
41
42=head1 DESCRIPTION
43
44Create type safe linked list.  These macros define typesafe inline
45functions that implement the various list operations. In the description
46here, B<I<TYPE>> is used as a placeholder for any datatype.  Lists are intended to
47be incorporated into other structures and rather than being a standalone data
48structure.
49
50The OSSL_LIST() macro returns the name for a list of the specified
51B<I<TYPE>>.  This is a structure which should be treated as opaque.
52
53DEFINE_LIST_OF() creates a set of functions for a list of B<I<TYPE>>
54elements with the name B<I<TYPE>>.  The type is represented
55by B<OSSL_LIST>(B<I<TYPE>>) and each function name begins with
56B<ossl_list_I<TYPE>_>.  The list's linkages are stored in the
57B<OSSL_LIST_MEMBER>(B<I<TYPE>>, B<I<TYPE>>) field.
58
59B<ossl_list_I<TYPE>_init>() initialises the memory pointed to by I<list>
60to zero which creates an empty list.
61
62B<ossl_list_I<TYPE>_init_elem>() initialises the list related memory pointed
63to by I<elem> to zero which allows it to be used in lists.
64
65B<ossl_list_I<TYPE>_is_empty>() returns nonzero if I<list> has no elements and
66zero otherwise.
67
68B<ossl_list_I<TYPE>_num>() returns the number of elements in I<list>.
69
70B<ossl_list_I<TYPE>_head>() returns the first element in the I<list>
71or NULL if there are no elements.
72
73B<ossl_list_I<TYPE>_tail>() returns the last element in the I<list>
74or NULL if there are no elements.
75
76B<ossl_list_I<TYPE>_remove>() removes the specified element I<elem> from
77the I<list>.  It is illegal to remove an element that isn't in the list.
78
79B<ossl_list_I<TYPE>_insert_head>() inserts the element I<elem>, which
80must not be in the list, into the first position in the I<list>.
81
82B<ossl_list_I<TYPE>_insert_tail>() inserts the element I<elem>, which
83must not be in the list, into the last position in the I<list>.
84
85B<ossl_list_I<TYPE>_insert_before>() inserts the element I<elem>,
86which must not be in the list, into the I<list> immediately before the
87I<existing> element.
88
89B<ossl_list_I<TYPE>_insert_after>() inserts the element I<elem>,
90which must not be in the list, into the I<list> immediately after the
91I<existing> element.
92
93=head1 RETURN VALUES
94
95B<ossl_list_I<TYPE>_is_empty>() returns nonzero if the list is empty and zero
96otherwise.
97
98B<ossl_list_I<TYPE>_num>() returns the number of elements in the
99list.
100
101B<ossl_list_I<TYPE>_head>(), B<ossl_list_I<TYPE>_tail>(),
102B<ossl_list_I<TYPE>_next>() and B<ossl_list_I<TYPE>_prev>() return
103the specified element in the list.
104
105=head1 EXAMPLES
106
107 typedef struct item_st ITEM;
108
109 struct item_st {
110     ...
111     OSSL_LIST_MEMBER(new_items, ITEM);
112     ...
113 };
114
115 DEFINE_LIST_OF(new_items, ITEM);
116
117 OSSL_LIST(new_items) new;
118
119 ITEM *p;
120
121 for (p = ossl_list_new_items_head(&st->new); p != NULL;
122      p = ossl_list_new_items_next(p))
123     /* do something */
124
125=head1 HISTORY
126
127The functions described here were all added in OpenSSL 3.2.
128
129=head1 COPYRIGHT
130
131Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
132
133Licensed under the Apache License 2.0 (the "License").  You may not use
134this file except in compliance with the License.  You can obtain a copy
135in the file LICENSE in the source distribution or at
136L<https://www.openssl.org/source/license.html>.
137
138=cut
139