1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
'\" t
.\" peter memishian -- meem@gnu.ai.mit.edu
.\" $Id: insque.3,v 1.2 1996/10/30 21:03:39 meem Exp meem $
.\" and Copyright (c) 2010, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" References consulted:
.\" Linux libc source code (5.4.7)
.\" Solaris 2.x, OSF/1, and HP-UX manpages
.\" Curry's "UNIX Systems Programming for SVR4" (O'Reilly & Associates 1996)
.\"
.\" Changed to POSIX, 2003-08-11, aeb+wh
.\" mtk, 2010-09-09: Noted glibc 2.4 bug, added info on circular
.\" lists, added example program
.\"
.TH insque 3 2023-10-31 "Linux man-pages 6.06"
.SH NAME
insque, remque \- insert/remove an item from a queue
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <search.h>
.P
.BI "void insque(void *" elem ", void *" prev );
.BI "void remque(void *" elem );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR insque (),
.BR remque ():
.nf
_XOPEN_SOURCE >= 500
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE
.fi
.SH DESCRIPTION
The
.BR insque ()
and
.BR remque ()
functions manipulate doubly linked lists.
Each element in the list is a structure of
which the first two elements are a forward and a
backward pointer.
The linked list may be linear (i.e., NULL forward pointer at
the end of the list and NULL backward pointer at the start of the list)
or circular.
.P
The
.BR insque ()
function inserts the element pointed to by \fIelem\fP
immediately after the element pointed to by \fIprev\fP.
.P
If the list is linear, then the call
.I "insque(elem, NULL)"
can be used to insert the initial list element,
and the call sets the forward and backward pointers of
.I elem
to NULL.
.P
If the list is circular,
the caller should ensure that the forward and backward pointers of the
first element are initialized to point to that element,
and the
.I prev
argument of the
.BR insque ()
call should also point to the element.
.P
The
.BR remque ()
function removes the element pointed to by \fIelem\fP from the
doubly linked list.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface Attribute Value
T{
.na
.nh
.BR insque (),
.BR remque ()
T} Thread safety MT-Safe
.TE
.SH VERSIONS
On ancient systems,
.\" e.g., SunOS, Linux libc4 and libc5
the arguments of these functions were of type \fIstruct qelem *\fP,
defined as:
.P
.in +4n
.EX
struct qelem {
struct qelem *q_forw;
struct qelem *q_back;
char q_data[1];
};
.EE
.in
.P
This is still what you will get if
.B _GNU_SOURCE
is defined before
including \fI<search.h>\fP.
.P
The location of the prototypes for these functions differs among several
versions of UNIX.
The above is the POSIX version.
Some systems place them in \fI<string.h>\fP.
.\" Linux libc4 and libc 5 placed them
.\" in \fI<stdlib.h>\fP.
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
.SH BUGS
In glibc 2.4 and earlier, it was not possible to specify
.I prev
as NULL.
Consequently, to build a linear list, the caller had to build a list
using an initial call that contained the first two elements of the list,
with the forward and backward pointers in each element suitably initialized.
.SH EXAMPLES
The program below demonstrates the use of
.BR insque ().
Here is an example run of the program:
.P
.in +4n
.EX
.RB "$ " "./a.out \-c a b c"
Traversing completed list:
a
b
c
That was a circular list
.EE
.in
.SS Program source
\&
.\" SRC BEGIN (insque.c)
.EX
#include <search.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
\&
struct element {
struct element *forward;
struct element *backward;
char *name;
};
\&
static struct element *
new_element(void)
{
struct element *e;
\&
e = malloc(sizeof(*e));
if (e == NULL) {
fprintf(stderr, "malloc() failed\en");
exit(EXIT_FAILURE);
}
\&
return e;
}
\&
int
main(int argc, char *argv[])
{
struct element *first, *elem, *prev;
int circular, opt, errfnd;
\&
/* The "\-c" command\-line option can be used to specify that the
list is circular. */
\&
errfnd = 0;
circular = 0;
while ((opt = getopt(argc, argv, "c")) != \-1) {
switch (opt) {
case \[aq]c\[aq]:
circular = 1;
break;
default:
errfnd = 1;
break;
}
}
\&
if (errfnd || optind >= argc) {
fprintf(stderr, "Usage: %s [\-c] string...\en", argv[0]);
exit(EXIT_FAILURE);
}
\&
/* Create first element and place it in the linked list. */
\&
elem = new_element();
first = elem;
\&
elem\->name = argv[optind];
\&
if (circular) {
elem\->forward = elem;
elem\->backward = elem;
insque(elem, elem);
} else {
insque(elem, NULL);
}
\&
/* Add remaining command\-line arguments as list elements. */
\&
while (++optind < argc) {
prev = elem;
\&
elem = new_element();
elem\->name = argv[optind];
insque(elem, prev);
}
\&
/* Traverse the list from the start, printing element names. */
\&
printf("Traversing completed list:\en");
elem = first;
do {
printf(" %s\en", elem\->name);
elem = elem\->forward;
} while (elem != NULL && elem != first);
\&
if (elem == first)
printf("That was a circular list\en");
\&
exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH SEE ALSO
.BR queue (7)
|
