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

getmsg.3p (10985B)


  1. '\" et
  2. .TH GETMSG "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. getmsg,
  12. getpmsg
  13. \(em receive next message from a STREAMS file (\fBSTREAMS\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <stropts.h>
  18. .P
  19. int getmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,
  20. struct strbuf *restrict \fIdataptr\fP, int *restrict \fIflagsp\fP);
  21. int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,
  22. struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP,
  23. int *restrict \fIflagsp\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIgetmsg\fR()
  28. function shall retrieve the contents of a message located at the head
  29. of the STREAM head read queue associated with a STREAMS file and place
  30. the contents into one or more buffers. The message contains either a
  31. data part, a control part, or both. The data and control parts of the
  32. message shall be placed into separate buffers, as described below. The
  33. semantics of each part are defined by the originator of the message.
  34. .P
  35. The
  36. \fIgetpmsg\fR()
  37. function shall be equivalent to
  38. \fIgetmsg\fR(),
  39. except that it provides finer control over the priority of the messages
  40. received. Except where noted, all requirements on
  41. \fIgetmsg\fR()
  42. also pertain to
  43. \fIgetpmsg\fR().
  44. .P
  45. The
  46. .IR fildes
  47. argument specifies a file descriptor referencing a STREAMS-based file.
  48. .P
  49. The
  50. .IR ctlptr
  51. and
  52. .IR dataptr
  53. arguments each point to a
  54. .BR strbuf
  55. structure, in which the
  56. .IR buf
  57. member points to a buffer in which the data or control information is
  58. to be placed, and the
  59. .IR maxlen
  60. member indicates the maximum number of bytes this buffer can hold. On
  61. return, the
  62. .IR len
  63. member shall contain the number of bytes of data or control information
  64. actually received. The
  65. .IR len
  66. member shall be set to 0 if there is a zero-length control or data part
  67. and
  68. .IR len
  69. shall be set to \-1 if no data or control information is present in
  70. the message.
  71. .P
  72. When
  73. \fIgetmsg\fR()
  74. is called,
  75. .IR flagsp
  76. should point to an integer that indicates the type of message the
  77. process is able to receive. This is described further below.
  78. .P
  79. The
  80. .IR ctlptr
  81. argument is used to hold the control part of the message, and
  82. .IR dataptr
  83. is used to hold the data part of the message. If
  84. .IR ctlptr
  85. (or
  86. .IR dataptr )
  87. is a null pointer or the
  88. .IR maxlen
  89. member is \-1, the control (or data) part of the message shall not be
  90. processed and shall be left on the STREAM head read queue, and if the
  91. .IR ctlptr
  92. (or
  93. .IR dataptr )
  94. is not a null pointer,
  95. .IR len
  96. shall be set to \-1. If the
  97. .IR maxlen
  98. member is set to 0 and there is a zero-length control (or data) part,
  99. that zero-length part shall be removed from the read queue and
  100. .IR len
  101. shall be set to 0. If the
  102. .IR maxlen
  103. member is set to 0 and there are more than 0 bytes of control (or data)
  104. information, that information shall be left on the read queue and
  105. .IR len
  106. shall be set to 0. If the
  107. .IR maxlen
  108. member in
  109. .IR ctlptr
  110. (or
  111. .IR dataptr )
  112. is less than the control (or data) part of the message,
  113. .IR maxlen
  114. bytes shall be retrieved. In this case, the remainder of the message
  115. shall be left on the STREAM head read queue and a non-zero return value
  116. shall be provided.
  117. .P
  118. By default,
  119. \fIgetmsg\fR()
  120. shall process the first available message on the STREAM head read
  121. queue. However, a process may choose to retrieve only high-priority
  122. messages by setting the integer pointed to by
  123. .IR flagsp
  124. to RS_HIPRI. In this case,
  125. \fIgetmsg\fR()
  126. shall only process the next message if it is a high-priority message.
  127. When the integer pointed to by
  128. .IR flagsp
  129. is 0, any available message shall be retrieved. In this case, on
  130. return, the integer pointed to by
  131. .IR flagsp
  132. shall be set to RS_HIPRI if a high-priority message was retrieved, or 0
  133. otherwise.
  134. .P
  135. For
  136. \fIgetpmsg\fR(),
  137. the flags are different. The
  138. .IR flagsp
  139. argument points to a bitmask with the following mutually-exclusive
  140. flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
  141. Like
  142. \fIgetmsg\fR(),
  143. \fIgetpmsg\fR()
  144. shall process the first available message on the STREAM head read
  145. queue. A process may choose to retrieve only high-priority messages by
  146. setting the integer pointed to by
  147. .IR flagsp
  148. to MSG_HIPRI and the integer pointed to by
  149. .IR bandp
  150. to 0. In this case,
  151. \fIgetpmsg\fR()
  152. shall only process the next message if it is a high-priority message.
  153. In a similar manner, a process may choose to retrieve a message from a
  154. particular priority band by setting the integer pointed to by
  155. .IR flagsp
  156. to MSG_BAND and the integer pointed to by
  157. .IR bandp
  158. to the priority band of interest. In this case,
  159. \fIgetpmsg\fR()
  160. shall only process the next message if it is in a priority band equal
  161. to, or greater than, the integer pointed to by
  162. .IR bandp ,
  163. or if it is a high-priority message. If a process wants to get the
  164. first message off the queue, the integer pointed to by
  165. .IR flagsp
  166. should be set to MSG_ANY and the integer pointed to by
  167. .IR bandp
  168. should be set to 0. On return, if the message retrieved was a
  169. high-priority message, the integer pointed to by
  170. .IR flagsp
  171. shall be set to MSG_HIPRI and the integer pointed to by
  172. .IR bandp
  173. shall be set to 0. Otherwise, the integer pointed to by
  174. .IR flagsp
  175. shall be set to MSG_BAND and the integer pointed to by
  176. .IR bandp
  177. shall be set to the priority band of the message.
  178. .P
  179. If O_NONBLOCK is not set,
  180. \fIgetmsg\fR()
  181. and
  182. \fIgetpmsg\fR()
  183. shall block until a message of the type specified by
  184. .IR flagsp
  185. is available at the front of the STREAM head read queue. If O_NONBLOCK
  186. is set and a message of the specified type is not present at the front
  187. of the read queue,
  188. \fIgetmsg\fR()
  189. and
  190. \fIgetpmsg\fR()
  191. shall fail and set
  192. .IR errno
  193. to
  194. .BR [EAGAIN] .
  195. .P
  196. If a hangup occurs on the STREAM from which messages are retrieved,
  197. \fIgetmsg\fR()
  198. and
  199. \fIgetpmsg\fR()
  200. shall continue to operate normally, as described above, until the
  201. STREAM head read queue is empty. Thereafter, they shall return 0 in the
  202. .IR len
  203. members of
  204. .IR ctlptr
  205. and
  206. .IR dataptr .
  207. .SH "RETURN VALUE"
  208. Upon successful completion,
  209. \fIgetmsg\fR()
  210. and
  211. \fIgetpmsg\fR()
  212. shall return a non-negative value. A value of 0 indicates that a full
  213. message was read successfully. A return value of MORECTL indicates
  214. that more control
  215. information is waiting for retrieval. A return value of MOREDATA
  216. indicates that more data is waiting for retrieval. A return value of
  217. the bitwise-logical OR of MORECTL and MOREDATA indicates that both
  218. types of information remain. Subsequent
  219. \fIgetmsg\fR()
  220. and
  221. \fIgetpmsg\fR()
  222. calls shall retrieve the remainder of the message. However, if a message
  223. of higher priority has come in on the STREAM head read queue, the next
  224. call to
  225. \fIgetmsg\fR()
  226. or
  227. \fIgetpmsg\fR()
  228. shall retrieve that higher-priority message before retrieving the
  229. remainder of the previous message.
  230. .P
  231. If the high priority control part of the message is consumed, the
  232. message shall be placed back on the queue as a normal message of band
  233. 0. Subsequent
  234. \fIgetmsg\fR()
  235. and
  236. \fIgetpmsg\fR()
  237. calls shall retrieve the remainder of the message. If, however, a
  238. priority message arrives or already exists on the STREAM head, the
  239. subsequent call to
  240. \fIgetmsg\fR()
  241. or
  242. \fIgetpmsg\fR()
  243. shall retrieve the higher-priority message before retrieving the
  244. remainder of the message that was put back.
  245. .P
  246. Upon failure,
  247. \fIgetmsg\fR()
  248. and
  249. \fIgetpmsg\fR()
  250. shall return \-1 and set
  251. .IR errno
  252. to indicate the error.
  253. .SH ERRORS
  254. The
  255. \fIgetmsg\fR()
  256. and
  257. \fIgetpmsg\fR()
  258. functions shall fail if:
  259. .TP
  260. .BR EAGAIN
  261. The O_NONBLOCK flag is set and no messages are available.
  262. .TP
  263. .BR EBADF
  264. The
  265. .IR fildes
  266. argument is not a valid file descriptor open for reading.
  267. .TP
  268. .BR EBADMSG
  269. The queued message to be read is not valid for
  270. \fIgetmsg\fR()
  271. or
  272. \fIgetpmsg\fR()
  273. or a pending file descriptor is at the STREAM head.
  274. .TP
  275. .BR EINTR
  276. A signal was caught during
  277. \fIgetmsg\fR()
  278. or
  279. \fIgetpmsg\fR().
  280. .TP
  281. .BR EINVAL
  282. An illegal value was specified by
  283. .IR flagsp ,
  284. or the STREAM or multiplexer referenced by
  285. .IR fildes
  286. is linked (directly or indirectly) downstream from a multiplexer.
  287. .TP
  288. .BR ENOSTR
  289. A STREAM is not associated with
  290. .IR fildes .
  291. .P
  292. In addition,
  293. \fIgetmsg\fR()
  294. and
  295. \fIgetpmsg\fR()
  296. shall fail if the STREAM head had processed an asynchronous error
  297. before the call. In this case, the value of
  298. .IR errno
  299. does not reflect the result of
  300. \fIgetmsg\fR()
  301. or
  302. \fIgetpmsg\fR()
  303. but reflects the prior error.
  304. .LP
  305. .IR "The following sections are informative."
  306. .SH EXAMPLES
  307. .SS "Getting Any Message"
  308. .P
  309. In the following example, the value of
  310. .IR fd
  311. is assumed to refer to an open STREAMS file. The call to
  312. \fIgetmsg\fR()
  313. retrieves any available message on the associated STREAM-head read
  314. queue, returning control and data information to the buffers pointed to
  315. by
  316. .IR ctrlbuf
  317. and
  318. .IR databuf ,
  319. respectively.
  320. .sp
  321. .RS 4
  322. .nf
  323. #include <stropts.h>
  324. \&...
  325. int fd;
  326. char ctrlbuf[128];
  327. char databuf[512];
  328. struct strbuf ctrl;
  329. struct strbuf data;
  330. int flags = 0;
  331. int ret;
  332. .P
  333. ctrl.buf = ctrlbuf;
  334. ctrl.maxlen = sizeof(ctrlbuf);
  335. .P
  336. data.buf = databuf;
  337. data.maxlen = sizeof(databuf);
  338. .P
  339. ret = getmsg (fd, &ctrl, &data, &flags);
  340. .fi
  341. .P
  342. .RE
  343. .SS "Getting the First Message off the Queue"
  344. .P
  345. In the following example, the call to
  346. \fIgetpmsg\fR()
  347. retrieves the first available message on the associated STREAM-head
  348. read queue.
  349. .sp
  350. .RS 4
  351. .nf
  352. #include <stropts.h>
  353. \&...
  354. .P
  355. int fd;
  356. char ctrlbuf[128];
  357. char databuf[512];
  358. struct strbuf ctrl;
  359. struct strbuf data;
  360. int band = 0;
  361. int flags = MSG_ANY;
  362. int ret;
  363. .P
  364. ctrl.buf = ctrlbuf;
  365. ctrl.maxlen = sizeof(ctrlbuf);
  366. .P
  367. data.buf = databuf;
  368. data.maxlen = sizeof(databuf);
  369. .P
  370. ret = getpmsg (fd, &ctrl, &data, &band, &flags);
  371. .fi
  372. .P
  373. .RE
  374. .SH "APPLICATION USAGE"
  375. None.
  376. .SH RATIONALE
  377. None.
  378. .SH "FUTURE DIRECTIONS"
  379. The
  380. \fIgetmsg\fR()
  381. and
  382. \fIgetpmsg\fR()
  383. functions may be removed in a future version.
  384. .SH "SEE ALSO"
  385. .IR "Section 2.6" ", " "STREAMS",
  386. .IR "\fIpoll\fR\^(\|)",
  387. .IR "\fIputmsg\fR\^(\|)",
  388. .IR "\fIread\fR\^(\|)",
  389. .IR "\fIwrite\fR\^(\|)"
  390. .P
  391. The Base Definitions volume of POSIX.1\(hy2017,
  392. .IR "\fB<stropts.h>\fP"
  393. .\"
  394. .SH COPYRIGHT
  395. Portions of this text are reprinted and reproduced in electronic form
  396. from IEEE Std 1003.1-2017, Standard for Information Technology
  397. -- Portable Operating System Interface (POSIX), The Open Group Base
  398. Specifications Issue 7, 2018 Edition,
  399. Copyright (C) 2018 by the Institute of
  400. Electrical and Electronics Engineers, Inc and The Open Group.
  401. In the event of any discrepancy between this version and the original IEEE and
  402. The Open Group Standard, the original IEEE and The Open Group Standard
  403. is the referee document. The original Standard can be obtained online at
  404. http://www.opengroup.org/unix/online.html .
  405. .PP
  406. Any typographical or formatting errors that appear
  407. in this page are most likely
  408. to have been introduced during the conversion of the source files to
  409. man page format. To report such errors, see
  410. https://www.kernel.org/doc/man-pages/reporting_bugs.html .