diff options
Diffstat (limited to 'man3p/getmsg.3p')
| -rw-r--r-- | man3p/getmsg.3p | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/man3p/getmsg.3p b/man3p/getmsg.3p new file mode 100644 index 000000000..683a99429 --- /dev/null +++ b/man3p/getmsg.3p @@ -0,0 +1,278 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getmsg +.SH NAME +getmsg, getpmsg \- receive next message from a STREAMS file (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include <stropts.h> +.br +.sp +int getmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB, +.br +\ \ \ \ \ \ struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP +\fIflagsp\fP\fB); +.br +int getpmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB, +.br +\ \ \ \ \ \ struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP +\fIbandp\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIflagsp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetmsg\fP() function shall retrieve the contents of a message +located at the head of the STREAM head read queue +associated with a STREAMS file and place the contents into one or +more buffers. The message contains either a data part, a control +part, or both. The data and control parts of the message shall be +placed into separate buffers, as described below. The semantics +of each part are defined by the originator of the message. +.LP +The \fIgetpmsg\fP() function shall be equivalent to \fIgetmsg\fP(), +except that it provides finer control over the priority of +the messages received. Except where noted, all requirements on \fIgetmsg\fP() +also pertain to \fIgetpmsg\fP(). +.LP +The \fIfildes\fP argument specifies a file descriptor referencing +a STREAMS-based file. +.LP +The \fIctlptr\fP and \fIdataptr\fP arguments each point to a \fBstrbuf\fP +structure, in which the \fIbuf\fP member points to +a buffer in which the data or control information is to be placed, +and the \fImaxlen\fP member indicates the maximum number of +bytes this buffer can hold. On return, the \fIlen\fP member shall +contain the number of bytes of data or control information +actually received. The \fIlen\fP member shall be set to 0 if there +is a zero-length control or data part and \fIlen\fP shall be +set to -1 if no data or control information is present in the message. +.LP +When \fIgetmsg\fP() is called, \fIflagsp\fP should point to an integer +that indicates the type of message the process is able +to receive. This is described further below. +.LP +The \fIctlptr\fP argument is used to hold the control part of the +message, and \fIdataptr\fP is used to hold the data part of +the message. If \fIctlptr\fP (or \fIdataptr\fP) is a null pointer +or the \fImaxlen\fP member is -1, the control (or data) part +of the message shall not be processed and shall be left on the STREAM +head read queue, and if the \fIctlptr\fP (or \fIdataptr\fP) +is not a null pointer, \fIlen\fP shall be set to -1. If the \fImaxlen\fP +member is set to 0 and there is a zero-length control +(or data) part, that zero-length part shall be removed from the read +queue and \fIlen\fP shall be set to 0. If the \fImaxlen\fP +member is set to 0 and there are more than 0 bytes of control (or +data) information, that information shall be left on the read +queue and \fIlen\fP shall be set to 0. If the \fImaxlen\fP member +in \fIctlptr\fP (or \fIdataptr\fP) is less than the control +(or data) part of the message, \fImaxlen\fP bytes shall be retrieved. +In this case, the remainder of the message shall be left on +the STREAM head read queue and a non-zero return value shall be provided. +.LP +By default, \fIgetmsg\fP() shall process the first available message +on the STREAM head read queue. However, a process may +choose to retrieve only high-priority messages by setting the integer +pointed to by \fIflagsp\fP to RS_HIPRI. In this case, +\fIgetmsg\fP() shall only process the next message if it is a high-priority +message. When the integer pointed to by \fIflagsp\fP +is 0, any available message shall be retrieved. In this case, on return, +the integer pointed to by \fIflagsp\fP shall be set to +RS_HIPRI if a high-priority message was retrieved, or 0 otherwise. +.LP +For \fIgetpmsg\fP(), the flags are different. The \fIflagsp\fP argument +points to a bitmask with the following +mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. +Like \fIgetmsg\fP(), \fIgetpmsg\fP() shall process the first +available message on the STREAM head read queue. A process may choose +to retrieve only high-priority messages by setting the +integer pointed to by \fIflagsp\fP to MSG_HIPRI and the integer pointed +to by \fIbandp\fP to 0. In this case, \fIgetpmsg\fP() +shall only process the next message if it is a high-priority message. +In a similar manner, a process may choose to retrieve a +message from a particular priority band by setting the integer pointed +to by \fIflagsp\fP to MSG_BAND and the integer pointed to +by \fIbandp\fP to the priority band of interest. In this case, \fIgetpmsg\fP() +shall only process the next message if it is in a +priority band equal to, or greater than, the integer pointed to by +\fIbandp\fP, or if it is a high-priority message. If a process +wants to get the first message off the queue, the integer pointed +to by \fIflagsp\fP should be set to MSG_ANY and the integer +pointed to by \fIbandp\fP should be set to 0. On return, if the message +retrieved was a high-priority message, the integer pointed +to by \fIflagsp\fP shall be set to MSG_HIPRI and the integer pointed +to by \fIbandp\fP shall be set to 0. Otherwise, the integer +pointed to by \fIflagsp\fP shall be set to MSG_BAND and the integer +pointed to by \fIbandp\fP shall be set to the priority band +of the message. +.LP +If O_NONBLOCK is not set, \fIgetmsg\fP() and \fIgetpmsg\fP() shall +block until a message of the type specified by +\fIflagsp\fP is available at the front of the STREAM head read queue. +If O_NONBLOCK is set and a message of the specified type is +not present at the front of the read queue, \fIgetmsg\fP() and \fIgetpmsg\fP() +shall fail and set \fIerrno\fP to [EAGAIN]. +.LP +If a hangup occurs on the STREAM from which messages are retrieved, +\fIgetmsg\fP() and \fIgetpmsg\fP() shall continue to +operate normally, as described above, until the STREAM head read queue +is empty. Thereafter, they shall return 0 in the \fIlen\fP +members of \fIctlptr\fP and \fIdataptr\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetmsg\fP() and \fIgetpmsg\fP() shall +return a non-negative value. A value of 0 indicates that +a full message was read successfully. A return value of MORECTL indicates +that more control information is waiting for retrieval. A +return value of MOREDATA indicates that more data is waiting for retrieval. +A return value of the bitwise-logical OR of MORECTL and +MOREDATA indicates that both types of information remain. Subsequent +\fIgetmsg\fP() and \fIgetpmsg\fP() calls shall retrieve the +remainder of the message. However, if a message of higher priority +has come in on the STREAM head read queue, the next call to +\fIgetmsg\fP() or \fIgetpmsg\fP() shall retrieve that higher-priority +message before retrieving the remainder of the previous +message. +.LP +If the high priority control part of the message is consumed, the +message shall be placed back on the queue as a normal message +of band 0. Subsequent \fIgetmsg\fP() and \fIgetpmsg\fP() calls shall +retrieve the remainder of the message. If, however, a +priority message arrives or already exists on the STREAM head, the +subsequent call to \fIgetmsg\fP() or \fIgetpmsg\fP() shall +retrieve the higher-priority message before retrieving the remainder +of the message that was put back. +.LP +Upon failure, \fIgetmsg\fP() and \fIgetpmsg\fP() shall return -1 and +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIgetmsg\fP() and \fIgetpmsg\fP() functions shall fail if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set and no messages are available. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor open for +reading. +.TP 7 +.B EBADMSG +The queued message to be read is not valid for \fIgetmsg\fP() or \fIgetpmsg\fP() +or a pending file descriptor is at the +STREAM head. +.TP 7 +.B EINTR +A signal was caught during \fIgetmsg\fP() or \fIgetpmsg\fP(). +.TP 7 +.B EINVAL +An illegal value was specified by \fIflagsp\fP, or the STREAM or multiplexer +referenced by \fIfildes\fP is linked (directly +or indirectly) downstream from a multiplexer. +.TP 7 +.B ENOSTR +A STREAM is not associated with \fIfildes\fP. +.sp +.LP +In addition, \fIgetmsg\fP() and \fIgetpmsg\fP() shall fail if the +STREAM head had processed an asynchronous error before the +call. In this case, the value of \fIerrno\fP does not reflect the +result of \fIgetmsg\fP() or \fIgetpmsg\fP() but reflects the +prior error. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting Any Message +.LP +In the following example, the value of \fIfd\fP is assumed to refer +to an open STREAMS file. The call to \fIgetmsg\fP() +retrieves any available message on the associated STREAM-head read +queue, returning control and data information to the buffers +pointed to by \fIctrlbuf\fP and \fIdatabuf\fP, respectively. +.sp +.RS +.nf + +\fB#include <stropts.h> +\&... +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int flags = 0; +int ret; +.sp + +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.sp + +data.buf = databuf; +data.maxlen = sizeof(databuf); +.sp + +ret = getmsg (fd, &ctrl, &data, &flags); +\fP +.fi +.RE +.SS Getting the First Message off the Queue +.LP +In the following example, the call to \fIgetpmsg\fP() retrieves the +first available message on the associated STREAM-head read +queue. +.sp +.RS +.nf + +\fB#include <stropts.h> +\&... +.sp + +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int band = 0; +int flags = MSG_ANY; +int ret; +.sp + +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.sp + +data.buf = databuf; +data.maxlen = sizeof(databuf); +.sp + +ret = getpmsg (fd, &ctrl, &data, &band, &flags); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIpoll\fP() , \fIputmsg\fP() , \fIread\fP() , \fIwrite\fP() +, the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<stropts.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |