GETMSG

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

NAME

getmsg - get next message off a stream

SYNOPSIS

#include <stropts.h>

int getmsg(int fd, struct strbuf *ctlptr, struct strbuf *dataptr, 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

getmsg 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 getmsg().

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.

The arguments to getmsg() are interpreted as follows:

fd specifies a file descriptor referencing an open stream.

ctlptr a pointer to a strbuf structure which describes the area used to store the control part of the received message.

datptr a pointer to a strbuf structure which describes the area used to store the data part of the received message.

The strbuf structure 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.

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.

For getmsg(), flagsp points to an integer that can have one of the following values:

0: requests retrieval of the first available message on the stream head read queue regardless of message priority;
RS_HIPRI: requests retrieval of the first high priority message on the stream head read queue, and that low priority messages not be processed.

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, getmsg() will fail and set errno to [EAGAIN] or [EWOULDBLOCK]. If the stream head is set for blocking operation, getmsg() 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, getmsg() will fail and set errno to EINTR.

If a hangup occurs on the stream from which messages are to be retrieved, getmsg 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, getmsg() will return -1 and set errno as described under ``ERRORS'', below.

Upon success, getmsg() 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 getmsg() 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 getmsg() operation.
0: indicates that the entire message was received successfully.

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

Upon success, getmsg() will also alter the len values in the strbuf structures pointed to by ctlbuf and datbuf and the integer value pointed to by flagp, as follows: The maxlen member is not altered on return. If the ctlptr or datptr are 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.

The integer pointed to by flagsp will contain one of the following values:

0,: the retrieved message is not a high priority message;
RS_HIPRI,: the retrieved message is a high priority message.

ERRORS

Upon failure, getmsg() 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, 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 getmsg() 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, getmsg() is not supported; or, the flags pointed to by flagsp were invalid for getmsg().
[EAGAIN], [EWOULDBLOCK]: The stream head is set for non-blocking operation and getmsg() 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 getmsg() 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.

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

NOTICES

Multi-Threading

getmsg() 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 getmsg() will block waiting for a message to arrive on the stream head. When the file is set for non-blocking operation, getmsg() will not block, but will return the appropriate error number ([EBADMSG], [ERESTARTSYS], [EAGAIN], [EWOULDBLOCK]) if a message of the correct type was not immediately available for retrieval at the stream head.

BUGS

getmsg() has no known bugs.

COMPATIBILITY

getmsg() 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®.

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

---: LiS[6] implements getmsg() as a call to getpmsg() 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 getmsg() 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 getmsg() 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 getmsg() system call.

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

getmsg() 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.