Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
|
Format
#define _OPEN_SYS_IPC_EXTENSIONS
#include <sys/msg.h>
int msgxrcv(int msgid, void *msgp, size_t msgsz, long int msgtyp, int msgflg);
Note: To expose the msgxrcv() name, the feature test macro _OPEN_SYS_IPC_EXTENSIONS should be defined. Otherwise,
the function's name is __msgxrcv().
General
description
The msgxrcv() function reads an extended message from the queue
associated with the message queue identifier specified by msgid and
places it in the user-defined buffer pointed to by msgp.
The argument
msgp points to a user-defined buffer where
the extended message will be received. This buffer must be defined
by a data structure of the following format:
.
struct msgxbuf {
time_t mtime; Time and date message was sent
uid_t muid; Sender's effective user ID
gid_t mgid; Sender's effective group ID
pid_t mpid; Sender's process ID
long int mtype; Message type
int mtext[n]; Message text
}
The structure member, mtype, is the received message's
type as specified by the sending process. The structure member, mtext,
is the text of the message.
The argument msgsz specifies the size in bytes of mtext,
The received message is truncated to msgsz bytes if it is
larger than msgsz and the MSG_NOERROR flag was specified in the argument msgflg. The truncated
portion of the message is lost and no indication of the truncation
is given to the calling process.
The argument
msgtyp specifies the type of message requested,
as follows:
- If msgtyp is equal to zero, the first message on the
queue is received.
- If msgtyp is greater than 0, the first message of type, msgtyp,
is received.
- If msgtyp is less than 0, the first message of the lowest
type that is less than or equal to the absolute value of msgtyp is
received.
The argument
msgflg specifies the action to be taken if
a message of the desired type is not on the queue. These are as follows:
- If the IPC_NOWAIT flag is on in msgflg,
the calling process will return immediately with a return value of -1
and errno set to ENOMSG.
- If the IPC_NOWAIT flag is off in msgflg the calling process
will suspend execution until one of the following occurs:
- A message of the desired type is placed on the queue.
- The message queue identifier, msgid, is removed from
the system; when this occurs, errno is set to EIDRM and a value of -1
is returned.
- The calling process receives a signal that is to be caught; in
this case a message is not received and the calling process resumes
execution. A value of -1 is returned and errno is set to EINTR.
If successful, the following actions are taken with respect to
the data structure,
msqid_ds, associated with
msgid:
- msg_qnum is decremented by 1.
- msg_lrpid is set equal to the process ID of the calling
process.
- msg_rtime is set equal to the current time.
Returned value
If successful, msgxrcv() returns a value equal to the number of
bytes actually placed into the mtext field of the user-defined
buffer pointed to by msgp. A value of zero indicates that
only the mtype field was received from the message queue.
If unsuccessful, msgxrcv() returns -1 and sets errno to one
of the following values:
- Error Code
- Description
- E2BIG
- The value of mtext is greater than msgsz and
the flag MSG_NOERROR was not specified.
- EACCES
- The calling process does not have read permission to the message
queue associated with the message queue identifier msgid.
- EIDRM
- The message queue identifier, msgid, has been removed
from the system while the caller of msgxrcv() was waiting.
- EINTR
- The function msgxrcv() was interrupted by a signal before a
message could be received.
- EINVAL
- The value of argument msgid is not a valid message
queue identifier or the value of msgsz is less than zero.
- ENOMSG
- The flag IPC_NOWAIT was specified and
the message queue does not contain a message of the desired type.