1putmsg(2)                        System Calls                        putmsg(2)
2
3
4

NAME

6       putmsg, putpmsg - send a message on a stream
7

SYNOPSIS

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

DESCRIPTION

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
27
28       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
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, which contains the following members:
37
38         int      maxlen;     /* not used here */
39         int      len;        /* length of data */
40         void     *buf;       /* ptr to buffer */
41
42
43
44       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
53
54       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
60
61       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
68
69       The stream head guarantees that the control part of a message generated
70       by putmsg() is at least 64 bytes in length.
71
72
73       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
84
85       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
91
92       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

RETURN VALUES

98       Upon successful completion, 0 is returned. Otherwise,  −1  is  returned
99       and errno is set to indicate the error.
100

ERRORS

102       The putmsg() and putpmsg() functions will fail if:
103
104       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
108
109       EBADF           The fildes argument is not a valid file descriptor open
110                       for writing.
111
112
113       EFAULT          The ctlptr or dataptr argument  points  to  an  illegal
114                       address.
115
116
117       EINTR           A  signal  was  caught  during  the  execution  of  the
118                       putmsg() function.
119
120
121       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
126
127       ENOSR           Buffers could not be allocated for the message that was
128                       to  be  created  due  to  insufficient  streams  memory
129                       resources.
130
131
132       ENOSTR          The fildes argument is not associated with a stream.
133
134
135       ENXIO           A  hangup  condition  was  generated downstream for the
136                       specified stream, or the  other  end  of  the  pipe  is
137                       closed.
138
139
140       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
146
147       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
156
157
158       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
163
164       The putpmsg() function will fail if:
165
166       EINVAL    The flags argument is set to MSG_HIPRI and band is non-zero.
167
168

ATTRIBUTES

170       See attributes(5) for descriptions of the following attributes:
171
172
173
174
175       ┌─────────────────────────────┬─────────────────────────────┐
176       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
177       ├─────────────────────────────┼─────────────────────────────┤
178       │Interface Stability          │Standard                     │
179       └─────────────────────────────┴─────────────────────────────┘
180

SEE ALSO

182       Intro(2),  getmsg(2),  poll(2), read(2), write(2), attributes(5), stan‐
183       dards(5)
184
185
186       STREAMS Programming Guide
187
188
189
190SunOS 5.11                        1 Nov 2003                         putmsg(2)
Impressum