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
11

NAME

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

SYNOPSIS

16       #include <stropts.h>
17
18       int putmsg(int fildes, const struct strbuf *ctlptr,
19           const struct strbuf *dataptr, int flags);
20       int putpmsg(int fildes, const struct strbuf *ctlptr,
21           const struct strbuf *dataptr, int band, int flags);
22

DESCRIPTION

24       The putmsg() function shall create a message from a  process  buffer(s)
25       and  send the message to a STREAMS file. The message may contain either
26       a data part, a control part, or both. The data and  control  parts  are
27       distinguished by placement in separate buffers, as described below. The
28       semantics of each part are defined by the STREAMS module that  receives
29       the message.
30
31       The  putpmsg()  function  is  equivalent  to  putmsg(), except that the
32       process can send messages in different priority  bands.   Except  where
33       noted, all requirements on putmsg() also pertain to putpmsg().
34
35       The  fildes  argument  specifies  a file descriptor referencing an open
36       STREAM. The ctlptr and dataptr arguments each point to a strbuf  struc‐
37       ture.
38
39       The  ctlptr  argument  points  to  the structure describing the control
40       part, if any, to be included in the message. The buf member in the str‐
41       buf  structure  points  to  the  buffer  where  the control information
42       resides, and the len member indicates the number of bytes to  be  sent.
43       The  maxlen  member  is not used by putmsg().  In a similar manner, the
44       argument dataptr specifies the data, if any, to be included in the mes‐
45       sage.  The flags argument indicates what type of message should be sent
46       and is described further below.
47
48       To send the data part of a message, the application shall  ensure  that
49       dataptr  is  not  a  null pointer and the len member of dataptr is 0 or
50       greater. To send the control part of a message, the  application  shall
51       ensure that the corresponding values are set for ctlptr.  No data (con‐
52       trol) part shall be sent if either dataptr(ctlptr) is a null pointer or
53       the len member of dataptr(ctlptr) is set to −1.
54
55       For  putmsg(),  if  a  control  part  is  specified and flags is set to
56       RS_HIPRI, a high priority message shall be sent. If no control part  is
57       specified,  and  flags  is set to RS_HIPRI, putmsg() shall fail and set
58       errno to [EINVAL].  If flags is set to 0, a  normal  message  (priority
59       band  equal  to  0) shall be sent.  If a control part and data part are
60       not specified and flags is set to 0, no message shall  be  sent  and  0
61       shall be returned.
62
63       For putpmsg(), the flags are different. The flags argument is a bitmask
64       with the following  mutually-exclusive  flags  defined:  MSG_HIPRI  and
65       MSG_BAND.  If  flags is set to 0, putpmsg() shall fail and set errno to
66       [EINVAL].  If a control part is specified and flags is set to MSG_HIPRI
67       and  band  is set to 0, a high-priority message shall be sent. If flags
68       is set to MSG_HIPRI and either no control part is specified or band  is
69       set  to  a  non-zero value, putpmsg() shall fail and set errno to [EIN‐
70       VAL].  If flags is set to MSG_BAND, then a message shall be sent in the
71       priority  band  specified by band.  If a control part and data part are
72       not specified and flags is set to MSG_BAND, no message  shall  be  sent
73       and 0 shall be returned.
74
75       The putmsg() function shall block if the STREAM write queue is full due
76       to internal flow control conditions, with the following exceptions:
77
78        *  For high-priority messages, putmsg() shall not block on this condi‐
79           tion and continues processing the message.
80
81        *  For  other  messages,  putmsg() shall not block but shall fail when
82           the write queue is full and O_NONBLOCK is set.
83
84       The putmsg() function shall also block, unless  prevented  by  lack  of
85       internal  resources,  while  waiting  for  the  availability of message
86       blocks in the STREAM, regardless of priority or whether O_NONBLOCK  has
87       been specified. No partial message shall be sent.
88

RETURN VALUE

90       Upon successful completion, putmsg() and putpmsg() shall return 0; oth‐
91       erwise, they shall return −1 and set errno to indicate the error.
92

ERRORS

94       The putmsg() and putpmsg() functions shall fail if:
95
96       EAGAIN A non-priority message was specified,  the  O_NONBLOCK  flag  is
97              set,  and  the  STREAM  write queue is full due to internal flow
98              control conditions; or buffers could not be  allocated  for  the
99              message that was to be created.
100
101       EBADF  fildes is not a valid file descriptor open for writing.
102
103       EINTR  A signal was caught during putmsg().
104
105       EINVAL An  undefined  value  is  specified in flags, or flags is set to
106              RS_HIPRI or MSG_HIPRI and no control part is  supplied,  or  the
107              STREAM  or  multiplexer referenced by fildes is linked (directly
108              or indirectly) downstream from a multiplexer, or flags is set to
109              MSG_HIPRI and band is non-zero (for putpmsg() only).
110
111       ENOSR  Buffers  could  not  be allocated for the message that was to be
112              created due to insufficient STREAMS memory resources.
113
114       ENOSTR A STREAM is not associated with fildes.
115
116       ENXIO  A hangup condition was generated downstream  for  the  specified
117              STREAM.
118
119       EPIPE or EIO
120              The fildes argument refers to a STREAMS-based pipe and the other
121              end of the pipe is closed. A SIGPIPE signal is generated for the
122              calling thread.
123
124       ERANGE The  size  of  the data part of the message does not fall within
125              the range specified by the maximum and minimum packet  sizes  of
126              the  topmost  STREAM  module. This value is also returned if the
127              control part of the message is larger than the  maximum  config‐
128              ured  size of the control part of a message, or if the data part
129              of a message is larger than the maximum configured size  of  the
130              data part of a message.
131
132       In  addition,  putmsg() and putpmsg() shall fail if the STREAM head had
133       processed an asynchronous error before the  call.  In  this  case,  the
134       value  of  errno  does not reflect the result of putmsg() or putpmsg(),
135       but reflects the prior error.
136
137       The following sections are informative.
138

EXAMPLES

140   Sending a High-Priority Message
141       The value of fd is assumed to refer to an open STREAMS file. This  call
142       to putmsg() does the following:
143
144        1. Creates  a  high-priority  message  with  a control part and a data
145           part, using the buffers pointed to by ctrlbuf and databuf,  respec‐
146           tively.
147
148        2. Sends the message to the STREAMS file identified by fd.
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           #include <stropts.h>
174           #include <string.h>
175           ...
176           int fd;
177           char *ctrlbuf = "This is the control part";
178           char *databuf = "This is the data part";
179           struct strbuf ctrl;
180           struct strbuf data;
181           int ret;
182
183           ctrl.buf = ctrlbuf;
184           ctrl.len = strlen(ctrlbuf);
185
186           data.buf = databuf;
187           data.len = strlen(databuf);
188
189           ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
190

APPLICATION USAGE

192       None.
193

RATIONALE

195       None.
196

FUTURE DIRECTIONS

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

SEE ALSO

202       Section 2.6, STREAMS, getmsg(), poll(), read(), write()
203
204       The Base Definitions volume of POSIX.1‐2008, <stropts.h>
205
207       Portions of this text are reprinted and reproduced in  electronic  form
208       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
209       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
210       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
211       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
212       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) 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.unix.org/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                  2013                           PUTMSG(3P)
Impressum