Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ./../../../../../data-stud/../../usr/man/man2/getmsg.2
Real path: /usr/share/man/man2/getmsg.2
Zurück

'\" te .\" Copyright (c) 1989, AT&T. All rights reserved. .\" Portions Copyright (c) 2003, 2023, Oracle and/or its affiliates. .TH getmsg 2 "30 Jan 2023" "Oracle Solaris 11.4" "System Calls" .SH NAME getmsg, getpmsg \- get next message off a stream .SH SYNOPSIS .LP .nf #include <stropts.h> \fBint\fR \fBgetmsg\fR(\fBint\fR \fIfildes\fR, \fBstruct strbuf *restrict\fR \fIctlptr\fR, \fBstruct strbuf *restrict\fR \fIdataptr\fR, \fBint *restrict\fR \fIflagsp\fR); .fi .LP .nf \fBint\fR \fBgetpmsg\fR(\fBint\fR \fIfildes\fR, \fBstruct strbuf *restrict\fR \fIctlptr\fR, \fBstruct strbuf *restrict\fR \fIdataptr\fR, \fBint *restrict\fR \fIbandp\fR, \fBint *restrict\fR \fIflagsp\fR); .fi .SH DESCRIPTION .sp .LP The \fBgetmsg()\fR function retrieves the contents of a message (see \fBIntro\fR(2)) located at the stream head read queue from a STREAMS file, and places the contents into user specified buffer(s). The message must contain either a data part, a control part, or both. The data and control parts of the message are placed into separate buffers, as described below. The semantics of each part is defined by the STREAMS module that generated the message. .sp .LP The \fBgetpmsg()\fR function behaves like \fBgetmsg()\fR, but provides finer control over the priority of the messages received. Except where noted, all information pertaining to \fBgetmsg()\fR also pertains to \fBgetpmsg()\fR. .sp .LP The \fIfildes\fR argument specifies a file descriptor referencing an open stream. The \fIctlptr\fR and \fIdataptr\fR arguments each point to a \fBstrbuf\fR structure, which contain the following members: .sp .in +2 .nf int maxlen; /* maximum buffer length */ int len; /* length of data */ char *buf; /* ptr to buffer */ .fi .in -2 .sp .sp .LP The \fBbuf\fR member points to a buffer into which the data or control information is to be placed, and the \fBmaxlen\fR member indicates the maximum number of bytes this buffer can hold. On return, the \fBlen\fR member contains the number of bytes of data or control information actually received; 0 if there is a zero-length control or data part, or \(mi1 if no data or control information is present in the message. The \fIflagsp\fR argument should point to an integer that indicates the type of message the user is able to receive, as described below. .sp .LP The \fIctlptr\fR argument holds the control part from the message and the \fIdataptr\fR argument holds the data part from the message. If \fIctlptr\fR (or \fIdataptr\fR) is \fINULL\fR or the \fBmaxlen\fR member is \(mi1, the control (or data) part of the message is not processed and is left on the stream head read queue. If \fIctlptr\fR (or \fIdataptr\fR) is not \fINULL\fR and there is no corresponding control (or data) part of the messages on the stream head read queue, \fBlen\fR is set to \(mi1. If the \fBmaxlen\fR member is set to 0 and there is a zero-length control (or data) part, that zero-length part is removed from the read queue and \fBlen\fR is set to 0. If the \fBmaxlen\fR member is set to 0 and there are more than zero bytes of control (or data) information, that information is left on the read queue and \fBlen\fR is set to 0. If the \fBmaxlen\fR member in \fIctlptr\fR or \fIdataptr\fR is less than, respectively, the control or data part of the message, \fBmaxlen\fR bytes are retrieved. In this case, the remainder of the message is left on the stream head read queue and a non-zero return value is provided, as described below under \fBRETURN VALUES\fR. .sp .LP By default, \fBgetmsg()\fR processes the first available message on the stream head read queue. A user may, however, choose to retrieve only high priority messages by setting the integer pointed to by \fIflagsp\fR to \fBRS_HIPRI\fR. In this case, \fBgetmsg()\fR processes the next message only if it is a high priority message. .sp .LP If the integer pointed to by \fIflagsp\fR is 0, \fBgetmsg()\fR retrieves any message available on the stream head read queue. In this case, on return, the integer pointed to by \fIflagsp\fR will be set to \fBRS_HIPRI\fR if a high priority message was retrieved, or to 0 otherwise. .sp .LP For \fBgetpmsg()\fR, the \fIflagsp\fR argument points to a bitmask with the following mutually-exclusive flags defined: \fBMSG_HIPRI\fR, \fBMSG_BAND\fR, and \fBMSG_ANY\fR. Like \fBgetmsg()\fR, \fBgetpmsg()\fR processes the first available message on the stream head read queue. A user may choose to retrieve only high-priority messages by setting the integer pointed to by \fIflagsp\fR to \fBMSG_HIPRI\fR and the integer pointed to by \fIbandp\fR to 0. In this case, \fBgetpmsg()\fR will only process the next message if it is a high-priority message. In a similar manner, a user may choose to retrieve a message from a particular priority band by setting the integer pointed to by \fIflagsp\fR to \fBMSG_BAND\fR and the integer pointed to by \fIbandp\fR to the priority band of interest. In this case, \fBgetpmsg()\fR will only process the next message if it is in a priority band equal to, or greater than, the integer pointed to by \fIbandp\fR, or if it is a high-priority message. If a user just wants to get the first message off the queue, the integer pointed to by \fIflagsp\fR should be set to \fBMSG_ANY\fR and the integer pointed to by \fIbandp\fR should be set to 0. On return, if the message retrieved was a high-priority message, the integer pointed to by \fIflagsp\fR will be set to \fBMSG_HIPRI\fR and the integer pointed to by \fIbandp\fR will be set to 0. Otherwise, the integer pointed to by \fIflagsp\fR will be set to \fBMSG_BAND\fR and the integer pointed to by \fIbandp\fR will be set to the priority band of the message. .sp .LP If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBgetmsg()\fR blocks until a message of the type specified by \fIflagsp\fR is available on the stream head read queue. If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR has been set and a message of the specified type is not present on the read queue, \fBgetmsg()\fR fails and sets \fBerrno\fR to \fBEAGAIN\fR. .sp .LP If a hangup occurs on the stream from which messages are to be retrieved, \fBgetmsg()\fR continues to operate normally, as described above, until the stream head read queue is empty. Thereafter, it returns 0 in the \fBlen\fR member of \fIctlptr\fR and \fIdataptr\fR. .SH RETURN VALUES .sp .LP Upon successful completion, a non-negative value is returned. A return value of \fB0\fR indicates that a full message was read successfully. A return value of \fBMORECTL\fR indicates that more control information is waiting for retrieval. A return value of \fBMOREDATA\fR indicates that more data are waiting for retrieval. A return value of \fBMORECTL\fR | \fBMOREDATA\fR indicates that both types of information remain. Subsequent \fBgetmsg()\fR calls retrieve the remainder of the message. However, if a message of higher priority has been received by the stream head read queue, the next call to \fBgetmsg()\fR will retrieve that higher priority message before retrieving the remainder of the previously received partial message. .SH ERRORS .sp .LP The \fBgetmsg()\fR and \fBgetpmsg()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBEADI\fR\fR .ad .RS 11n .rt The user-specified buffer for the data part of a message is enabled for ADI, and an ADI version mismatch is detected while the system writes data to the buffer. For more information, see the \fBadi\fR(3C) man page. .RE .sp .ne 2 .mk .na \fB\fBEAGAIN\fR\fR .ad .RS 11n .rt The \fBO_NDELAY\fR or \fBO_NONBLOCK\fR flag is set and no messages are available. .RE .sp .ne 2 .mk .na \fB\fBEBADF\fR\fR .ad .RS 11n .rt The \fIfildes\fR argument is not a valid file descriptor open for reading. .RE .sp .ne 2 .mk .na \fB\fBEBADMSG\fR\fR .ad .RS 11n .rt Queued message to be read is not valid for \fBgetmsg\fR. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 11n .rt The \fIctlptr\fR, \fIdataptr\fR, \fIbandp\fR, or \fIflagsp\fR argument points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBEINTR\fR\fR .ad .RS 11n .rt A signal was caught during the execution of the \fBgetmsg\fR function. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 11n .rt An illegal value was specified in \fIflagsp\fR, or the stream referenced by \fIfildes\fR is linked under a multiplexor. .RE .sp .ne 2 .mk .na \fB\fBENOSTR\fR\fR .ad .RS 11n .rt A stream is not associated with \fIfildes\fR. .RE .sp .LP The \fBgetmsg()\fR function can also fail if a STREAMS error message has been received at the stream head before the call to \fBgetmsg()\fR. The error returned is the value contained in the STREAMS error message. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(7) for description of the following attribute: .sp .TS tab( ) box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Committed _ Standard See \fBstandards\fR(7). .TE .sp .SH SEE ALSO .sp .LP \fBIntro\fR(2), \fBpoll\fR(2), \fBputmsg\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(7), \fBstandards\fR(7) .sp .LP \fISTREAMS Programming Guide\fR .SH HISTORY .sp .LP The \fBgetmsg()\fR function has been included in all Sun and Oracle releases of Solaris. .sp .LP The \fBgetpmsg()\fR function has been included in Solaris since the Solaris 2.0 release.