[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1

kmsgrcv Kernel Service

Purpose

Reads a message from a message queue.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int kmsgrcv 
(msqid, msgp, msgsz, 
msgtyp, msgflg, flags, bytes)
int msqid;
struct msgxbuf *msgp; 
   or struct msgbuf *msgp;
int msgsz;
mtyp_t msgtyp;
int msgflg;
int flags;
int *bytes;

Parameters

msqid Specifies the message queue from which to read.
msgp Points to either an msgxbuf or an msgbuf structure where the message text is placed. The type of structure pointed to is determined by the values of the flags parameter. These structures are defined in the /usr/include/sys/msg.h file.
msgsz Specifies the maximum number of bytes of text to be received from the message queue. The received message is truncated to the size specified by the msgsz parameter if the message is longer than this size and MSG_NOERROR is set in the msgflg parameter. The truncated part of the message is lost and no indication of the truncation is given to the calling process.
msgtyp Specifies the type of message requested as follows:
  • If the msgtyp parameter is equal to 0, the first message on the queue is received.
  • If the msgtyp parameter is greater than 0, the first message of the type specified by the msgtyp parameter is received.
  • If the msgtyp parameter is less than 0, the first message of the lowest type that is less than or equal to the absolute value of the msgtyp parameter is received.
msgflg Specifies a value of 0, or is constructed by logically ORing one of several values:
MSG_NOERROR Truncates the message if it is longer than the number of bytes specified by the msgsz parameter.
IPC_NOWAIT Specifies the action to take if a message of the desired type is not on the queue:
  • If IPC_NOWAIT is set, then the kmsgrcv service returns an ENOMSG value.
  • If IPC_NOWAIT is not set, then the calling process suspends execution until one of the following occurs:
    • A message of the desired type is placed on the queue.
    • The message queue ID specified by the msqid parameter is removed from the system. When this occurs, the kmsgrcv service returns an EIDRM value.
    • The calling process receives a signal that is to be caught. In this case, a message is not received and the kmsgrcv service returns an EINTR value.
flags Specifies a value of 0 if a normal message receive is to be performed. If an extended message receive is to be performed, this flag should be set to an XMSG value. With this flag set, the kmsgrcv service functions as the msgxrcv subroutine would. Otherwise, the kmsgrcv service functions as the msgrcv subroutine would.
bytes Specifies a reference parameter. This parameter contains the number of message-text bytes read from the message queue upon return from the kmsgrcv service.

If the message is longer than the number of bytes specified by the msgsz parameter bytes but MSG_NOERROR is not set, then the kmsgrcv kernel service fails and returns an E2BIG return value.

Description

The kmsgrcv kernel service reads a message from the queue specified by the msqid parameter and stores the message into the structure pointed to by the msgp parameter. The kmsgrcv kernel service provides the same functions for user-mode processes in kernel mode as the msgrcv and msgxrcv subroutines perform for kernel processes or user-mode processes in user mode.

The kmsgrcv service can be called by a user-mode process in kernel mode or by a kernel process. A kernel process can also call the msgrcv and msgxrcv subroutines to provide the same functions.

Execution Environment

The kmsgrcv kernel service can be called from the process environment only.

Return Values

0 Indicates a successful operation.
EINVAL Indicates that the ID specified by the msqid parameter is not a valid message queue ID.
EACCES Indicates that operation permission is denied to the calling process.
EINVAL Indicates that the value of the msgsz parameter is less than 0.
E2BIG Indicates that the message text is greater than the maximum length specified by the msgsz parameter and MSG_NOERROR is not set.
ENOMSG Indicates that the queue does not contain a message of the desired type and IPC_NOWAIT is set.
EINTR Indicates that the kmsgrcv service received a signal.
EIDRM Indicates that the message queue ID specified by the msqid parameter has been removed from the system.

Implementation Specifics

The kmsgrcv kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The msgrcv subroutine, msgxrcv subroutine.

Message Queue Kernel Services in AIX Kernel Extensions and Device Support Programming Concepts.

Understanding System Call Execution in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]