1putmsg(2) System Calls putmsg(2)
2
6 putmsg, putpmsg - send a message on a stream
7
9 #include <stropts.h>
10 int putmsg(int fildes, const struct strbuf *ctlptr,
12 const struct strbuf *dataptr, int flags);
13 int putpmsg(int fildes, const struct strbuf *ctlptr,
16 const struct strbuf *dataptr,int band, int flags);
17
20 The putmsg() function creates a message from user-specified buffer(s)
21 and sends the message to a streams file. The message may contain either
22 a data part, a control part, or both. The data and control parts to be
23 sent are distinguished by placement in separate buffers, as described
24 below. The semantics of each part is defined by the streams module that
25 receives the message.
26 The putpmsg() function does the same thing as putmsg(), but provides
29 the user the ability to send messages in different priority bands.
30 Except where noted, all information pertaining to putmsg() also per‐
31 tains to putpmsg().
32 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, which contains the following members:
37 int maxlen; /* not used here */
39 int len; /* length of data */
40 void *buf; /* ptr to buffer */
41 The ctlptr argument points to the structure describing the control
45 part, if any, to be included in the message. The buf member in the str‐
46 buf structure points to the buffer where the control information
47 resides, and the len member indicates the number of bytes to be sent.
48 The maxlen member is not used in putmsg() (see getmsg(2)). In a similar
49 manner, dataptr specifies the data, if any, to be included in the mes‐
50 sage. The flags argument indicates what type of message should be sent
51 and is described later.
52 To send the data part of a message, dataptr must not be NULL, and the
55 len member of dataptr must have a value of 0 or greater. To send the
56 control part of a message, the corresponding values must be set for
57 ctlptr. No data (control) part is sent if either dataptr (ctlptr) is
58 NULL or the len member of dataptr (ctlptr) is negative.
59 For putmsg(), if a control part is specified, and flags is set to
62 RS_HIPRI, a high priority message is sent. If no control part is speci‐
63 fied, and flags is set to RS_HIPRI, putmsg() fails and sets errno to
64 EINVAL. If flags is set to 0, a normal (non-priority) message is sent.
65 If no control part and no data part are specified, and flags is set to
66 0, no message is sent, and 0 is returned.
67 The stream head guarantees that the control part of a message generated
70 by putmsg() is at least 64 bytes in length.
71 For putpmsg(), the flags are different. The flags argument is a bit‐
74 mask with the following mutually-exclusive flags defined: MSG_HIPRI and
75 MSG_BAND. If flags is set to 0, putpmsg() fails and sets errno to EIN‐
76 VAL. If a control part is specified and flags is set to MSG_HIPRI and
77 band is set to 0, a high-priority message is sent. If flags is set to
78 MSG_HIPRI and either no control part is specified or band is set to a
79 non-zero value, putpmsg() fails and sets errno to EINVAL. If flags is
80 set to MSG_BAND, then a message is sent in the priority band specified
81 by band. If a control part and data part are not specified and flags is
82 set to MSG_BAND, no message is sent and 0 is returned.
83 Normally, putmsg() will block if the stream write queue is full due to
86 internal flow control conditions. For high-priority messages, putmsg()
87 does not block on this condition. For other messages, putmsg() does
88 not block when the write queue is full and O_NDELAY or O_NONBLOCK is
89 set. Instead, it fails and sets errno to EAGAIN.
90 The putmsg() or putpmsg() function also blocks, unless prevented by
93 lack of internal resources, waiting for the availability of message
94 blocks in the stream, regardless of priority or whether O_NDELAY or
95 O_NONBLOCK has been specified. No partial message is sent.
96
98 Upon successful completion, 0 is returned. Otherwise, −1 is returned
99 and errno is set to indicate the error.
100
102 The putmsg() and putpmsg() functions will fail if:
103 EAGAIN A non-priority message was specified, the O_NDELAY or
105 O_NONBLOCK flag is set and the stream write queue is
106 full due to internal flow control conditions.
107 EBADF The fildes argument is not a valid file descriptor open
110 for writing.
111 EFAULT The ctlptr or dataptr argument points to an illegal
114 address.
115 EINTR A signal was caught during the execution of the
118 putmsg() function.
119 EINVAL An undefined value was specified in flags; flags is set
122 to RS_HIPRI and no control part was supplied; or the
123 stream referenced by fildes is linked below a multi‐
124 plexor.
125 ENOSR Buffers could not be allocated for the message that was
128 to be created due to insufficient streams memory
129 resources.
130 ENOSTR The fildes argument is not associated with a stream.
133 ENXIO A hangup condition was generated downstream for the
136 specified stream, or the other end of the pipe is
137 closed.
138 EPIPE or EIO The fildes argument refers to a streams-based pipe and
141 the other end of the pipe is closed. A SIGPIPE signal
142 is generated for the calling thread. This error condi‐
143 tion occurs only with SUS-conforming applications. See
144 standards(5).
145 ERANGE The size of the data part of the message does not fall
148 within the range specified by the maximum and minimum
149 packet sizes of the topmost stream module. This value
150 is also returned if the control part of the message is
151 larger than the maximum configured size of the control
152 part of a message, or if the data part of a message is
153 larger than the maximum configured size of the data
154 part of a message.
155 In addition, putmsg() and putpmsg() will fail if the stream head had
159 processed an asynchronous error before the call. In this case, the
160 value of errno does not reflect the result of putmsg() or putpmsg() but
161 reflects the prior error.
162 The putpmsg() function will fail if:
165 EINVAL The flags argument is set to MSG_HIPRI and band is non-zero.
167
170 See attributes(5) for descriptions of the following attributes:
171 ┌─────────────────────────────┬─────────────────────────────┐
176 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
177 ├─────────────────────────────┼─────────────────────────────┤
178 │Interface Stability │Standard │
179 └─────────────────────────────┴─────────────────────────────┘
180
182 Intro(2), getmsg(2), poll(2), read(2), write(2), attributes(5), stan‐
183 dards(5)
184 STREAMS Programming Guide
187SunOS 5.11 1 Nov 2003 putmsg(2)