diff options
Diffstat (limited to 'man3p/msgrcv.3p')
| -rw-r--r-- | man3p/msgrcv.3p | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/man3p/msgrcv.3p b/man3p/msgrcv.3p new file mode 100644 index 000000000..7104a8f75 --- /dev/null +++ b/man3p/msgrcv.3p @@ -0,0 +1,214 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MSGRCV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" msgrcv +.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 . |