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

putmsg.3p (9149B)


  1. '\" et
  2. .TH PUTMSG "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. putmsg,
  12. putpmsg
  13. \(em send a message on a STREAM (\fBSTREAMS\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <stropts.h>
  18. .P
  19. int putmsg(int \fIfildes\fP, const struct strbuf *\fIctlptr\fP,
  20. const struct strbuf *\fIdataptr\fP, int \fIflags\fP);
  21. int putpmsg(int \fIfildes\fP, const struct strbuf *\fIctlptr\fP,
  22. const struct strbuf *\fIdataptr\fP, int \fIband\fP, int \fIflags\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIputmsg\fR()
  27. function shall create a message from a process buffer(s) and send the
  28. message to a STREAMS file. The message may contain either a data part,
  29. a control part, or both. The data and control parts are distinguished
  30. by placement in separate buffers, as described below. The semantics of
  31. each part are defined by the STREAMS module that receives the message.
  32. .P
  33. The
  34. \fIputpmsg\fR()
  35. function is equivalent to
  36. \fIputmsg\fR(),
  37. except that the process can send messages in different priority bands.
  38. Except where noted, all requirements on
  39. \fIputmsg\fR()
  40. also pertain to
  41. \fIputpmsg\fR().
  42. .P
  43. The
  44. .IR fildes
  45. argument specifies a file descriptor referencing an open STREAM. The
  46. .IR ctlptr
  47. and
  48. .IR dataptr
  49. arguments each point to a
  50. .BR strbuf
  51. structure.
  52. .P
  53. The
  54. .IR ctlptr
  55. argument points to the structure describing the control part, if any,
  56. to be included in the message. The
  57. .IR buf
  58. member in the
  59. .BR strbuf
  60. structure points to the buffer where the control information resides,
  61. and the
  62. .IR len
  63. member indicates the number of bytes to be sent. The
  64. .IR maxlen
  65. member is not used by
  66. \fIputmsg\fR().
  67. In a similar manner, the argument
  68. .IR dataptr
  69. specifies the data, if any, to be included in the message. The
  70. .IR flags
  71. argument indicates what type of message should be sent and is described
  72. further below.
  73. .P
  74. To send the data part of a message, the application shall ensure that
  75. .IR dataptr
  76. is not a null pointer and the
  77. .IR len
  78. member of
  79. .IR dataptr
  80. is 0 or greater. To send the control part of a message, the application
  81. shall ensure that the corresponding values are set for
  82. .IR ctlptr .
  83. No data (control) part shall be sent if either
  84. .IR dataptr (\c
  85. .IR ctlptr )
  86. is a null pointer or the
  87. .IR len
  88. member of
  89. .IR dataptr (\c
  90. .IR ctlptr )
  91. is set to \-1.
  92. .P
  93. For
  94. \fIputmsg\fR(),
  95. if a control part is specified and
  96. .IR flags
  97. is set to RS_HIPRI, a high
  98. priority message shall be sent. If no control part is specified, and
  99. .IR flags
  100. is set to RS_HIPRI,
  101. \fIputmsg\fR()
  102. shall fail and set
  103. .IR errno
  104. to
  105. .BR [EINVAL] .
  106. If
  107. .IR flags
  108. is set to 0, a normal message (priority band equal to 0) shall be sent.
  109. If a control part and data part are not specified and
  110. .IR flags
  111. is set to 0, no message shall be sent and 0 shall be returned.
  112. .P
  113. For
  114. \fIputpmsg\fR(),
  115. the flags are different. The
  116. .IR flags
  117. argument is a bitmask with the following mutually-exclusive flags
  118. defined: MSG_HIPRI and MSG_BAND. If
  119. .IR flags
  120. is set to 0,
  121. \fIputpmsg\fR()
  122. shall fail and set
  123. .IR errno
  124. to
  125. .BR [EINVAL] .
  126. If a control part is specified and
  127. .IR flags
  128. is set to MSG_HIPRI and
  129. .IR band
  130. is set to 0, a high-priority message shall be sent. If
  131. .IR flags
  132. is set to MSG_HIPRI and either no control part is specified or
  133. .IR band
  134. is set to a non-zero value,
  135. \fIputpmsg\fR()
  136. shall fail and set
  137. .IR errno
  138. to
  139. .BR [EINVAL] .
  140. If
  141. .IR flags
  142. is set to MSG_BAND, then a message shall be sent in the priority band
  143. specified by
  144. .IR band .
  145. If a control part and data part are not specified and
  146. .IR flags
  147. is set to MSG_BAND, no message shall be sent and 0 shall be returned.
  148. .br
  149. .P
  150. The
  151. \fIputmsg\fR()
  152. function shall block if the STREAM write queue is full due to internal
  153. flow control conditions, with the following exceptions:
  154. .IP " *" 4
  155. For high-priority messages,
  156. \fIputmsg\fR()
  157. shall not block on this condition and continues processing the message.
  158. .IP " *" 4
  159. For other messages,
  160. \fIputmsg\fR()
  161. shall not block but shall fail when the write queue is full and
  162. O_NONBLOCK is set.
  163. .P
  164. The
  165. \fIputmsg\fR()
  166. function shall also block, unless prevented by lack of internal
  167. resources, while waiting for the availability of message blocks in the
  168. STREAM, regardless of priority or whether O_NONBLOCK has been
  169. specified. No partial message shall be sent.
  170. .SH "RETURN VALUE"
  171. Upon successful completion,
  172. \fIputmsg\fR()
  173. and
  174. \fIputpmsg\fR()
  175. shall return 0; otherwise, they shall return \-1 and set
  176. .IR errno
  177. to indicate the error.
  178. .SH ERRORS
  179. The
  180. \fIputmsg\fR()
  181. and
  182. \fIputpmsg\fR()
  183. functions shall fail if:
  184. .TP
  185. .BR EAGAIN
  186. A non-priority message was specified, the O_NONBLOCK flag is set, and
  187. the STREAM write queue is full due to internal flow control conditions;
  188. or buffers could not be allocated for the message that was to be
  189. created.
  190. .TP
  191. .BR EBADF
  192. .IR fildes
  193. is not a valid file descriptor open for writing.
  194. .TP
  195. .BR EINTR
  196. A signal was caught during
  197. \fIputmsg\fR().
  198. .TP
  199. .BR EINVAL
  200. An undefined value is specified in
  201. .IR flags ,
  202. or
  203. .IR flags
  204. is set to RS_HIPRI or MSG_HIPRI and no control part is supplied, or the
  205. STREAM or multiplexer referenced by
  206. .IR fildes
  207. is linked (directly or indirectly) downstream from a multiplexer, or
  208. .IR flags
  209. is set to MSG_HIPRI and
  210. .IR band
  211. is non-zero (for
  212. \fIputpmsg\fR()
  213. only).
  214. .TP
  215. .BR ENOSR
  216. Buffers could not be allocated for the message that was to be created
  217. due to insufficient STREAMS memory resources.
  218. .TP
  219. .BR ENOSTR
  220. A STREAM is not associated with
  221. .IR fildes .
  222. .TP
  223. .BR ENXIO
  224. A hangup condition was generated downstream for the specified STREAM.
  225. .TP
  226. .BR EPIPE " or " EIO
  227. The
  228. .IR fildes
  229. argument refers to a STREAMS-based pipe and the other end of the pipe
  230. is closed. A SIGPIPE signal is generated for the calling thread.
  231. .TP
  232. .BR ERANGE
  233. The size of the data part of the message does not fall within the range
  234. specified by the maximum and minimum packet sizes of the topmost STREAM
  235. module. This value is also returned if the control part of the message
  236. is larger than the maximum configured size of the control part of a
  237. message, or if the data part of a message is larger than the maximum
  238. configured size of the data part of a message.
  239. .P
  240. In addition,
  241. \fIputmsg\fR()
  242. and
  243. \fIputpmsg\fR()
  244. shall fail if the STREAM head had processed an asynchronous error
  245. before the call. In this case, the value of
  246. .IR errno
  247. does not reflect the result of
  248. \fIputmsg\fR()
  249. or
  250. \fIputpmsg\fR(),
  251. but reflects the prior error.
  252. .br
  253. .LP
  254. .IR "The following sections are informative."
  255. .SH EXAMPLES
  256. .SS "Sending a High-Priority Message"
  257. .P
  258. The value of
  259. .IR fd
  260. is assumed to refer to an open STREAMS file. This call to
  261. \fIputmsg\fR()
  262. does the following:
  263. .IP " 1." 4
  264. Creates a high-priority message with a control part and a data part,
  265. using the buffers pointed to by
  266. .IR ctrlbuf
  267. and
  268. .IR databuf ,
  269. respectively.
  270. .IP " 2." 4
  271. Sends the message to the STREAMS file identified by
  272. .IR fd .
  273. .sp
  274. .RS 4
  275. .nf
  276. #include <stropts.h>
  277. #include <string.h>
  278. \&...
  279. int fd;
  280. char *ctrlbuf = "This is the control part";
  281. char *databuf = "This is the data part";
  282. struct strbuf ctrl;
  283. struct strbuf data;
  284. int ret;
  285. .P
  286. ctrl.buf = ctrlbuf;
  287. ctrl.len = strlen(ctrlbuf);
  288. .P
  289. data.buf = databuf;
  290. data.len = strlen(databuf);
  291. .P
  292. ret = putmsg(fd, &ctrl, &data, MSG_HIPRI);
  293. .fi
  294. .P
  295. .RE
  296. .SS "Using putpmsg(\|)"
  297. .P
  298. This example has the same effect as the previous example. In this
  299. example, however, the
  300. \fIputpmsg\fR()
  301. function creates and sends the message to the STREAMS file.
  302. .sp
  303. .RS 4
  304. .nf
  305. #include <stropts.h>
  306. #include <string.h>
  307. \&...
  308. int fd;
  309. char *ctrlbuf = "This is the control part";
  310. char *databuf = "This is the data part";
  311. struct strbuf ctrl;
  312. struct strbuf data;
  313. int ret;
  314. .P
  315. ctrl.buf = ctrlbuf;
  316. ctrl.len = strlen(ctrlbuf);
  317. .P
  318. data.buf = databuf;
  319. data.len = strlen(databuf);
  320. .P
  321. ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
  322. .fi
  323. .P
  324. .RE
  325. .SH "APPLICATION USAGE"
  326. None.
  327. .SH RATIONALE
  328. None.
  329. .SH "FUTURE DIRECTIONS"
  330. The
  331. \fIputmsg\fR()
  332. and
  333. \fIputpmsg\fR()
  334. functions may be removed in a future version.
  335. .SH "SEE ALSO"
  336. .IR "Section 2.6" ", " "STREAMS",
  337. .IR "\fIgetmsg\fR\^(\|)",
  338. .IR "\fIpoll\fR\^(\|)",
  339. .IR "\fIread\fR\^(\|)",
  340. .IR "\fIwrite\fR\^(\|)"
  341. .P
  342. The Base Definitions volume of POSIX.1\(hy2017,
  343. .IR "\fB<stropts.h>\fP"
  344. .\"
  345. .SH COPYRIGHT
  346. Portions of this text are reprinted and reproduced in electronic form
  347. from IEEE Std 1003.1-2017, Standard for Information Technology
  348. -- Portable Operating System Interface (POSIX), The Open Group Base
  349. Specifications Issue 7, 2018 Edition,
  350. Copyright (C) 2018 by the Institute of
  351. Electrical and Electronics Engineers, Inc and The Open Group.
  352. In the event of any discrepancy between this version and the original IEEE and
  353. The Open Group Standard, the original IEEE and The Open Group Standard
  354. is the referee document. The original Standard can be obtained online at
  355. http://www.opengroup.org/unix/online.html .
  356. .PP
  357. Any typographical or formatting errors that appear
  358. in this page are most likely
  359. to have been introduced during the conversion of the source files to
  360. man page format. To report such errors, see
  361. https://www.kernel.org/doc/man-pages/reporting_bugs.html .