OSF

NAME

getmsg − Collect the next message from a stream

SYNOPSIS

#include <stropts.h> int getmsg(
int fd,
struct strbuf ∗ctlbuf,
struct strbuf ∗databuf,
long ∗flags);

PARAMETERS

fdSpecifies a file descriptor that references an open stream. 

ctlptrPoints to a strbuf structure that holds the control part of the message.  See the DESCRIPTION section for more information. 

dataptrPoints to a strbuf structure that holds the data part of the message. See the DESCRIPTION section for more information. 

flagsPoints to an integer that specifies the type of message that you are able to retrieve. 

DESCRIPTION

The getmsg() function references a message positioned at the stream head read queue, collects the control and data parts of the message, and then places these parts into specified buffers. 

A message must contain either a control part, data part, or both. The control part of the message is placed into the buffer specified by the ctlptr parameter.  The data part of the message is placed into the buffer specified by the dataptr parameter.  The STREAMS module that creates the message also defines the semantics of the control and data parts. 

Effects of Parameters

The fd parameter specifies a file descriptor that references an open stream. 

The ctlbuf and databuf parameters point to separate strbuf structures that contain the following members:

int maxlen;/∗ maximum buffer length ∗/
int len;/∗ length of data ∗/
char ∗buf/∗ ptr to buffer ∗/

These fields are defined as follows:

FieldFunction

maxlenSpecifies the maximum number of bytes the control or data buffer can hold. 

lenContains, on return, the number of bytes the control or data parts receive.  This field is set to zero (0) if there is a zero-length data or control part.  This field is set to -1 if the message does not contain control or data parts. 

bufPoints to the buffers in which control or data information is to reside. 

The following conditions are possible:

       •If either ctlbuf or databuf is NULL, or the maxlen field is set to -1, the control or data message is not processed, and it remains on the stream head read queue. 

       •If either the ctlbuf or databuf is not NULL, the len field is set to -1. 

       •If either ctlbuf or databuf has a zero-length, and the maxlen field is set to zero (0), the zero-length part of the message is deleted from the stream head read queue and the len field is then set to zero (0). 

       •If either ctlbuf or databuf contain more than zero (0) bytes, and the maxlen field is set to zero (0), the information remains on the stream head read queue and the len field is set to zero (0). 

       •If either the ctlbuf or databuf is greater than maxlen, maxlen bytes are retrieved, and the remainder of the message is left on the stream head read queue; a non-zero return value is given.  See the RETURN VALUE section. 

The flags parameter points to an integer that specifies the type of message you can retrieve. 

By default, the getmsg() function processes the first available message on the stream head read queue. However, if you set the flags parameter to RS_HIPRI, the getmsg() function processes the next message only if it is a high priority. On return, the priority of the message retrieved determines the next setting for the flags parameter.  If the message retrieved was a high priority, the flags parameter is set to RS_HIPRI.  In all other cases, the integer pointed to by the flags parameter is set to zero (0). 

If O_NDELAY or O_NONBLOCK has not been set, the getmsg() function blocks messages, until the message type specified by flags is encountered at the top of the stream head read queue.  If O_NDELAY or O_NONBLOCK has been set, and a message of the specified type is not present at the top of the stream head read queue, the getmsg() function fails and errno is set to EAGAIN. 

If there is a hangup on the stream from which messages are being retrieved, the getmsg() function continues to operate as previously described, until the stream head read queue is empty.  Thereafter, the functions return a value of zero (0) for the ctlbuf and databuf parameters len fields. 

RETURN VALUES

The getmsg() function returns the following values:

       •A nonnegative value indicates successful completion. 

       •A zero (0) value indicates that a full message was successfully read. 

       •A MORECTL value indicates that more control information is awaiting retrieval. 

       •A MOREDATA value indicates that more data information is awaiting retrieval. 

       •A MORECTL|MOREDATA value indicates that both control and data information are awaiting retrieval. 

Upon failure, the getmsg() function returns a value of -1, and errno is set to indicate error. 

ERRORS

Following is a list of possible conditions and error settings:

[EAGAIN]The O_NDELAY or O_NONBLOCK flag is set, and no messages are currently available. 

[EBADF]The fd parameter is not a valid file descriptor open for reading. 

[EBADMSG]The queued message to be read is not valid for getmsg(). 

[EFAULT]Ctlptr, dataptr, or flags points to a location outside the allocated address space. 

[EINTR]A signal was encountered during a getmsg() operation. 

[EINVAL]The flags parameter specifies and illegal value, or the stream referenced by fd parameter is linked under a multiplexer. 

[ENOSTR]A stream is not associated with the fd parameter. 

If a STREAMS error messages is encountered at the stream head read queue before a call was made to it, the getmsg() function fails.  The STREAMS error message specifies the error value returned. 

RELATED INFORMATION

Functions: poll(2), putmsg(2), read(2), write(2) Interfaces: streamio(7)