getmsg.3p (10985B)
- '\" et
- .TH GETMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- getmsg,
- getpmsg
- \(em receive next message from a STREAMS file (\fBSTREAMS\fP)
- .SH SYNOPSIS
- .LP
- .nf
- #include <stropts.h>
- .P
- int getmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,
- struct strbuf *restrict \fIdataptr\fP, int *restrict \fIflagsp\fP);
- int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,
- struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP,
- int *restrict \fIflagsp\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIgetmsg\fR()
- function shall retrieve the contents of a message located at the head
- of the STREAM head read queue associated with a STREAMS file and place
- the contents into one or more buffers. The message contains either a
- data part, a control part, or both. The data and control parts of the
- message shall be placed into separate buffers, as described below. The
- semantics of each part are defined by the originator of the message.
- .P
- The
- \fIgetpmsg\fR()
- function shall be equivalent to
- \fIgetmsg\fR(),
- except that it provides finer control over the priority of the messages
- received. Except where noted, all requirements on
- \fIgetmsg\fR()
- also pertain to
- \fIgetpmsg\fR().
- .P
- The
- .IR fildes
- argument specifies a file descriptor referencing a STREAMS-based file.
- .P
- The
- .IR ctlptr
- and
- .IR dataptr
- arguments each point to a
- .BR strbuf
- structure, in which the
- .IR buf
- member points to a buffer in which the data or control information is
- to be placed, and the
- .IR maxlen
- member indicates the maximum number of bytes this buffer can hold. On
- return, the
- .IR len
- member shall contain the number of bytes of data or control information
- actually received. The
- .IR len
- member shall be set to 0 if there is a zero-length control or data part
- and
- .IR len
- shall be set to \-1 if no data or control information is present in
- the message.
- .P
- When
- \fIgetmsg\fR()
- is called,
- .IR flagsp
- should point to an integer that indicates the type of message the
- process is able to receive. This is described further below.
- .P
- The
- .IR ctlptr
- argument is used to hold the control part of the message, and
- .IR dataptr
- is used to hold the data part of the message. If
- .IR ctlptr
- (or
- .IR dataptr )
- is a null pointer or the
- .IR maxlen
- member is \-1, 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
- .IR ctlptr
- (or
- .IR dataptr )
- is not a null pointer,
- .IR len
- shall be set to \-1. If the
- .IR 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
- .IR len
- shall be set to 0. If the
- .IR 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
- .IR len
- shall be set to 0. If the
- .IR maxlen
- member in
- .IR ctlptr
- (or
- .IR dataptr )
- is less than the control (or data) part of the message,
- .IR 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.
- .P
- By default,
- \fIgetmsg\fR()
- shall process the first available message on the STREAM head read
- queue. However, a process may choose to retrieve only high-priority
- messages by setting the integer pointed to by
- .IR flagsp
- to RS_HIPRI. In this case,
- \fIgetmsg\fR()
- shall only process the next message if it is a high-priority message.
- When the integer pointed to by
- .IR flagsp
- is 0, any available message shall be retrieved. In this case, on
- return, the integer pointed to by
- .IR flagsp
- shall be set to RS_HIPRI if a high-priority message was retrieved, or 0
- otherwise.
- .P
- For
- \fIgetpmsg\fR(),
- the flags are different. The
- .IR flagsp
- argument points to a bitmask with the following mutually-exclusive
- flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
- Like
- \fIgetmsg\fR(),
- \fIgetpmsg\fR()
- 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
- .IR flagsp
- to MSG_HIPRI and the integer pointed to by
- .IR bandp
- to 0. In this case,
- \fIgetpmsg\fR()
- shall only process the next message if it is 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
- .IR flagsp
- to MSG_BAND and the integer pointed to by
- .IR bandp
- to the priority band of interest. In this case,
- \fIgetpmsg\fR()
- shall only process the next message if it is in a priority band equal
- to, or greater than, the integer pointed to by
- .IR bandp ,
- or if it is a high-priority message. If a process wants to get the
- first message off the queue, the integer pointed to by
- .IR flagsp
- should be set to MSG_ANY and the integer pointed to by
- .IR bandp
- should be set to 0. On return, if the message retrieved was a
- high-priority message, the integer pointed to by
- .IR flagsp
- shall be set to MSG_HIPRI and the integer pointed to by
- .IR bandp
- shall be set to 0. Otherwise, the integer pointed to by
- .IR flagsp
- shall be set to MSG_BAND and the integer pointed to by
- .IR bandp
- shall be set to the priority band of the message.
- .P
- If O_NONBLOCK is not set,
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- shall block until a message of the type specified by
- .IR 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,
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- shall fail and set
- .IR errno
- to
- .BR [EAGAIN] .
- .P
- If a hangup occurs on the STREAM from which messages are retrieved,
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- shall continue to operate normally, as described above, until the
- STREAM head read queue is empty. Thereafter, they shall return 0 in the
- .IR len
- members of
- .IR ctlptr
- and
- .IR dataptr .
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- shall return a non-negative value. A value of 0 indicates that a full
- message was read successfully. 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
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- 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
- \fIgetmsg\fR()
- or
- \fIgetpmsg\fR()
- shall retrieve that higher-priority message before retrieving the
- remainder of the previous message.
- .P
- 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
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- 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
- \fIgetmsg\fR()
- or
- \fIgetpmsg\fR()
- shall retrieve the higher-priority message before retrieving the
- remainder of the message that was put back.
- .P
- Upon failure,
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- shall return \-1 and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- functions shall fail if:
- .TP
- .BR EAGAIN
- The O_NONBLOCK flag is set and no messages are available.
- .TP
- .BR EBADF
- The
- .IR fildes
- argument is not a valid file descriptor open for reading.
- .TP
- .BR EBADMSG
- The queued message to be read is not valid for
- \fIgetmsg\fR()
- or
- \fIgetpmsg\fR()
- or a pending file descriptor is at the STREAM head.
- .TP
- .BR EINTR
- A signal was caught during
- \fIgetmsg\fR()
- or
- \fIgetpmsg\fR().
- .TP
- .BR EINVAL
- An illegal value was specified by
- .IR flagsp ,
- or the STREAM or multiplexer referenced by
- .IR fildes
- is linked (directly or indirectly) downstream from a multiplexer.
- .TP
- .BR ENOSTR
- A STREAM is not associated with
- .IR fildes .
- .P
- In addition,
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- shall fail if the STREAM head had processed an asynchronous error
- before the call. In this case, the value of
- .IR errno
- does not reflect the result of
- \fIgetmsg\fR()
- or
- \fIgetpmsg\fR()
- but reflects the prior error.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Getting Any Message"
- .P
- In the following example, the value of
- .IR fd
- is assumed to refer to an open STREAMS file. The call to
- \fIgetmsg\fR()
- retrieves any available message on the associated STREAM-head read
- queue, returning control and data information to the buffers pointed to
- by
- .IR ctrlbuf
- and
- .IR databuf ,
- respectively.
- .sp
- .RS 4
- .nf
- #include <stropts.h>
- \&...
- int fd;
- char ctrlbuf[128];
- char databuf[512];
- struct strbuf ctrl;
- struct strbuf data;
- int flags = 0;
- int ret;
- .P
- ctrl.buf = ctrlbuf;
- ctrl.maxlen = sizeof(ctrlbuf);
- .P
- data.buf = databuf;
- data.maxlen = sizeof(databuf);
- .P
- ret = getmsg (fd, &ctrl, &data, &flags);
- .fi
- .P
- .RE
- .SS "Getting the First Message off the Queue"
- .P
- In the following example, the call to
- \fIgetpmsg\fR()
- retrieves the first available message on the associated STREAM-head
- read queue.
- .sp
- .RS 4
- .nf
- #include <stropts.h>
- \&...
- .P
- int fd;
- char ctrlbuf[128];
- char databuf[512];
- struct strbuf ctrl;
- struct strbuf data;
- int band = 0;
- int flags = MSG_ANY;
- int ret;
- .P
- ctrl.buf = ctrlbuf;
- ctrl.maxlen = sizeof(ctrlbuf);
- .P
- data.buf = databuf;
- data.maxlen = sizeof(databuf);
- .P
- ret = getpmsg (fd, &ctrl, &data, &band, &flags);
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- The
- \fIgetmsg\fR()
- and
- \fIgetpmsg\fR()
- functions may be removed in a future version.
- .SH "SEE ALSO"
- .IR "Section 2.6" ", " "STREAMS",
- .IR "\fIpoll\fR\^(\|)",
- .IR "\fIputmsg\fR\^(\|)",
- .IR "\fIread\fR\^(\|)",
- .IR "\fIwrite\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<stropts.h>\fP"
- .\"
- .SH 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 .
- .PP
- 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 .