msgxrcv() — Extended message receive operation
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);
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.
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.
- 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.
- 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.
- 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.
- 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.