1PUTMSG(3P)                 POSIX Programmer's Manual                PUTMSG(3P)
2
3
4

PROLOG

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

NAME

12       putmsg, putpmsg — send a message on a STREAM (STREAMS)
13

SYNOPSIS

15       #include <stropts.h>
16
17       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

DESCRIPTION

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
30       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
34       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
38       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
47       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
54       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
62       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
74       The putmsg() function shall block if the STREAM write queue is full due
75       to internal flow control conditions, with the following exceptions:
76
77        *  For high-priority messages, putmsg() shall not block on this condi‐
78           tion and continues processing the message.
79
80        *  For  other  messages,  putmsg() shall not block but shall fail when
81           the write queue is full and O_NONBLOCK is set.
82
83       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

RETURN VALUE

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

ERRORS

93       The putmsg() and putpmsg() functions shall fail if:
94
95       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
100       EBADF  fildes is not a valid file descriptor open for writing.
101
102       EINTR  A signal was caught during putmsg().
103
104       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
110       ENOSR  Buffers  could  not  be allocated for the message that was to be
111              created due to insufficient STREAMS memory resources.
112
113       ENOSTR A STREAM is not associated with fildes.
114
115       ENXIO  A hangup condition was generated downstream  for  the  specified
116              STREAM.
117
118       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
123       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
131       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
136       The following sections are informative.
137

EXAMPLES

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
143        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
147        2. Sends the message to the STREAMS file identified by fd.
148
149
150           #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
160           ctrl.buf = ctrlbuf;
161           ctrl.len = strlen(ctrlbuf);
162
163           data.buf = databuf;
164           data.len = strlen(databuf);
165
166           ret = putmsg(fd, &ctrl, &data, MSG_HIPRI);
167
168   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
173
174           #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
184           ctrl.buf = ctrlbuf;
185           ctrl.len = strlen(ctrlbuf);
186
187           data.buf = databuf;
188           data.len = strlen(databuf);
189
190           ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
191

APPLICATION USAGE

193       None.
194

RATIONALE

196       None.
197

FUTURE DIRECTIONS

199       The  putmsg()  and  putpmsg() functions may be removed in a future ver‐
200       sion.
201

SEE ALSO

203       Section 2.6, STREAMS, getmsg(), poll(), read(), write()
204
205       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
218       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 .
222
223
224
225IEEE/The Open Group                  2017                           PUTMSG(3P)
Impressum