Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 412 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3p/getmsg.3p b/upstream/mageia-cauldron/man3p/getmsg.3p
new file mode 100644
index 00000000..aff2b244
--- /dev/null
+++ b/upstream/mageia-cauldron/man3p/getmsg.3p
@@ -0,0 +1,412 @@
+'\" et
+.TH GETMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+getmsg,
+getpmsg
+\(em receive next message from a STREAMS file (\fBSTREAMS\fP)
+.SH SYNOPSIS
+.LP
+.nf
+#include <stropts.h>
+.P
+int getmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,
+    struct strbuf *restrict \fIdataptr\fP, int *restrict \fIflagsp\fP);
+int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,
+    struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP,
+    int *restrict \fIflagsp\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIgetmsg\fR()
+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.
+.P
+The
+\fIgetpmsg\fR()
+function shall be equivalent to
+\fIgetmsg\fR(),
+except that it provides finer control over the priority of the messages
+received. Except where noted, all requirements on
+\fIgetmsg\fR()
+also pertain to
+\fIgetpmsg\fR().
+.P
+The
+.IR fildes
+argument specifies a file descriptor referencing a STREAMS-based file.
+.P
+The
+.IR ctlptr
+and
+.IR dataptr
+arguments each point to a
+.BR strbuf
+structure, in which the
+.IR buf
+member points to a buffer in which the data or control information is
+to be placed, and the
+.IR maxlen
+member indicates the maximum number of bytes this buffer can hold. On
+return, the
+.IR len
+member shall contain the number of bytes of data or control information
+actually received. The
+.IR len
+member shall be set to 0 if there is a zero-length control or data part
+and
+.IR len
+shall be set to \-1 if no data or control information is present in
+the message.
+.P
+When
+\fIgetmsg\fR()
+is called,
+.IR flagsp
+should point to an integer that indicates the type of message the
+process is able to receive. This is described further below.
+.P
+The
+.IR ctlptr
+argument is used to hold the control part of the message, and
+.IR dataptr
+is used to hold the data part of the message. If
+.IR ctlptr
+(or
+.IR dataptr )
+is a null pointer or the
+.IR maxlen
+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
+.IR ctlptr
+(or
+.IR dataptr )
+is not a null pointer,
+.IR len
+shall be set to \-1. If the
+.IR maxlen
+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
+.IR len
+shall be set to 0. If the
+.IR maxlen
+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
+.IR len
+shall be set to 0. If the
+.IR maxlen
+member in
+.IR ctlptr
+(or
+.IR dataptr )
+is less than the control (or data) part of the message,
+.IR maxlen
+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.
+.P
+By default,
+\fIgetmsg\fR()
+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
+.IR flagsp
+to RS_HIPRI. In this case,
+\fIgetmsg\fR()
+shall only process the next message if it is a high-priority message.
+When the integer pointed to by
+.IR flagsp
+is 0, any available message shall be retrieved. In this case, on
+return, the integer pointed to by
+.IR flagsp
+shall be set to RS_HIPRI if a high-priority message was retrieved, or 0
+otherwise.
+.P
+For
+\fIgetpmsg\fR(),
+the flags are different. The
+.IR flagsp
+argument points to a bitmask with the following mutually-exclusive
+flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
+Like
+\fIgetmsg\fR(),
+\fIgetpmsg\fR()
+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
+.IR flagsp
+to MSG_HIPRI and the integer pointed to by
+.IR bandp
+to 0. In this case,
+\fIgetpmsg\fR()
+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
+.IR flagsp
+to MSG_BAND and the integer pointed to by
+.IR bandp
+to the priority band of interest. In this case,
+\fIgetpmsg\fR()
+shall only process the next message if it is in a priority band equal
+to, or greater than, the integer pointed to by
+.IR bandp ,
+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
+.IR flagsp
+should be set to MSG_ANY and the integer pointed to by
+.IR bandp
+should be set to 0. On return, if the message retrieved was a
+high-priority message, the integer pointed to by
+.IR flagsp
+shall be set to MSG_HIPRI and the integer pointed to by
+.IR bandp
+shall be set to 0. Otherwise, the integer pointed to by
+.IR flagsp
+shall be set to MSG_BAND and the integer pointed to by
+.IR bandp
+shall be set to the priority band of the message.
+.P
+If O_NONBLOCK is not set,
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+shall block until a message of the type specified by
+.IR flagsp
+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\fR()
+and
+\fIgetpmsg\fR()
+shall fail and set
+.IR errno
+to
+.BR [EAGAIN] .
+.P
+If a hangup occurs on the STREAM from which messages are retrieved,
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+shall continue to operate normally, as described above, until the
+STREAM head read queue is empty. Thereafter, they shall return 0 in the
+.IR len
+members of
+.IR ctlptr
+and
+.IR dataptr .
+.SH "RETURN VALUE"
+Upon successful completion,
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+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\fR()
+and
+\fIgetpmsg\fR()
+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\fR()
+or
+\fIgetpmsg\fR()
+shall retrieve that higher-priority message before retrieving the
+remainder of the previous message.
+.P
+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\fR()
+and
+\fIgetpmsg\fR()
+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\fR()
+or
+\fIgetpmsg\fR()
+shall retrieve the higher-priority message before retrieving the
+remainder of the message that was put back.
+.P
+Upon failure,
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+shall return \-1 and set
+.IR errno
+to indicate the error.
+.SH ERRORS
+The
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+functions shall fail if:
+.TP
+.BR EAGAIN
+The O_NONBLOCK flag is set and no messages are available.
+.TP
+.BR EBADF
+The
+.IR fildes
+argument is not a valid file descriptor open for reading.
+.TP
+.BR EBADMSG
+The queued message to be read is not valid for
+\fIgetmsg\fR()
+or
+\fIgetpmsg\fR()
+or a pending file descriptor is at the STREAM head.
+.TP
+.BR EINTR
+A signal was caught during
+\fIgetmsg\fR()
+or
+\fIgetpmsg\fR().
+.TP
+.BR EINVAL
+An illegal value was specified by
+.IR flagsp ,
+or the STREAM or multiplexer referenced by
+.IR fildes
+is linked (directly or indirectly) downstream from a multiplexer.
+.TP
+.BR ENOSTR
+A STREAM is not associated with
+.IR fildes .
+.P
+In addition,
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+shall fail if the STREAM head had processed an asynchronous error
+before the call. In this case, the value of
+.IR errno
+does not reflect the result of
+\fIgetmsg\fR()
+or
+\fIgetpmsg\fR()
+but reflects the prior error.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.SS "Getting Any Message"
+.P
+In the following example, the value of
+.IR fd
+is assumed to refer to an open STREAMS file. The call to
+\fIgetmsg\fR()
+retrieves any available message on the associated STREAM-head read
+queue, returning control and data information to the buffers pointed to
+by
+.IR ctrlbuf
+and
+.IR databuf ,
+respectively.
+.sp
+.RS 4
+.nf
+
+#include <stropts.h>
+\&...
+int fd;
+char ctrlbuf[128];
+char databuf[512];
+struct strbuf ctrl;
+struct strbuf data;
+int flags = 0;
+int ret;
+.P
+ctrl.buf = ctrlbuf;
+ctrl.maxlen = sizeof(ctrlbuf);
+.P
+data.buf = databuf;
+data.maxlen = sizeof(databuf);
+.P
+ret = getmsg (fd, &ctrl, &data, &flags);
+.fi
+.P
+.RE
+.SS "Getting the First Message off the Queue"
+.P
+In the following example, the call to
+\fIgetpmsg\fR()
+retrieves the first available message on the associated STREAM-head
+read queue.
+.sp
+.RS 4
+.nf
+
+#include <stropts.h>
+\&...
+.P
+int fd;
+char ctrlbuf[128];
+char databuf[512];
+struct strbuf ctrl;
+struct strbuf data;
+int band = 0;
+int flags = MSG_ANY;
+int ret;
+.P
+ctrl.buf = ctrlbuf;
+ctrl.maxlen = sizeof(ctrlbuf);
+.P
+data.buf = databuf;
+data.maxlen = sizeof(databuf);
+.P
+ret = getpmsg (fd, &ctrl, &data, &band, &flags);
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+None.
+.SH RATIONALE
+None.
+.SH "FUTURE DIRECTIONS"
+The
+\fIgetmsg\fR()
+and
+\fIgetpmsg\fR()
+functions may be removed in a future version.
+.SH "SEE ALSO"
+.IR "Section 2.6" ", " "STREAMS",
+.IR "\fIpoll\fR\^(\|)",
+.IR "\fIputmsg\fR\^(\|)",
+.IR "\fIread\fR\^(\|)",
+.IR "\fIwrite\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<stropts.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 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 .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .