1INSQUE(3P) POSIX Programmer's Manual INSQUE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 insque, remque — insert or remove an element in a queue
13
15 #include <search.h>
16 void insque(void *element, void *pred);
18 void remque(void *element);
19
21 The insque() and remque() functions shall manipulate queues built from
22 doubly-linked lists. The queue can be either circular or linear. An
23 application using insque() or remque() shall ensure it defines a struc‐
24 ture in which the first two members of the structure are pointers to
25 the same type of structure, and any further members are application-
26 specific. The first member of the structure is a forward pointer to the
27 next entry in the queue. The second member is a backward pointer to the
28 previous entry in the queue. If the queue is linear, the queue is ter‐
29 minated with null pointers. The names of the structure and of the
30 pointer members are not subject to any special restriction.
31 The insque() function shall insert the element pointed to by element
33 into a queue immediately after the element pointed to by pred.
34 The remque() function shall remove the element pointed to by element
36 from a queue.
37 If the queue is to be used as a linear list, invoking insque(&element,
39 NULL), where element is the initial element of the queue, shall ini‐
40 tialize the forward and backward pointers of element to null pointers.
41 If the queue is to be used as a circular list, the application shall
43 ensure it initializes the forward pointer and the backward pointer of
44 the initial element of the queue to the element's own address.
45
47 The insque() and remque() functions do not return a value.
48
50 No errors are defined.
51 The following sections are informative.
53
55 Creating a Linear Linked List
56 The following example creates a linear linked list.
57 #include <search.h>
60 ...
61 struct myque element1;
62 struct myque element2;
63 char *data1 = "DATA1";
65 char *data2 = "DATA2";
66 ...
67 element1.data = data1;
68 element2.data = data2;
69 insque (&element1, NULL);
71 insque (&element2, &element1);
72 Creating a Circular Linked List
74 The following example creates a circular linked list.
75 #include <search.h>
78 ...
79 struct myque element1;
80 struct myque element2;
81 char *data1 = "DATA1";
83 char *data2 = "DATA2";
84 ...
85 element1.data = data1;
86 element2.data = data2;
87 element1.fwd = &element1;
89 element1.bck = &element1;
90 insque (&element2, &element1);
92 Removing an Element
94 The following example removes the element pointed to by element1.
95 #include <search.h>
98 ...
99 struct myque element1;
100 ...
101 remque (&element1);
102
104 The historical implementations of these functions described the argu‐
105 ments as being of type struct qelem * rather than as being of type void
106 * as defined here. In those implementations, struct qelem was commonly
107 defined in <search.h> as:
108 struct qelem {
111 struct qelem *q_forw;
112 struct qelem *q_back;
113 };
114 Applications using these functions, however, were never able to use
116 this structure directly since it provided no room for the actual data
117 contained in the elements. Most applications defined structures that
118 contained the two pointers as the initial elements and also provided
119 space for, or pointers to, the object's data. Applications that used
120 these functions to update more than one type of table also had the
121 problem of specifying two or more different structures with the same
122 name, if they literally used struct qelem as specified.
123 As described here, the implementations were actually expecting a struc‐
125 ture type where the first two members were forward and backward point‐
126 ers to structures. With C compilers that didn't provide function proto‐
127 types, applications used structures as specified in the DESCRIPTION
128 above and the compiler did what the application expected.
129 If this method had been carried forward with an ISO C standard compiler
131 and the historical function prototype, most applications would have to
132 be modified to cast pointers to the structures actually used to be
133 pointers to struct qelem to avoid compilation warnings. By specifying
134 void * as the argument type, applications do not need to change (unless
135 they specifically referenced struct qelem and depended on it being
136 defined in <search.h>).
137
139 None.
140
142 None.
143
145 The Base Definitions volume of POSIX.1‐2017, <search.h>
146
148 Portions of this text are reprinted and reproduced in electronic form
149 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
150 table Operating System Interface (POSIX), The Open Group Base Specifi‐
151 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
152 Electrical and Electronics Engineers, Inc and The Open Group. In the
153 event of any discrepancy between this version and the original IEEE and
154 The Open Group Standard, the original IEEE and The Open Group Standard
155 is the referee document. The original Standard can be obtained online
156 at http://www.opengroup.org/unix/online.html .
157 Any typographical or formatting errors that appear in this page are
159 most likely to have been introduced during the conversion of the source
160 files to man page format. To report such errors, see https://www.ker‐
161 nel.org/doc/man-pages/reporting_bugs.html .
162IEEE/The Open Group 2017 INSQUE(3P)