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