| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 2: System Calls Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 2: System Calls Oracle Solaris 11 Information Library |
- get next message off a stream
#include <stropts.h>intgetmsg(intfildes,struct strbuf *restrictctlptr,struct strbuf *restrictdataptr,int *restrictflagsp);
intgetpmsg(intfildes,struct strbuf *restrictctlptr,struct strbuf *restrictdataptr,int *restrictbandp,int *restrictflagsp);
Thegetmsg() function retrieves the contents of a message (seeIntro(2))located at the stream head read queue from a STREAMS file, andplaces the contents into user specified buffer(s). The message must contain eithera data part, a control part, or both. The data and controlparts of the message are placed into separate buffers, as describedbelow. The semantics of each part is defined by the STREAMS modulethat generated the message.
Thegetpmsg() function behaved likegetmsg(), but provides finer control overthe priority of the messages received. Except where noted, all information pertainingtogetmsg() also pertains togetpmsg().
Thefildes argument specifies a file descriptor referencing an open stream. Thectlptr anddataptr arguments each point to astrbuf structure, whichcontains the following members:
int maxlen; /* maximum buffer length */int len; /* length of data */char *buf; /* ptr to buffer */
Thebuf member points to a buffer into which the data orcontrol information is to be placed, and themaxlen member indicates themaximum number of bytes this buffer can hold. On return, thelenmember contains the number of bytes of data or control information actually received;0 if there is a zero-length control or data part; or -1if no data or control information is present in the message. Theflagsp argument should point to an integer that indicates the type ofmessage the user is able to receive, as described below.
Thectlptr argument holds the control part from the message and thedataptr argument holds the data part from the message. Ifctlptr(ordataptr) isNULL or themaxlen member is -1, thecontrol (or data) part of the message is not processed and isleft on the stream head read queue. Ifctlptr (ordataptr) isnotNULL and there is no corresponding control (or data) part of themessages on the stream head read queue,len is set to -1.If themaxlen member is set to 0 and there is azero-length control (or data) part, that zero-length part is removed fromthe read queue andlen is set to 0. If themaxlen memberis set to 0 and there are more than zero bytes ofcontrol (or data) information, that information is left on the read queueandlen is set to 0. If themaxlen member inctlptrordataptr is less than, respectively, the control or data part ofthe message,maxlen bytes are retrieved. In this case, the remainderof the message is left on the stream head read queueand a non-zero return value is provided, as described below underRETURN VALUES.
By default,getmsg() processes the first available message on the streamhead read queue. A user may, however, choose to retrieve only highpriority messages by setting the integer pointed to byflagsp toRS_HIPRI. In this case,getmsg() processes the next message only if itis a high priority message.
If the integer pointed to byflagsp is 0,getmsg() retrieves anymessage available on the stream head read queue. In this case, onreturn, the integer pointed to byflagsp will be set toRS_HIPRI if a high priority message was retrieved, or to 0 otherwise.
Forgetpmsg(), theflagsp argument points to a bitmask with the followingmutually-exclusive flags defined:MSG_HIPRI,MSG_BAND, andMSG_ANY. Likegetmsg(),getpmsg() processes the firstavailable message on the stream head read queue. A user may chooseto retrieve only high-priority messages by setting the integer pointed to byflagsp toMSG_HIPRI and the integer pointed to bybandp to 0.In this case,getpmsg() will only process the next message if itis a high-priority message. In a similar manner, a user may chooseto retrieve a message from a particular priority band by setting theinteger pointed to byflagsp toMSG_BAND and the integer pointed to bybandp to the priority band of interest. In this case,getpmsg() willonly process the next message if it is in a priority bandequal to, or greater than, the integer pointed to bybandp, orif it is a high-priority message. If a user just wants to getthe first message off the queue, the integer pointed to byflagspshould be set toMSG_ANY and the integer pointed to bybandpshould be set to 0. On return, if the message retrieved wasa high-priority message, the integer pointed to byflagsp will be set toMSG_HIPRI and the integer pointed to bybandp will be set to0. Otherwise, the integer pointed to byflagsp will be set toMSG_BAND and the integer pointed to bybandp will be set to thepriority band of the message.
IfO_NDELAY andO_NONBLOCK are clear,getmsg() blocks until a message ofthe type specified byflagsp is available on the stream head read queue. IfO_NDELAY orO_NONBLOCK has been set and a message ofthe specified type is not present on the read queue,getmsg() failsand setserrno toEAGAIN.
If a hangup occurs on the stream from which messages are tobe retrieved,getmsg() continues to operate normally, as described above, until the stream head read queue is empty. Thereafter, it returns 0 inthelen member ofctlptr anddataptr.
Upon successful completion, a non-negative value is returned. A return value of0 indicates that a full message was read successfully. A return valueofMORECTL indicates that more control information is waiting for retrieval. Areturn value ofMOREDATA indicates that more data are waiting for retrieval.A return value ofMORECTL |MOREDATA indicates that both types ofinformation remain. Subsequentgetmsg() calls retrieve the remainder of the message. However,if a message of higher priority has been received by the stream headread queue, the next call togetmsg() will retrieve that higher prioritymessage before retrieving the remainder of the previously received partial message.
Thegetmsg() andgetpmsg() functions will fail if:
TheO_NDELAY orO_NONBLOCK flag is set and no messages are available.
Thefildes argument is not a valid file descriptor open for reading.
Queued message to be read is not valid forgetmsg.
Thectlptr,dataptr,bandp, orflagsp argument points to an illegal address.
A signal was caught during the execution of thegetmsg function.
An illegal value was specified inflagsp, or the stream referenced byfildes is linked under a multiplexor.
A stream is not associated withfildes.
Thegetmsg() function can also fail if a STREAMS error message hadbeen received at the stream head before the call togetmsg(). Theerror returned is the value contained in the STREAMS error message.
Seeattributes(5) for descriptions of the following attributes:
|
Intro(2),poll(2),putmsg(2),read(2),write(2),attributes(5),standards(5)
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |