kmsgctl Kernel Service

Purpose

Provides message-queue control operations.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/ipc.h>
#include <sys/msg.h>

int kmsgctl ( msqid, cmd, buf) int msqid, cmd; struct msqid_ds *buf;

Parameters

Item	Description
msqid	Specifies the message queue ID, which indicates the message queue for which the control operation is being requested for.
cmd	Specifies which control operation is being requested. There are three valid commands.
buf	Points to the msqid_ds structure provided by the caller of the kmsgctl service. Data is obtained either from this structure or from status returned in this structure, depending on the cmd parameter. The msqid_ds structure is defined in the /usr/include/sys/msg.h file.

Description

The kmsgctl kernel service provides a variety of message-queue control operations as specified by the cmd parameter. The kmsgctl kernel service provides the same functions for user-mode processes in kernel mode as the msgctl subroutine performs for kernel processes or user-mode processes in user mode. The kmsgctl service can be called by a user-mode process in kernel mode or by a kernel process. A kernel process can also call the msgctl subroutine to provide the same function.

The following three commands can be specified with the cmd parameter:

Item	Description
IPC_STAT	Sets only documented fields. See the msgctl subroutine.
IPC_SET	Sets the value of the following fields of the data structure associated with the msqid parameter to the corresponding values found in the structure pointed to by the buf parameter: `msg_perm.uid` `msg_perm.gid` `msg_perm.mode` (only the low-order 9 bits) `msg_qbytes` To perform the IPC_SET operation, the current process must have an effective user ID equal to the value of the `msg_perm.uid` or `msg_perm.cuid` field in the data structure associated with the msqid parameter. To raise the value of the `msg_qbytes` field, the calling process must have the appropriate system privilege.
IPC_RMID	Removes from the system the message-queue identifier specified by the msqid parameter. This operation also destroys both the message queue and the data structure associated with it. To perform this operation, the current process must have an effective user ID equal to the value of the `msg_perm.uid` or `msg_perm.cuid` field in the data structure associated with the msqid parameter.

Item

Description

IPC_STAT

Sets only documented fields. See the msgctl subroutine.

IPC_SET

Sets the value of the following fields of the data structure associated with the msqid parameter to the corresponding values found in the structure pointed to by the buf parameter:

msg_perm.uid
msg_perm.gid
msg_perm.mode (only the low-order 9 bits)
msg_qbytes

To perform the IPC_SET operation, the current process must have an effective user ID equal to the value of the msg_perm.uid or msg_perm.cuid field in the data structure associated with the msqid parameter. To raise the value of the msg_qbytes field, the calling process must have the appropriate system privilege.

IPC_RMID

Removes from the system the message-queue identifier specified by the msqid parameter. This operation also destroys both the message queue and the data structure associated with it. To perform this operation, the current process must have an effective user ID equal to the value of the msg_perm.uid or msg_perm.cuid field in the data structure associated with the msqid parameter.

Execution Environment

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

Return Values

Item	Description
0	Indicates successful completion.
EINVAL	Indicates either The identifier specified by the msqid parameter is not a valid message queue identifier. The command specified by the cmd parameter is not a valid command.
EACCES	The command specified by the cmd parameter is equal to IPC_STAT and read permission is denied to the calling process.
EPERM	The command specified by the cmd parameter is equal to IPC_RMID, IPC_SET, and the effective user ID of the calling process is not equal to that of the value of the `msg_perm.uid` field in the data structure associated with the msqid parameter.
EPERM	Indicates the following conditions: The command specified by the cmd parameter is equal to IPC_SET. An attempt is being made to increase to the value of the `msg_qbytes` field, but the calling process does not have the appropriate system privilege.