GETMSG(3P)

💖 GETMSG(3P) 💖

okay bestie, gather round — this is GETMSG(3P), straight out of the POSIX Programmer's Manual. One thing before we go any further though, and I need you to hear me: this manual page is part of the POSIX Programmer's Manual, and the Linux implementation of this interface may differ — so if you're on Linux, consult the corresponding Linux manual page for details of Linux behavior. Or, plot twist, the interface might not even be implemented on Linux at all. iykyk 💀

---

✨ NAME ✨

getmsg, getpmsg — receive next message from a STREAMS file (STREAMS). that's the whole vibe, she's a receiver 🎀

---

🌸 SYNOPSIS 🌸

#include <stropts.h>

int getmsg(int fildes, struct strbuf *restrict ctlptr,
    struct strbuf *restrict dataptr, int *restrict flagsp);
int getpmsg(int fildes, struct strbuf *restrict ctlptr,
    struct strbuf *restrict dataptr, int *restrict bandp,
    int *restrict flagsp);

---

🦋 DESCRIPTION 🦋

So getmsg() goes and grabs the contents of a message sitting at the head of the STREAM head read queue associated with a STREAMS file, and it plops those contents into one or more buffers. The message contains either a data part, a control part, or both — both is valid, we love a versatile queen. The data part and the control part get placed into separate buffers, as described below. What each part actually means? That's defined by whoever originated the message. not our business, not our problem 💅

getpmsg() is equivalent to getmsg(), except it gives you finer control over the priority of the messages you receive. And except where noted, every single requirement on getmsg() also applies to getpmsg(). same girl, more options ✨

The fildes argument specifies a file descriptor referencing a STREAMS-based file.

The ctlptr and dataptr arguments each point to a strbuf structure, where the buf member points to a buffer that the data or control information is going to be placed into, and the maxlen member says how many bytes max that buffer can hold. On return, the len member shall contain the number of bytes of data or control information actually received. And listen: len shall be set to 0 if there's a zero-length control or data part, and len shall be set to -1 if there's no data or control information present in the message. two very different numbers, bestie, don't mix them up 😭

When getmsg() is called, flagsp should point to an integer that indicates the type of message the process is able to receive. More on that below. 👇

The ctlptr argument holds the control part of the message, and dataptr holds the data part of the message. Now here's the fine print, and it's detailed:

• If ctlptr (or dataptr) is a null pointer, or the maxlen member is -1, then the control (or data) part of the message shall not be processed and shall be left on the STREAM head read queue — and if the ctlptr (or dataptr) is not a null pointer, len shall be set to -1.
• If the maxlen member is set to 0 and there is a zero-length control (or data) part, that zero-length part shall be removed from the read queue and len shall be set to 0.
• If the maxlen member is set to 0 and there are more than 0 bytes of control (or data) information, that information shall be left on the read queue and len shall be set to 0.
• If the maxlen member in ctlptr (or dataptr) is less than the control (or data) part of the message, maxlen bytes shall be retrieved. In this case, the remainder of the message shall be left on the STREAM head read queue and a non-zero return value shall be provided. leftovers! she saves them for later 🍓

By default, getmsg() shall process the first available message on the STREAM head read queue. But a process can choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to RS_HIPRI. In that case, getmsg() shall only process the next message if it's a high-priority message. When the integer pointed to by flagsp is 0, any available message shall be retrieved — and in that case, on return, the integer pointed to by flagsp shall be set to RS_HIPRI if a high-priority message was retrieved, or 0 otherwise.

For getpmsg(), the flags are different. The flagsp argument points to a bitmask with the following mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. mutually exclusive, meaning pick ONE, we are not doing polyamory with flags today 💀

Like getmsg(), getpmsg() shall process the first available message on the STREAM head read queue. A process may choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to MSG_HIPRI and the integer pointed to by bandp to 0. In this case, getpmsg() shall only process the next message if it's a high-priority message.

In a similar manner, a process may choose to retrieve a message from a particular priority band by setting the integer pointed to by flagsp to MSG_BAND and the integer pointed to by bandp to the priority band of interest. In this case, getpmsg() shall only process the next message if it's in a priority band equal to, or greater than, the integer pointed to by bandp, or if it's a high-priority message.

If a process wants to get the first message off the queue, the integer pointed to by flagsp should be set to MSG_ANY and the integer pointed to by bandp should be set to 0.

On return: if the message retrieved was a high-priority message, the integer pointed to by flagsp shall be set to MSG_HIPRI and the integer pointed to by bandp shall be set to 0. Otherwise, the integer pointed to by flagsp shall be set to MSG_BAND and the integer pointed to by bandp shall be set to the priority band of the message. she tells you what she gave you, very communicative 🫶

