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

NAME

6       putmsg, putpmsg - send a message on a STREAM (STREAMS)
7

SYNOPSIS

9       #include <stropts.h>
10
11       int putmsg(int fildes, const struct strbuf *ctlptr,
12              const struct strbuf *dataptr, int flags);
13       int putpmsg(int fildes, const struct strbuf *ctlptr,
14              const struct strbuf *dataptr, int band, int flags);
15
16

DESCRIPTION

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

RETURN VALUE

84       Upon successful completion, putmsg() and putpmsg() shall return 0; oth‐
85       erwise, they shall return -1 and set errno to indicate the error.
86

ERRORS

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

EXAMPLES

135   Sending a High-Priority Message
136       The value of fd is assumed to refer to an open STREAMS file.  This call
137       to putmsg() does the following:
138
139        1. Creates a high-priority message with a  control  part  and  a  data
140           part,  using the buffers pointed to by ctrlbuf and databuf, respec‐
141           tively.
142
143        2. Sends the message to the STREAMS file identified by fd.
144
145              #include <stropts.h>
146              #include <string.h>
147              ...
148              int fd;
149              char *ctrlbuf = "This is the control part";
150              char *databuf = "This is the data part";
151              struct strbuf ctrl;
152              struct strbuf data;
153              int ret;
154
155
156              ctrl.buf = ctrlbuf;
157              ctrl.len = strlen(ctrlbuf);
158
159
160              data.buf = databuf;
161              data.len = strlen(databuf);
162
163
164              ret = putmsg(fd, &ctrl, &data, MSG_HIPRI);
165
166   Using putpmsg()
167       This example has the same effect as the previous example. In this exam‐
168       ple,  however,  the putpmsg() function creates and sends the message to
169       the STREAMS file.
170
171
172              #include <stropts.h>
173              #include <string.h>
174              ...
175              int fd;
176              char *ctrlbuf = "This is the control part";
177              char *databuf = "This is the data part";
178              struct strbuf ctrl;
179              struct strbuf data;
180              int ret;
181
182
183              ctrl.buf = ctrlbuf;
184              ctrl.len = strlen(ctrlbuf);
185
186
187              data.buf = databuf;
188              data.len = strlen(databuf);
189
190
191              ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
192

APPLICATION USAGE

194       None.
195

RATIONALE

197       None.
198

FUTURE DIRECTIONS

200       None.
201

SEE ALSO

203       STREAMS , getmsg() , poll() , read() , write() , the  Base  Definitions
204       volume of IEEE Std 1003.1-2001, <stropts.h>
205
207       Portions  of  this text are reprinted and reproduced in electronic form
208       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
209       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
210       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
211       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
212       event of any discrepancy between this version and the original IEEE and
213       The  Open Group Standard, the original IEEE and The Open Group Standard
214       is the referee document. The original Standard can be  obtained  online
215       at http://www.opengroup.org/unix/online.html .
216
217
218
219IEEE/The Open Group                  2003                            PUTMSG(P)
Impressum