logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

insque.3p (5821B)


  1. '\" et
  2. .TH INSQUE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. insque,
  12. remque
  13. \(em insert or remove an element in a queue
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <search.h>
  18. .P
  19. void insque(void *\fIelement\fP, void *\fIpred\fP);
  20. void remque(void *\fIelement\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIinsque\fR()
  25. and
  26. \fIremque\fR()
  27. functions shall manipulate queues built from doubly-linked lists.
  28. The queue can be either circular or linear. An application using
  29. \fIinsque\fR()
  30. or
  31. \fIremque\fR()
  32. shall ensure it defines a structure in which the first two members of
  33. the structure are pointers to the same type of structure, and any
  34. further members are application-specific. The first member of the
  35. structure is a forward pointer to the next entry in the queue. The
  36. second member is a backward pointer to the previous entry in the queue.
  37. If the queue is linear, the queue is terminated with null pointers. The
  38. names of the structure and of the pointer members are not subject to
  39. any special restriction.
  40. .P
  41. The
  42. \fIinsque\fR()
  43. function shall insert the element pointed to by
  44. .IR element
  45. into a queue immediately after the element pointed to by
  46. .IR pred .
  47. .P
  48. The
  49. \fIremque\fR()
  50. function shall remove the element pointed to by
  51. .IR element
  52. from a queue.
  53. .P
  54. If the queue is to be used as a linear list, invoking
  55. \fIinsque\fP(&\fIelement\fP, NULL), where
  56. .IR element
  57. is the initial element of the queue, shall initialize the forward
  58. and backward pointers of
  59. .IR element
  60. to null pointers.
  61. .P
  62. If the queue is to be used as a circular list, the application shall
  63. ensure it initializes the forward pointer and the backward pointer of
  64. the initial element of the queue to the element's own address.
  65. .SH "RETURN VALUE"
  66. The
  67. \fIinsque\fR()
  68. and
  69. \fIremque\fR()
  70. functions do not return a value.
  71. .SH ERRORS
  72. No errors are defined.
  73. .LP
  74. .IR "The following sections are informative."
  75. .SH EXAMPLES
  76. .SS "Creating a Linear Linked List"
  77. .P
  78. The following example creates a linear linked list.
  79. .sp
  80. .RS 4
  81. .nf
  82. #include <search.h>
  83. \&...
  84. struct myque element1;
  85. struct myque element2;
  86. .P
  87. char *data1 = "DATA1";
  88. char *data2 = "DATA2";
  89. \&...
  90. element1.data = data1;
  91. element2.data = data2;
  92. .P
  93. insque (&element1, NULL);
  94. insque (&element2, &element1);
  95. .fi
  96. .P
  97. .RE
  98. .SS "Creating a Circular Linked List"
  99. .P
  100. The following example creates a circular linked list.
  101. .sp
  102. .RS 4
  103. .nf
  104. #include <search.h>
  105. \&...
  106. struct myque element1;
  107. struct myque element2;
  108. .P
  109. char *data1 = "DATA1";
  110. char *data2 = "DATA2";
  111. \&...
  112. element1.data = data1;
  113. element2.data = data2;
  114. .P
  115. element1.fwd = &element1;
  116. element1.bck = &element1;
  117. .P
  118. insque (&element2, &element1);
  119. .fi
  120. .P
  121. .RE
  122. .SS "Removing an Element"
  123. .P
  124. The following example removes the element pointed to by
  125. .IR element1 .
  126. .sp
  127. .RS 4
  128. .nf
  129. #include <search.h>
  130. \&...
  131. struct myque element1;
  132. \&...
  133. remque (&element1);
  134. .fi
  135. .P
  136. .RE
  137. .SH "APPLICATION USAGE"
  138. The historical implementations of these functions described the
  139. arguments as being of type
  140. .BR "struct qelem *"
  141. rather than as being of type
  142. .BR "void *"
  143. as defined here. In those implementations,
  144. .BR "struct qelem"
  145. was commonly defined in
  146. .IR <search.h>
  147. as:
  148. .sp
  149. .RS 4
  150. .nf
  151. struct qelem {
  152. struct qelem *q_forw;
  153. struct qelem *q_back;
  154. };
  155. .fi
  156. .P
  157. .RE
  158. .P
  159. Applications using these functions, however, were never able to use
  160. this structure directly since it provided no room for the actual data
  161. contained in the elements. Most applications defined structures that
  162. contained the two pointers as the initial elements and also provided
  163. space for, or pointers to, the object's data. Applications that used
  164. these functions to update more than one type of table also had the
  165. problem of specifying two or more different structures with the same
  166. name, if they literally used
  167. .BR "struct qelem"
  168. as specified.
  169. .P
  170. As described here, the implementations were actually expecting a
  171. structure type where the first two members were forward and backward
  172. pointers to structures. With C compilers that didn't provide function
  173. prototypes, applications used structures as specified in the
  174. DESCRIPTION above and the compiler did what the application expected.
  175. .P
  176. If this method had been carried forward with an ISO\ C standard compiler and the
  177. historical function prototype, most applications would have to be
  178. modified to cast pointers to the structures actually used to be
  179. pointers to
  180. .BR "struct qelem"
  181. to avoid compilation warnings. By specifying
  182. .BR "void *"
  183. as the argument type, applications do not need to change (unless
  184. they specifically referenced
  185. .BR "struct qelem"
  186. and depended on it being defined in
  187. .IR <search.h> ).
  188. .SH RATIONALE
  189. None.
  190. .SH "FUTURE DIRECTIONS"
  191. None.
  192. .SH "SEE ALSO"
  193. The Base Definitions volume of POSIX.1\(hy2017,
  194. .IR "\fB<search.h>\fP"
  195. .\"
  196. .SH COPYRIGHT
  197. Portions of this text are reprinted and reproduced in electronic form
  198. from IEEE Std 1003.1-2017, Standard for Information Technology
  199. -- Portable Operating System Interface (POSIX), The Open Group Base
  200. Specifications Issue 7, 2018 Edition,
  201. Copyright (C) 2018 by the Institute of
  202. Electrical and Electronics Engineers, Inc and The Open Group.
  203. In the event of any discrepancy between this version and the original IEEE and
  204. The Open Group Standard, the original IEEE and The Open Group Standard
  205. is the referee document. The original Standard can be obtained online at
  206. http://www.opengroup.org/unix/online.html .
  207. .PP
  208. Any typographical or formatting errors that appear
  209. in this page are most likely
  210. to have been introduced during the conversion of the source files to
  211. man page format. To report such errors, see
  212. https://www.kernel.org/doc/man-pages/reporting_bugs.html .