Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 248 insertions, 0 deletions

diff --git a/man/man3/insque.3 b/man/man3/insque.3
new file mode 100644
index 0000000..905d803
--- /dev/null
+++ b/man/man3/insque.3
@@ -0,0 +1,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 2024-05-02 "Linux man-pages (unreleased)"
+.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)