GETPMSG

Section: Linux Fast-STREAMS System Calls (2)
Updated: 2008-10-31
Index Return to Main Contents

NAME

getpmsg - get next message off a stream

SYNOPSIS

#include <stropts.h>

int getpmsg(int fd, struct strbuf *ctlptr, struct strbuf *dataptr, int *bandp, int *flagsp);

ARGUMENTS

fd: the file descriptor from which to get a message.
ctlptr: a pointer to a strbuf structure to hold any control part of the message.
dataptr: a pointer to a strbuf structure to hold any data part of the message.
flagsp: a pointer to a integer containing passed in and returned flags.

DESCRIPTION

getpmsg() reads a STREAMS message from the read queue of a stream head into the caller supplied buffers. The read messages will contain a control part or a data part or both. The data and control parts of the message are handled separately by

The meaning and interpretation of the contents of the control part and data part are specific to the STREAMS module to which the stream head is attached. The semantics of these contents forms a necessary part of the STREAMS module documentation.

getpmsg() provides finer control over the messages retrieved than does getmsg(2).

fd specifies a file descriptor referencing an open stream.

ctlptr is used to hold the control part of the retrieved message and datptr is used to hold the data part of the retrieved message. ctlptr and dataptr each contain NULL or a pointer to a strbuf structure, which contains the following members:

struct strbuf {
    int maxlen;         /* maximum buffer length */
    int len;            /* length of data */
    char *buf;          /* ptr to buffer */
};

maxlen: specifies the maximum number of bytes that the buffer pointed to by buf can hold. When 0 is specified, maxlen requests that only zero-length message be retrieved. When -1 is specified, maxlen requests that the corresponding control or data part not be retrieved. When set to a positive value, maxlen requests that at maximum only maxlen bytes of the control or data part be retrieved.
len: is a return value only. See ``RETURN VALUES'', below.
buf: points to the buffer into which the data or control information is to be placed.

If ctlptr or datptr is NULL, or the corresponding maxlen field is set to -1, the control or data part of the message is not processed and is left on the stream head read queue.

bandp is the lowest numerical priority band of interest. When flagsp is set to other than MSG_BAND, the integer pointed to by this argument must be coded zero (0); when flagsp is set to MSG_BAND, the integer pointed to by this argument indicates the lowest priority band of interest.

flagsp When flagsp points to an integer containing the flag MSG_ANY or MSG_HIPRI, bandp should point to an integer containing the priority band 0. When flagsp points to an integer containing the flag MSG_BAND, bandp should point to an integer containing the lowest numerical priority band of interest. flagsp should point to an integer that indicates the type of message the user is able to receive and will return the type of message received. flagsp points to an integer that can have one of the following values:

MSG_HIPRI,: requests the retrieval of the first available high priority message on the stream head read queue, and that low priority messages not be processed. For this option, the priority band indicated by bandp must be 0.
MSG_ANY,: requests the retrieval of the first available message on the stream head read queue, regardless of priority. For this option, the priority band indicated by bandp must be 0.
MSG_BAND,: requests the retrieval of the first available message in a priority band greater than or equal to the priority band specified in bandp.

If the stream head is set for non-blocking operation and no message of the specified type and priority band is available to be read, getpmsg() will fail and set errno to EAGAIN or EWOULDBLOCK. If the stream head is set for blocking operation, getpmsg() will block until a message of the specified type and priority band becomes available on the stream head read queue, or the call is interrupted by a signal. If the call is interrupted by a signal in this fashion, getpmsg() will fail and set errno to EINTR.

If a hangup occurs on the stream from which messages are to be retrieved, getpmsg() continues to operate normally, as described above, until the stream head read queue is empty. Thereafter, it returns 0 in the len field of ctlptr and dataptr.

RETURN VALUES

Upon failure, getpmsg() will return -1 and set errno as described under ``ERRORS'', below.

Upon success, getpmsg() will return a non-negative value with any of the following flags set:

MORECTL: indicates that more control information belonging to the same message is waiting to be retrieved from the stream head read queue with a subsequent getpmsg() operation.
MOREDATA: indicates that more data belonging to the same message is waiting to be retrieved from the stream head read queue with a subsequent getpmsg() operation. 0 indicates that the entire message was received successfully.

getpmsg() with the appropriate arguments will retrieve a higher priority message before the remainder of a partially retrieved lower priority message is retrieved.

Upon success, getpmsg() will also alter the len values in the strbuf structures pointed to by ctlbuf and datbuf and the integer values pointed to by bandp and flagp, as follows: The maxlen member is not altered on return. If the ctlptr or datptr a not NULL, and maxlen is not -1, the existence and length of the retrieved message is returned in the len member. If there is no control or data part retrieved, the len member of the corresponding strbuf structure is set to -1.

If the control or data part retrieved is of zero-length, the control or data part is removed from the stream head read queue and the returned len is set to 0. If maxlen is greater than or equal to 0 and the number of bytes in the control or data part is greater than maxlen, only maxlen bytes are retrieved and the remaining bytes of the corresponding part are left on the stream head read queue. In the return value the corresponding more flag (MORECTL or MOREDATA) is set. The buf member is not altered on return.

