mirror of https://github.com/mkerrisk/man-pages
220 lines
6.8 KiB
Plaintext
220 lines
6.8 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "MSGRCV" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" msgrcv
|
|
.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
|
|
msgrcv \- XSI message receive operation
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <sys/msg.h>
|
|
.br
|
|
.sp
|
|
ssize_t msgrcv(int\fP \fImsqid\fP\fB, void *\fP\fImsgp\fP\fB, size_t\fP
|
|
\fImsgsz\fP\fB, long\fP
|
|
\fImsgtyp\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ int\fP \fImsgflg\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fImsgrcv\fP() function operates on XSI message queues (see the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
Section 3.224, Message Queue). It is unspecified whether this function
|
|
interoperates with the realtime interprocess communication facilities
|
|
defined in \fIRealtime\fP .
|
|
.LP
|
|
The \fImsgrcv\fP() function shall read a message from the queue associated
|
|
with the message queue identifier specified by
|
|
\fImsqid\fP and place it in the user-defined buffer pointed to by
|
|
\fImsgp\fP.
|
|
.LP
|
|
The application shall ensure that the argument \fImsgp\fP points to
|
|
a user-defined buffer that contains first a field of type
|
|
\fBlong\fP specifying the type of the message, and then a data portion
|
|
that holds the data bytes of the message. The structure
|
|
below is an example of what this user-defined buffer might look like:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBstruct mymsg {
|
|
long mtype; /* Message type. */
|
|
char mtext[1]; /* Message text. */
|
|
}
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The structure member \fImtype\fP is the received message's type as
|
|
specified by the sending process.
|
|
.LP
|
|
The structure member \fImtext\fP is the text of the message.
|
|
.LP
|
|
The argument \fImsgsz\fP specifies the size in bytes of \fImtext\fP.
|
|
The received message shall be truncated to \fImsgsz\fP
|
|
bytes if it is larger than \fImsgsz\fP and (\fImsgflg\fP & MSG_NOERROR)
|
|
is non-zero. The truncated part of the message shall
|
|
be lost and no indication of the truncation shall be given to the
|
|
calling process.
|
|
.LP
|
|
If the value of \fImsgsz\fP is greater than {SSIZE_MAX}, the result
|
|
is implementation-defined.
|
|
.LP
|
|
The argument \fImsgtyp\fP specifies the type of message requested
|
|
as follows:
|
|
.IP " *" 3
|
|
If \fImsgtyp\fP is 0, the first message on the queue shall be received.
|
|
.LP
|
|
.IP " *" 3
|
|
If \fImsgtyp\fP is greater than 0, the first message of type \fImsgtyp\fP
|
|
shall be received.
|
|
.LP
|
|
.IP " *" 3
|
|
If \fImsgtyp\fP is less than 0, the first message of the lowest type
|
|
that is less than or equal to the absolute value of
|
|
\fImsgtyp\fP shall be received.
|
|
.LP
|
|
.LP
|
|
The argument \fImsgflg\fP specifies the action to be taken if a message
|
|
of the desired type is not on the queue. These are as
|
|
follows:
|
|
.IP " *" 3
|
|
If (\fImsgflg\fP & IPC_NOWAIT) is non-zero, the calling thread shall
|
|
return immediately with a return value of -1 and
|
|
\fIerrno\fP set to [ENOMSG].
|
|
.LP
|
|
.IP " *" 3
|
|
If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend
|
|
execution until one of the following occurs:
|
|
.RS
|
|
.IP " *" 3
|
|
A message of the desired type is placed on the queue.
|
|
.LP
|
|
.IP " *" 3
|
|
The message queue identifier \fImsqid\fP is removed from the system;
|
|
when this occurs, \fIerrno\fP shall be set equal to
|
|
[EIDRM] and -1 shall be returned.
|
|
.LP
|
|
.IP " *" 3
|
|
The calling thread receives a signal that is to be caught; in this
|
|
case a message is not received and the calling thread resumes
|
|
execution in the manner prescribed in \fIsigaction\fP() .
|
|
.LP
|
|
.RE
|
|
.LP
|
|
.LP
|
|
Upon successful completion, the following actions are taken with respect
|
|
to the data structure associated with \fImsqid\fP:
|
|
.IP " *" 3
|
|
\fBmsg_qnum\fP shall be decremented by 1.
|
|
.LP
|
|
.IP " *" 3
|
|
\fBmsg_lrpid\fP shall be set equal to the process ID of the calling
|
|
process.
|
|
.LP
|
|
.IP " *" 3
|
|
\fBmsg_rtime\fP shall be set equal to the current time.
|
|
.LP
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fImsgrcv\fP() shall return a value equal
|
|
to the number of bytes actually placed into the buffer
|
|
\fImtext\fP. Otherwise, no message shall be received, \fImsgrcv\fP()
|
|
shall return (\fBssize_t\fP)-1, and \fIerrno\fP shall be
|
|
set to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fImsgrcv\fP() function shall fail if:
|
|
.TP 7
|
|
.B E2BIG
|
|
The value of \fImtext\fP is greater than \fImsgsz\fP and (\fImsgflg\fP
|
|
& MSG_NOERROR) is 0.
|
|
.TP 7
|
|
.B EACCES
|
|
Operation permission is denied to the calling process; see \fIXSI
|
|
Interprocess
|
|
Communication\fP .
|
|
.TP 7
|
|
.B EIDRM
|
|
The message queue identifier \fImsqid\fP is removed from the system.
|
|
.TP 7
|
|
.B EINTR
|
|
The \fImsgrcv\fP() function was interrupted by a signal.
|
|
.TP 7
|
|
.B EINVAL
|
|
\fImsqid\fP is not a valid message queue identifier.
|
|
.TP 7
|
|
.B ENOMSG
|
|
The queue does not contain a message of the desired type and (\fImsgflg\fP
|
|
& IPC_NOWAIT) is non-zero.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Receiving a Message
|
|
.LP
|
|
The following example receives the first message on the queue (based
|
|
on the value of the \fImsgtyp\fP argument, 0). The queue
|
|
is identified by the \fImsqid\fP argument (assuming that the value
|
|
has previously been set). This call specifies that an error
|
|
should be reported if no message is available, but not if the message
|
|
is too large. The message size is calculated directly using
|
|
the \fIsizeof\fP operator.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <sys/msg.h>
|
|
\&...
|
|
int result;
|
|
int msqid;
|
|
struct message {
|
|
long type;
|
|
char text[20];
|
|
} msg;
|
|
long msgtyp = 0;
|
|
\&...
|
|
result = msgrcv(msqid, (void *) &msg, sizeof(msg.text),
|
|
msgtyp, MSG_NOERROR | IPC_NOWAIT);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The POSIX Realtime Extension defines alternative interfaces for interprocess
|
|
communication (IPC). Application developers who
|
|
need to use IPC should design their applications so that modules using
|
|
the IPC routines described in \fIXSI Interprocess Communication\fP
|
|
can be easily modified to use the alternative
|
|
interfaces.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIXSI Interprocess Communication\fP, \fIRealtime\fP, \fImq_close\fP()
|
|
, \fImq_getattr\fP(), \fImq_notify\fP(), \fImq_open\fP(), \fImq_receive\fP()
|
|
, \fImq_send\fP(), \fImq_setattr\fP(), \fImq_unlink\fP(), \fImsgctl\fP()
|
|
, \fImsgget\fP(),
|
|
\fImsgsnd\fP(), \fIsigaction\fP(), the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<sys/msg.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 .
|