If O_NONBLOCK is not set, getmsg() and getpmsg() shall block until a message of the type specified by flagsp is available at the front of the STREAM head read queue. If O_NONBLOCK is set and a message of the specified type is not present at the front of the read queue, getmsg() and getpmsg() shall fail and set errno to [EAGAIN]. blocking vs. bailing, choose your fighter

And if a hangup occurs on the STREAM from which messages are retrieved, getmsg() and getpmsg() shall continue to operate normally, as described above, until the STREAM head read queue is empty. After that, they shall return 0 in the len members of ctlptr and dataptr. she's polite even at the end of the world 🧚

---

👑 RETURN VALUE 👑

Upon successful completion, getmsg() and getpmsg() shall return a non-negative value. Here's the breakdown:

• A value of 0 indicates that a full message was read successfully. slay, complete, no crumbs
• A return value of MORECTL indicates that more control information is waiting for retrieval.
• A return value of MOREDATA indicates that more data is waiting for retrieval.
• A return value of the bitwise-logical OR of MORECTL and MOREDATA indicates that both types of information remain.

Subsequent getmsg() and getpmsg() calls shall retrieve the remainder of the message. However, if a message of higher priority has come in on the STREAM head read queue, the next call to getmsg() or getpmsg() shall retrieve that higher-priority message before retrieving the remainder of the previous message. priority says jump the line, and priority always wins 💅

If the high-priority control part of the message is consumed, the message shall be placed back on the queue as a normal message of band 0. Subsequent getmsg() and getpmsg() calls shall retrieve the remainder of the message. If, however, a priority message arrives or already exists on the STREAM head, the subsequent call to getmsg() or getpmsg() shall retrieve the higher-priority message before retrieving the remainder of the message that was put back. demoted to band 0 and then immediately queue-jumped, iconic behavior honestly 😭

Upon failure, getmsg() and getpmsg() shall return -1 and set errno to indicate the error.

---

🔥 ERRORS 🔥

The getmsg() and getpmsg() functions shall fail if:

• EAGAIN — The O_NONBLOCK flag is set and no messages are available.
• EBADF — The fildes argument is not a valid file descriptor open for reading.
• EBADMSG — The queued message to be read is not valid for getmsg() or getpmsg() or a pending file descriptor is at the STREAM head.
• EINTR — A signal was caught during getmsg() or getpmsg().
• EINVAL — An illegal value was specified by flagsp, or the STREAM or multiplexer referenced by fildes is linked (directly or indirectly) downstream from a multiplexer.
• ENOSTR — A STREAM is not associated with fildes.

In addition, getmsg() and getpmsg() shall fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno does not reflect the result of getmsg() or getpmsg() — it reflects the prior error. not me getting blamed for something that happened before I even got here 🙈

The following sections are informative. i.e. the tea is optional but delicious

---

💜 EXAMPLES 💜

🎀 Getting Any Message

In the following example, the value of fd is assumed to refer to an open STREAMS file. The call to getmsg() retrieves any available message on the associated STREAM-head read queue, returning control and data information to the buffers pointed to by ctrlbuf and databuf, respectively.

#include <stropts.h>
...
int fd;
char ctrlbuf[128];
char databuf[512];
struct strbuf ctrl;
struct strbuf data;
int flags = 0;
int ret;

ctrl.buf = ctrlbuf;
ctrl.maxlen = sizeof(ctrlbuf);

data.buf = databuf;
data.maxlen = sizeof(databuf);

ret = getmsg (fd, &ctrl, &data, &flags);

🌈 Getting the First Message off the Queue

In the following example, the call to getpmsg() retrieves the first available message on the associated STREAM-head read queue.

#include <stropts.h>
...

int fd;
char ctrlbuf[128];
char databuf[512];
struct strbuf ctrl;
struct strbuf data;
int band = 0;
int flags = MSG_ANY;
int ret;

ctrl.buf = ctrlbuf;
ctrl.maxlen = sizeof(ctrlbuf);

data.buf = databuf;
data.maxlen = sizeof(databuf);

ret = getpmsg (fd, &ctrl, &data, &band, &flags);

---

⭐ APPLICATION USAGE ⭐

None.

---

🦋 RATIONALE 🦋

None.

---

💀 FUTURE DIRECTIONS 💀

The getmsg() and getpmsg() functions may be removed in a future version. not to be dramatic but like... they might get cancelled. enjoy them while they're here bestie 😭

---

🌸 SEE ALSO 🌸

• Section 2.6, STREAMS
• poll()
• putmsg()
• read()
• write()

The Base Definitions volume of POSIX.1‐2017, <stropts.h>

---

📜 COPYRIGHT 📜

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

okay that's the whole page, love you, bye 💖✨ — this one came to you from the fine people at IEEE/The Open Group, 2017, filed under GETMSG(3P). now go read a message off a STREAM head, you absolute icon 🎀🦋💅