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
13 insque, remque — insert or remove an element in a queue
14
16 #include <search.h>
17 void insque(void *element, void *pred);
19 void remque(void *element);
20
22 The insque() and remque() functions shall manipulate queues built from
23 doubly-linked lists. The queue can be either circular or linear. An
24 application using insque() or remque() shall ensure it defines a struc‐
25 ture in which the first two members of the structure are pointers to
26 the same type of structure, and any further members are application-
27 specific. The first member of the structure is a forward pointer to the
28 next entry in the queue. The second member is a backward pointer to the
29 previous entry in the queue. If the queue is linear, the queue is ter‐
30 minated with null pointers. The names of the structure and of the
31 pointer members are not subject to any special restriction.
32 The insque() function shall insert the element pointed to by element
34 into a queue immediately after the element pointed to by pred.
35 The remque() function shall remove the element pointed to by element
37 from a queue.
38 If the queue is to be used as a linear list, invoking insque(&element,
40 NULL), where element is the initial element of the queue, shall ini‐
41 tialize the forward and backward pointers of element to null pointers.
42 If the queue is to be used as a circular list, the application shall
44 ensure it initializes the forward pointer and the backward pointer of
45 the initial element of the queue to the element's own address.
46
48 The insque() and remque() functions do not return a value.
49
51 No errors are defined.
52 The following sections are informative.
54
56 Creating a Linear Linked List
57 The following example creates a linear linked list.
58 #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>
77 ...
78 struct myque element1;
79 struct myque element2;
80 char *data1 = "DATA1";
82 char *data2 = "DATA2";
83 ...
84 element1.data = data1;
85 element2.data = data2;
86 element1.fwd = &element1;
88 element1.bck = &element1;
89 insque (&element2, &element1);
91 Removing an Element
93 The following example removes the element pointed to by element1.
94 #include <search.h>
96 ...
97 struct myque element1;
98 ...
99 remque (&element1);
100
102 The historical implementations of these functions described the argu‐
103 ments as being of type struct qelem * rather than as being of type void
104 * as defined here. In those implementations, struct qelem was commonly
105 defined in <search.h> as:
106 struct qelem {
108 struct qelem *q_forw;
109 struct qelem *q_back;
110 };
111 Applications using these functions, however, were never able to use
113 this structure directly since it provided no room for the actual data
114 contained in the elements. Most applications defined structures that
115 contained the two pointers as the initial elements and also provided
116 space for, or pointers to, the object's data. Applications that used
117 these functions to update more than one type of table also had the
118 problem of specifying two or more different structures with the same
119 name, if they literally used struct qelem as specified.
120 As described here, the implementations were actually expecting a struc‐
122 ture type where the first two members were forward and backward point‐
123 ers to structures. With C compilers that didn't provide function proto‐
124 types, applications used structures as specified in the DESCRIPTION
125 above and the compiler did what the application expected.
126 If this method had been carried forward with an ISO C standard compiler
128 and the historical function prototype, most applications would have to
129 be modified to cast pointers to the structures actually used to be
130 pointers to struct qelem to avoid compilation warnings. By specifying
131 void * as the argument type, applications do not need to change (unless
132 they specifically referenced struct qelem and depended on it being
133 defined in <search.h>).
134
136 None.
137
139 None.
140
142 The Base Definitions volume of POSIX.1‐2008, <search.h>
143
145 Portions of this text are reprinted and reproduced in electronic form
146 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
147 -- Portable Operating System Interface (POSIX), The Open Group Base
148 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
149 cal and Electronics Engineers, Inc and The Open Group. (This is
150 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
151 event of any discrepancy between this version and the original IEEE and
152 The Open Group Standard, the original IEEE and The Open Group Standard
153 is the referee document. The original Standard can be obtained online
154 at http://www.unix.org/online.html .
155 Any typographical or formatting errors that appear in this page are
157 most likely to have been introduced during the conversion of the source
158 files to man page format. To report such errors, see https://www.ker‐
159 nel.org/doc/man-pages/reporting_bugs.html .
160IEEE/The Open Group 2013 INSQUE(3P)