When the integer that flagp points to returns the flag MSG_BAND, the integer bandp points to returns the priority band of the retrieved message.

For getpmsg() the integer pointed to by flagsp will contain one of the following values:

MSG_HIPRI,: the retrieved message is a high priority message;
MSG_BAND,: the retrieved message is not a high priority message--the value in the integer pointed to by bandp indicates the priority band of the retrieved message.

ERRORS

Upon failure, getpmsg() will return -1 and set errno as follows:

[EISDIR]: fd refers to a directory.
[EBADF]: fd is not a valid file descriptor or is not open for reading.
[EFAULT]: A specified address is outside the user's accessible address space. Specified addresses include, ctlptr, datptr, bandp, flagsp, and the buf fields of the strbuf structure pointed to by cttlptr and datptr.
[ENODEV]: fd refers to a device that does not support the getpmsg() system call.
[ENOSTR]: fd refers to a device that has no stream associated with it.
[EIO]: I/O error, or, fd refers to a stream that is open but is in the process of closing.
[EINVAL]: fd is linked under a multiplexing driver; or, getpmsg() is not supported; or, the flags were invalid for getpmsg() (not MSG_HIPRI, MSG_ANY or MSG_BAND).
[EAGAIN], [EWOULDBLOCK]: The stream head is set for non-blocking operation and getpmsg() would block: that is, no message of the requested type and priority band is available to be read.
[EINTR]: A signal was caught, or an M_SIG(9) message processed, before the call to getpmsg() could return any data.
[ENOSTR]: fd has no stream associated with the file descriptor.
[EBADMSG]: The message at the head of the queue is of an invalid message type (valid message types include: M_DATA, M_PROTO and M_PCPROTO); or, the message at head of the of the queue is not of the requested type as specified by flagsp, or priority band as specified by bandp.

Other errors may be returned by getpmsg(). If the protocol module sends a M_ERROR(9) message to the stream head, the error returned on all subsequent read operations, including getpmsg(), is specified in the M_ERROR(9) message by the protocol module. Which errors are returned under which conditions form part of the necessary documentation of the protocol module.

NOTICES

Multi-Threading

getpmsg() is thread-safe; however, multiple threads performing concurrent partial reads on the same stream will interfere with each other. POSIX mandatory file locks, (see lockf(3)) can be used to avoid interference.

Asynchronous I/O

If the file is set for blocking operation (see fcntl(2)), then getpmsg() will block waiting for a message to arrive on the stream head in the specified band. When the file is set for non-blocking operation, getpmsg() will not block, but will return the appropriate error number ([EBADMSG], [ERESTARTSYS], [EAGAIN], [EWOULDBLOCK]) if a message of the correct type and band was not immediately available for retrieval at the stream head.

BUGS

getpmsg() has no known bugs.

COMPATIBILITY

getpmsg() is compatible with SVID[1], XID[2], SUSv2[3], SUSv3[4], POSIX, and implementations based on SVR 4.2[5], including AIX®, HP-UX®, LiS, OSF/1®, Solaris®, SUPER-UX®, UnixWare®, UXP/V®.

getpmsg() is compatible with LiS[6] with the following exceptions:

---: LiS[6] implements getmsg(2) as a call to getpmsg (2s) with a NULL bandp pointer.
---: LiS[6] incorrectly returns [EINVAL] instead of [EIO] when the internal head queue pointer points to a structure that is not a queue structure, or is mangled.
---: LiS[6] incorrectly returns [EINVAL] instead of [EIO] when q->q_first yeilds a non-NULL message pointer, but getq() later cannot retrieve a message.
---: LiS[6] does not return [EIO] when getpmsg() is called on a closing stream.
---: LiS[6] incorrectly returns [EAGAIN] or [EWOULDBLOCK] instead of [EINTR] when an M_SIG(9) message causes a signal that interrupts the call to getpmsg() before any data is read.
---: LiS[6] incorrectly returns [ENODEV] instead of [ENOSTR] when there is no stream associated with fd.
---: LiS[6] incorrectly returns [EINVAL] instead of [ENODEV] when fd refers to a device that does not support the getpmsg() system calls.

Linux Fast-STREAMS provides system calls for __NR_getpmsg and __NR_putpmsg that are used to implement this system call. (glibc has prototypes for this system call.) In addition, Linux Fast-STREAMS recognizes the ``invalid'' buffer length to read(2s) used by LiS to emulate the __NR_getpmsg system call, permitting LiS libraries to be used with Linux Fast-STREAMS.

CONFORMANCE

SVID[1], XID[2], SUSv2[3], SUSv3[4], POSIX.

HISTORY

getpmsg() first appeared in SVR 3[7].

REFERENCES

[1]: SVID, System V, Interface Definition, Fourth Edition.
[2]: XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[3]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[4]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[5]: SVR 4.2 CR, UNIX® System V Release 4.2 Command Reference Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[6]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.