CIRCLEQ_INSERT_HEAD(3)

1CIRCLEQ(3)                 Linux Programmer's Manual                CIRCLEQ(3)
2
3
4

NAME

6       CIRCLEQ_EMPTY,   CIRCLEQ_ENTRY,  CIRCLEQ_FIRST,  CIRCLEQ_FOREACH,  CIR‐
7       CLEQ_FOREACH_REVERSE,  CIRCLEQ_HEAD,   CIRCLEQ_HEAD_INITIALIZER,   CIR‐
8       CLEQ_INIT,   CIRCLEQ_INSERT_AFTER,  CIRCLEQ_INSERT_BEFORE,  CIRCLEQ_IN‐
9       SERT_HEAD, CIRCLEQ_INSERT_TAIL, CIRCLEQ_LAST,  CIRCLEQ_LOOP_NEXT,  CIR‐
10       CLEQ_LOOP_PREV,  CIRCLEQ_NEXT, CIRCLEQ_PREV, CIRCLEQ_REMOVE - implemen‐
11       tation of a doubly linked circular queue
12

SYNOPSIS

14       #include <sys/queue.h>
15
16       int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *head);
17
18       CIRCLEQ_ENTRY(TYPE);
19
20       struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *head);
21
22       CIRCLEQ_FOREACH(struct TYPE *var, CIRCLEQ_HEAD *head,
23                       CIRCLEQ_ENTRY NAME);
24
25       CIRCLEQ_FOREACH_REVERSE(struct TYPE *var, CIRCLEQ_HEAD *head,
26                       CIRCLEQ_ENTRY NAME);
27
28       CIRCLEQ_HEAD(HEADNAME, TYPE);
29
30       CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD head);
31
32       void CIRCLEQ_INIT(CIRCLEQ_HEAD *head);
33
34       void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *head, struct TYPE *listelm,
35                       struct TYPE *elm, CIRCLEQ_ENTRY NAME);
36
37       void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *head, struct TYPE *listelm,
38                       struct TYPE *elm, CIRCLEQ_ENTRY NAME);
39
40       void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *head, struct TYPE *elm,
41                       CIRCLEQ_ENTRY NAME);
42
43       void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *head, struct TYPE *elm,
44                       CIRCLEQ_ENTRY NAME);
45
46       struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *head);
47
48       void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *head, struct TYPE *elm,
49                       CIRCLEQ_ENTRY NAME);
50
51       void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *head, struct TYPE *elm,
52                       CIRCLEQ_ENTRY NAME);
53
54       struct TYPE *CIRCLEQ_NEXT(struct TYPE *elm, CIRCLEQ_ENTRY NAME);
55
56       struct TYPE *CIRCLEQ_PREV(struct TYPE *elm, CIRCLEQ_ENTRY NAME);
57
58       void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *head, struct TYPE *elm,
59                       CIRCLEQ_ENTRY NAME);
60

DESCRIPTION

62       These macros define and operate on doubly linked circular queues.
63
64       In the macro definitions, TYPE is the name of a user-defined structure,
65       that must contain a field of type CIRCLEQ_ENTRY, named NAME.  The argu‐
66       ment HEADNAME is the name of a user-defined structure that must be  de‐
67       clared using the macro CIRCLEQ_HEAD().
68
69       A circular queue is headed by a structure defined by the CIRCLEQ_HEAD()
70       macro.  This structure contains a pair of pointers, one  to  the  first
71       element  in the circular queue and the other to the last element in the
72       circular queue.  The elements are doubly linked so  that  an  arbitrary
73       element can be removed without traversing the circular queue.  New ele‐
74       ments can be added to the circular queue after an existing element, be‐
75       fore  an existing element, at the head of the circular queue, or at the
76       end of the circular queue.  A CIRCLEQ_HEAD  structure  is  declared  as
77       follows:
78
79           CIRCLEQ_HEAD(HEADNAME, TYPE) head;
80
81       where  struct  HEADNAME is the structure to be defined, and struct TYPE
82       is the type of the elements to be linked into the  circular  queue.   A
83       pointer to the head of the circular queue can later be declared as:
84
85           struct HEADNAME *headp;
86
87       (The names head and headp are user selectable.)
88
89       The  macro  CIRCLEQ_HEAD_INITIALIZER()  evaluates to an initializer for
90       the circular queue head.
91
92       The macro CIRCLEQ_EMPTY() evaluates to true if there are  no  items  on
93       the circular queue.
94
95       The  macro  CIRCLEQ_ENTRY() declares a structure that connects the ele‐
96       ments in the circular queue.
97
98       The macro CIRCLEQ_FIRST() returns the first item on the circular queue.
99
100       The macro CIRCLEQ_FOREACH() traverses the circular queue referenced  by
101       head  in  the forward direction, assigning each element in turn to var.
102       var is set to &head if the loop completes normally, or if there were no
103       elements.
104
105       The macro CIRCLEQ_FOREACH_REVERSE() traverses the circular queue refer‐
106       enced by head in the reverse direction, assigning each element in  turn
107       to var.
108
109       The  macro  CIRCLEQ_INIT() initializes the circular queue referenced by
110       head.
111
112       The macro CIRCLEQ_INSERT_HEAD() inserts the new element elm at the head
113       of the circular queue.
114
115       The  macro CIRCLEQ_INSERT_TAIL() inserts the new element elm at the end
116       of the circular queue.
117
118       The macro CIRCLEQ_INSERT_AFTER() inserts the new element elm after  the
119       element listelm.
120
121       The  macro  CIRCLEQ_INSERT_BEFORE()  inserts the new element elm before
122       the element listelm.
123
124       The macro CIRCLEQ_LAST() returns the last item on the circular queue.
125
126       The macro CIRCLEQ_NEXT() returns the next item on the  circular  queue,
127       or &head if this item is the last one.
128
129       The  macro  CIRCLEQ_PREV()  returns  the  previous item on the circular
130       queue, or &head if this item is the first one.
131
132       The macro CIRCLEQ_LOOP_NEXT() returns the next  item  on  the  circular
133       queue.  If elm is the last element on the circular queue, the first el‐
134       ement is returned.
135
136       The macro CIRCLEQ_LOOP_PREV() returns the previous item on the circular
137       queue.  If elm is the first element on the circular queue, the last el‐
138       ement is returned.
139
140       The macro CIRCLEQ_REMOVE() removes the element elm  from  the  circular
141       queue.
142

