insque(3C)                                                       insque(3C)

NAME
     insque, remque - insert or remove an element in a queue

SYNOPSIS
     #include <search.h>

     void insque(void *element, void *pred);

     void remque(void *element);

DESCRIPTION
     The insque() and remque() functions manipulate queues built from
     doubly-linked lists. The queue can be either circular or linear. An
     application using insque() or remque() must define a structure in
     which the first two members of the structure are pointers to the same
     type of structure, and any further members are application-specific.
     The first member of the structure is a forward pointer to the next
     entry in the queue. The second member is a backward pointer to the
     previous entry in the queue. If the queue is linear, the queue is ter-
     minated with null pointers. The names of the structure and of the
     pointer members are not subject to any special restriction.

     The insque() function inserts the element pointed to by element into a
     queue immediately after the element pointed to by pred.

     The remque() function removes the element pointed to by element from a
     queue.

     If the queue is to be used as a linear list, invoking insque(&element,
     NULL), where element is the initial element of the queue, will ini-
     tialize the forward and backward pointers of element to null pointers.

     If the queue is to be used as a circular list, the application must
     initialize the forward pointer and the backward pointer of the initial
     element of the queue to the element's own address.

RETURN VALUE
     The insque() and remque() functions do not return a value.

APPLICATION USAGE
     The historical implementations of these functions described the argu-
     ments as being of type struct qelem * rather than as being of type
     void * as defined here. In those implementations, struct qelem was
     commonly defined in <search.h> as:

     struct qelem {
          struct qelem  *qforw;
          struct qelem  *qback;
     };






Page 1                       Reliant UNIX 5.44                Printed 11/98

insque(3C)                                                       insque(3C)

     Applications using these functions, however, were never able to use
     this structure directly since it provided no room for the actual data
     contained in the elements. Most applications defined structures that
     contained the two pointers as the initial elements and also provided
     space for, or pointers to, the object's data. Applications that used
     these functions to update more than one type of table also had the
     problem of specifying two or more different structures with the same
     name, if they literally used struct qelem as specified.

     As described here, the implementations were actually expecting a
     structure type where the first two members were forward and backward
     pointers to structures. With C compilers that didn't provide function
     prototypes, applications used structures as specified in the DESCRIP-
     TION above and the compiler did what the application expected.

     If this method had been carried forward with an ISO C compiler and the
     historical function prototype, most applications would have to be
     modified to cast pointers to the structures actually used to be
     pointers to struct qelem to avoid compilation warnings. By specifying
     void * as the argument type, applications won't need to change (unless
     they specifically referenced struct qelem and depended on it being
     defined in <search.h>).

SEE ALSO
     search(5).





























Page 2                       Reliant UNIX 5.44                Printed 11/98