1PUTMSG(3P) POSIX Programmer's Manual PUTMSG(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 putmsg, putpmsg — send a message on a STREAM (STREAMS)
13
15 #include <stropts.h>
16 int putmsg(int fildes, const struct strbuf *ctlptr,
18 const struct strbuf *dataptr, int flags);
19 int putpmsg(int fildes, const struct strbuf *ctlptr,
20 const struct strbuf *dataptr, int band, int flags);
21
23 The putmsg() function shall create a message from a process buffer(s)
24 and send the message to a STREAMS file. The message may contain either
25 a data part, a control part, or both. The data and control parts are
26 distinguished by placement in separate buffers, as described below. The
27 semantics of each part are defined by the STREAMS module that receives
28 the message.
29 The putpmsg() function is equivalent to putmsg(), except that the
31 process can send messages in different priority bands. Except where
32 noted, all requirements on putmsg() also pertain to putpmsg().
33 The fildes argument specifies a file descriptor referencing an open
35 STREAM. The ctlptr and dataptr arguments each point to a strbuf struc‐
36 ture.
37 The ctlptr argument points to the structure describing the control
39 part, if any, to be included in the message. The buf member in the str‐
40 buf structure points to the buffer where the control information
41 resides, and the len member indicates the number of bytes to be sent.
42 The maxlen member is not used by putmsg(). In a similar manner, the
43 argument dataptr specifies the data, if any, to be included in the mes‐
44 sage. The flags argument indicates what type of message should be sent
45 and is described further below.
46 To send the data part of a message, the application shall ensure that
48 dataptr is not a null pointer and the len member of dataptr is 0 or
49 greater. To send the control part of a message, the application shall
50 ensure that the corresponding values are set for ctlptr. No data (con‐
51 trol) part shall be sent if either dataptr(ctlptr) is a null pointer or
52 the len member of dataptr(ctlptr) is set to -1.
53 For putmsg(), if a control part is specified and flags is set to
55 RS_HIPRI, a high priority message shall be sent. If no control part is
56 specified, and flags is set to RS_HIPRI, putmsg() shall fail and set
57 errno to [EINVAL]. If flags is set to 0, a normal message (priority
58 band equal to 0) shall be sent. If a control part and data part are
59 not specified and flags is set to 0, no message shall be sent and 0
60 shall be returned.
61 For putpmsg(), the flags are different. The flags argument is a bitmask
63 with the following mutually-exclusive flags defined: MSG_HIPRI and
64 MSG_BAND. If flags is set to 0, putpmsg() shall fail and set errno to
65 [EINVAL]. If a control part is specified and flags is set to MSG_HIPRI
66 and band is set to 0, a high-priority message shall be sent. If flags
67 is set to MSG_HIPRI and either no control part is specified or band is
68 set to a non-zero value, putpmsg() shall fail and set errno to [EIN‐
69 VAL]. If flags is set to MSG_BAND, then a message shall be sent in the
70 priority band specified by band. If a control part and data part are
71 not specified and flags is set to MSG_BAND, no message shall be sent
72 and 0 shall be returned.
73 The putmsg() function shall block if the STREAM write queue is full due
75 to internal flow control conditions, with the following exceptions:
76 * For high-priority messages, putmsg() shall not block on this condi‐
78 tion and continues processing the message.
79 * For other messages, putmsg() shall not block but shall fail when
81 the write queue is full and O_NONBLOCK is set.
82 The putmsg() function shall also block, unless prevented by lack of
84 internal resources, while waiting for the availability of message
85 blocks in the STREAM, regardless of priority or whether O_NONBLOCK has
86 been specified. No partial message shall be sent.
87
89 Upon successful completion, putmsg() and putpmsg() shall return 0; oth‐
90 erwise, they shall return -1 and set errno to indicate the error.
91
93 The putmsg() and putpmsg() functions shall fail if:
94 EAGAIN A non-priority message was specified, the O_NONBLOCK flag is
96 set, and the STREAM write queue is full due to internal flow
97 control conditions; or buffers could not be allocated for the
98 message that was to be created.
99 EBADF fildes is not a valid file descriptor open for writing.
101 EINTR A signal was caught during putmsg().
103 EINVAL An undefined value is specified in flags, or flags is set to
105 RS_HIPRI or MSG_HIPRI and no control part is supplied, or the
106 STREAM or multiplexer referenced by fildes is linked (directly
107 or indirectly) downstream from a multiplexer, or flags is set to
108 MSG_HIPRI and band is non-zero (for putpmsg() only).
109 ENOSR Buffers could not be allocated for the message that was to be
111 created due to insufficient STREAMS memory resources.
112 ENOSTR A STREAM is not associated with fildes.
114 ENXIO A hangup condition was generated downstream for the specified
116 STREAM.
117 EPIPE or EIO
119 The fildes argument refers to a STREAMS-based pipe and the other
120 end of the pipe is closed. A SIGPIPE signal is generated for the
121 calling thread.
122 ERANGE The size of the data part of the message does not fall within
124 the range specified by the maximum and minimum packet sizes of
125 the topmost STREAM module. This value is also returned if the
126 control part of the message is larger than the maximum config‐
127 ured size of the control part of a message, or if the data part
128 of a message is larger than the maximum configured size of the
129 data part of a message.
130 In addition, putmsg() and putpmsg() shall fail if the STREAM head had
132 processed an asynchronous error before the call. In this case, the
133 value of errno does not reflect the result of putmsg() or putpmsg(),
134 but reflects the prior error.
135 The following sections are informative.
137
139 Sending a High-Priority Message
140 The value of fd is assumed to refer to an open STREAMS file. This call
141 to putmsg() does the following:
142 1. Creates a high-priority message with a control part and a data
144 part, using the buffers pointed to by ctrlbuf and databuf, respec‐
145 tively.
146 2. Sends the message to the STREAMS file identified by fd.
148 #include <stropts.h>
151 #include <string.h>
152 ...
153 int fd;
154 char *ctrlbuf = "This is the control part";
155 char *databuf = "This is the data part";
156 struct strbuf ctrl;
157 struct strbuf data;
158 int ret;
159 ctrl.buf = ctrlbuf;
161 ctrl.len = strlen(ctrlbuf);
162 data.buf = databuf;
164 data.len = strlen(databuf);
165 ret = putmsg(fd, &ctrl, &data, MSG_HIPRI);
167 Using putpmsg()
169 This example has the same effect as the previous example. In this exam‐
170 ple, however, the putpmsg() function creates and sends the message to
171 the STREAMS file.
172 #include <stropts.h>
175 #include <string.h>
176 ...
177 int fd;
178 char *ctrlbuf = "This is the control part";
179 char *databuf = "This is the data part";
180 struct strbuf ctrl;
181 struct strbuf data;
182 int ret;
183 ctrl.buf = ctrlbuf;
185 ctrl.len = strlen(ctrlbuf);
186 data.buf = databuf;
188 data.len = strlen(databuf);
189 ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
191
193 None.
194
196 None.
197
199 The putmsg() and putpmsg() functions may be removed in a future ver‐
200 sion.
201
203 Section 2.6, STREAMS, getmsg(), poll(), read(), write()
204 The Base Definitions volume of POSIX.1‐2017, <stropts.h>
206
208 Portions of this text are reprinted and reproduced in electronic form
209 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
210 table Operating System Interface (POSIX), The Open Group Base Specifi‐
211 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
212 Electrical and Electronics Engineers, Inc and The Open Group. In the
213 event of any discrepancy between this version and the original IEEE and
214 The Open Group Standard, the original IEEE and The Open Group Standard
215 is the referee document. The original Standard can be obtained online
216 at http://www.opengroup.org/unix/online.html .
217 Any typographical or formatting errors that appear in this page are
219 most likely to have been introduced during the conversion of the source
220 files to man page format. To report such errors, see https://www.ker‐
221 nel.org/doc/man-pages/reporting_bugs.html .
222IEEE/The Open Group 2017 PUTMSG(3P)