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

NAME

6       getmsg, getpmsg - get next message off a stream
7

SYNOPSIS

9       #include <stropts.h>
10
11       int getmsg(int fildes, struct strbuf *restrict ctlptr,
12            struct strbuf *restrict dataptr, int *restrict flagsp);
13
14
15       int getpmsg(int fildes, struct strbuf *restrict ctlptr,
16            struct strbuf *restrict dataptr, int *restrict bandp,
17            int *restrict flagsp);
18
19

DESCRIPTION

21       The  getmsg()  function  retrieves  the  contents  of  a  message  (see
22       Intro(2)) located at  the stream head read queue from a  STREAMS  file,
23       and places the contents into user specified buffer(s). The message must
24       contain either a data part, a control part, or both. The data and  con‐
25       trol  parts  of  the  message  are  placed  into  separate buffers,  as
26       described below. The semantics of each part is defined by  the  STREAMS
27       module that generated the message.
28
29
30       The   getpmsg() function behaved like getmsg(), but provides finer con‐
31       trol over the priority of the messages received.  Except  where  noted,
32       all information pertaining to getmsg() also pertains to getpmsg().
33
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, which contains the following members:
38
39         int    maxlen;      /* maximum buffer length */
40         int    len;         /* length of data */
41         char   *buf;        /* ptr to buffer */
42
43
44
45       The buf member points to a buffer into which the data or control infor‐
46       mation is to be placed, and the maxlen  member  indicates  the  maximum
47       number  of  bytes  this buffer can hold. On return, the len member con‐
48       tains the number of bytes  of  data  or  control  information  actually
49       received; 0 if there is a zero-length control or data part; or −1 if no
50       data or control information is present in the message. The flagsp argu‐
51       ment  should point to an integer that indicates the type of message the
52       user is able to receive, as described below.
53
54
55       The ctlptr argument holds the control part from  the  message  and  the
56       dataptr  argument   holds the data part from the message. If ctlptr (or
57       dataptr) is NULL or the maxlen member is −1,   the  control  (or  data)
58       part  of  the  message  is not processed and is left on the stream head
59       read queue. If ctlptr (or dataptr) is not NULL and there is  no  corre‐
60       sponding control (or data) part of the messages on the stream head read
61       queue, len is set to −1. If the maxlen member is set to 0 and there  is
62       a zero-length control (or data)  part, that zero-length part is removed
63       from the read queue and len is set to 0. If the maxlen member is set to
64       0  and there are more than zero bytes of control (or data) information,
65       that information is left on the read queue and len is set to 0. If  the
66       maxlen  member  in  ctlptr  or dataptr is less than,  respectively, the
67       control or data part of the message, maxlen bytes  are   retrieved.  In
68       this case, the remainder of the message is left on the stream head read
69       queue and a non-zero return value is provided, as described below under
70       RETURN VALUES.
71
72
73       By  default,  getmsg()  processes  the  first  available message on the
74       stream head read queue. A user may, however, choose  to  retrieve  only
75       high  priority messages by setting  the integer pointed to by flagsp to
76       RS_HIPRI. In this case, getmsg() processes the next message only if  it
77       is a high priority message.
78
79
80       If  the  integer pointed to by flagsp is 0, getmsg() retrieves any mes‐
81       sage available on the stream head read queue. In this case, on  return,
82       the  integer  pointed  to  by flagsp will be set to  RS_HIPRI if a high
83       priority message was retrieved, or to 0 otherwise.
84
85
86       For getpmsg(), the flagsp argument points to a bitmask with the follow‐
87       ing mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
88       Like getmsg(), getpmsg() processes the first available message  on  the
89       stream  head read queue. A user may choose to retrieve only high-prior‐
90       ity messages by setting the integer pointed to by flagsp  to  MSG_HIPRI
91       and  the integer pointed to by bandp to 0. In this case, getpmsg() will
92       only process the next message if it is a high-priority  message.  In  a
93       similar manner, a user may choose to retrieve a message from a particu‐
94       lar priority band by setting  the  integer  pointed  to  by  flagsp  to
95       MSG_BAND  and  the  integer pointed to by bandp to the priority band of
96       interest. In this case, getpmsg() will only process the next message if
97       it is in a priority band equal to, or greater than, the integer pointed
98       to by bandp, or if it is a high-priority message. If a user just  wants
99       to  get  the  first  message  off  the queue, the integer pointed to by
100       flagsp should be set to MSG_ANY and the integer  pointed  to  by  bandp
101       should be set to 0. On return, if the message retrieved was a high-pri‐
102       ority message, the  integer  pointed  to  by  flagsp  will  be  set  to
103       MSG_HIPRI  and the integer pointed to by bandp will be set to 0. Other‐
104       wise, the integer pointed to by flagsp will be set to MSG_BAND and  the
105       integer  pointed  to  by  bandp will be set to the priority band of the
106       message.
107
108
109       If O_NDELAY and O_NONBLOCK are clear, getmsg() blocks until  a  message
110       of  the  type  specified by flagsp is available on the stream head read
111       queue. If O_NDELAY or O_NONBLOCK has been set  and  a  message  of  the
112       specified  type  is  not  present on the read queue, getmsg() fails and
113       sets errno to EAGAIN.
114
115
116       If a hangup occurs  on  the  stream  from  which  messages  are  to  be
117       retrieved,  getmsg() continues to operate normally, as described above,
118       until the  stream head read queue is empty. Thereafter, it returns 0 in
119       the len member of ctlptr and dataptr.
120

RETURN VALUES

122       Upon  successful completion, a non-negative value is returned. A return
123       value of 0 indicates that a  full  message  was  read  successfully.  A
124       return  value  of  MORECTL  indicates  that more control information is
125       waiting for retrieval. A return value of MOREDATA indicates  that  more
126       data  are  waiting  for retrieval. A return value of MORECTL | MOREDATA
127       indicates that both types of information  remain.  Subsequent  getmsg()
128       calls  retrieve  the remainder of the message. However, if a message of
129       higher priority has been received by the stream head  read  queue,  the
130       next call to getmsg() will retrieve that higher priority message before
131       retrieving the remainder of the previously received partial message.
132

ERRORS

134       The getmsg() and getpmsg() functions will fail if:
135
136       EAGAIN     The O_NDELAY or O_NONBLOCK flag is set and no  messages  are
137                  available.
138
139
140       EBADF      The  fildes argument is not a valid file descriptor open for
141                  reading.
142
143
144       EBADMSG    Queued message to be read is not valid for getmsg.
145
146
147       EFAULT     The ctlptr, dataptr, bandp, or flagsp argument points to  an
148                  illegal address.
149
150
151       EINTR      A signal was caught during the execution of the getmsg func‐
152                  tion.
153
154
155       EINVAL     An illegal value was specified in flagsp, or the stream ref‐
156                  erenced by fildes is linked under a multiplexor.
157
158
159       ENOSTR     A stream is not associated with fildes.
160
161
162
163       The getmsg() function can also fail if a STREAMS error message had been
164       received at the stream head before the  call  to  getmsg().  The  error
165       returned is the value contained in the STREAMS error message.
166

ATTRIBUTES

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

SEE ALSO

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