RETURN VALUE

144       CIRCLEQ_EMPTY()  returns nonzero if the queue is empty, and zero if the
145       queue contains at least one entry.
146
147       CIRCLEQ_FIRST(), CIRCLEQ_LAST(), CIRCLEQ_NEXT(), and CIRCLEQ_PREV() re‐
148       turn a pointer to the first, last, next or previous TYPE structure, re‐
149       spectively.
150
151       CIRCLEQ_HEAD_INITIALIZER() returns an initializer that can be  assigned
152       to the queue head.
153

CONFORMING TO

155       Not  in  POSIX.1,  POSIX.1-2001  or  POSIX.1-2008.  Present on the BSDs
156       (CIRCLEQ macros first appeared in 4.4BSD).
157

BUGS

159       The macros CIRCLEQ_FOREACH() and CIRCLEQ_FOREACH_REVERSE() don't  allow
160       var  to be removed or freed within the loop, as it would interfere with
161       the traversal.  The  macros  CIRCLEQ_FOREACH_SAFE()  and  CIRCLEQ_FORE‐
162       ACH_REVERSE_SAFE(),  which  are present on the BSDs but are not present
163       in glibc, fix this limitation by allowing var to safely be removed from
164       the  list  and  freed from within the loop without interfering with the
165       traversal.
166

EXAMPLES

168       #include <stddef.h>
169       #include <stdio.h>
170       #include <stdlib.h>
171       #include <sys/queue.h>
172
173       struct entry {
174           int data;
175           CIRCLEQ_ENTRY(entry) entries;           /* Queue. */
176       };
177
178       CIRCLEQ_HEAD(circlehead, entry);
179
180       int
181       main(void)
182       {
183           struct entry *n1, *n2, *n3, *np;
184           struct circlehead head;                 /* Queue head. */
185           int i;
186
187           CIRCLEQ_INIT(&head);                    /* Initialize the queue. */
188
189           n1 = malloc(sizeof(struct entry));      /* Insert at the head. */
190           CIRCLEQ_INSERT_HEAD(&head, n1, entries);
191
192           n1 = malloc(sizeof(struct entry));      /* Insert at the tail. */
193           CIRCLEQ_INSERT_TAIL(&head, n1, entries);
194
195           n2 = malloc(sizeof(struct entry));      /* Insert after. */
196           CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries);
197
198           n3 = malloc(sizeof(struct entry));      /* Insert before. */
199           CIRCLEQ_INSERT_BEFORE(&head, n2, n3, entries);
200
201           CIRCLEQ_REMOVE(&head, n2, entries);     /* Deletion. */
202           free(n2);
203                                                   /* Forward traversal. */
204           i = 0;
205           CIRCLEQ_FOREACH(np, &head, entries)
206               np->data = i++;
207                                                   /* Reverse traversal. */
208           CIRCLEQ_FOREACH_REVERSE(np, &head, entries)
209               printf("%i\n", np->data);
210                                                   /* Queue deletion. */
211           n1 = CIRCLEQ_FIRST(&head);
212           while (n1 != (void *)&head) {
213               n2 = CIRCLEQ_NEXT(n1, entries);
214               free(n1);
215               n1 = n2;
216           }
217           CIRCLEQ_INIT(&head);
218
219           exit(EXIT_SUCCESS);
220       }
221

COLOPHON

226       This page is part of release 5.10 of the Linux  man-pages  project.   A
227       description  of  the project, information about reporting bugs, and the
228       latest    version    of    this    page,    can     be     found     at
229       https://www.kernel.org/doc/man-pages/.
230
231
232
233GNU                               2020-10-21                        CIRCLEQ(3)