msgget Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

msgget Subroutine

Purpose

Gets a message queue identifier.

Library

Standard C Library (libc.a)

Syntax

#include <sys/msg.h>

int msgget (Key, MessageFlag)
key_t Key;
int MessageFlag;

Description

The msgget subroutine returns the message queue identifier associated with the specified Key parameter.

A message queue identifier, associated message queue, and data structure are created for the value of the Key parameter if one of the following conditions is true:

The Key parameter is equal to the IPC_PRIVATE value.
The Key parameter does not already have a message queue identifier associated with it, and the IPC_CREAT value is set.

Upon creation, the data structure associated with the new message queue identifier is initialized as follows:

The msg_perm.cuid, msg_perm.uid, msg_perm.cgid, and msg_perm.gid fields are set equal to the effective user ID and effective group ID, respectively, of the calling process.
The low-order 9 bits of the msg_perm.mode field are set equal to the low-order 9 bits of the MessageFlag parameter.
The msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime fields are set equal to 0.
The msg_ctime field is set equal to the current time.
The msg_qbytes field is set equal to the system limit.

The msgget subroutine performs the following actions:

The msgget subroutine either finds or creates (depending on the value of the MessageFlag parameter) a queue with the Key parameter.
The msgget subroutine returns the ID of the queue header to its caller.

The following limits apply to the message queue:

Maximum message size is 4 Mega bytes.
Maximum number of messages per queue is 8192.
Maximum number of message queue IDs is 4096 for AIX releases before 4.3.2 and 131072 for AIX 4.3.2 and following.

Parameters

Key

Specifies either the value IPC_PRIVATE or an Interprocess Communication (IPC) key constructed by the ftok subroutine (or by a similar algorithm).

MessageFlag

Constructed by logically ORing one or more of the following values:

IPC_CREAT: Creates the data structure if it does not already exist.
IPC_EXCL: Causes the msgget subroutine to fail if the IPC_CREAT value is also set and the data structure already exists.
S_IRUSR: Permits the process that owns the data structure to read it.
S_IWUSR: Permits the process that owns the data structure to modify it.
S_IRGRP: Permits the group associated with the data structure to read it.
S_IWGRP: Permits the group associated with the data structure to modify it.
S_IROTH: Permits others to read the data structure.
S_IWOTH: Permits others to modify the data structure.

Values that begin with S_I are defined in the sys/mode.h file and are a subset of the access permissions that apply to files.

Return Values

Upon successful completion, the msgget subroutine returns a message queue identifier. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The msgget subroutine is unsuccessful if any of the following conditions is true:

EACCES	A message queue identifier exists for the Key parameter, but operation permission as specified by the low-order 9 bits of the MessageFlag parameter is not granted.
ENOENT	A message queue identifier does not exist for the Key parameter and the IPC_CREAT value is not set.
ENOSPC	A message queue identifier is to be created, but the system-imposed limit on the maximum number of allowed message queue identifiers system-wide would be exceeded.
EEXIST	A message queue identifier exists for the Key parameter, and both IPC_CREAT and IPC_EXCL values are set.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The ftok subroutine, msgctl subroutine, msgrcv subroutine, msgsnd subroutine, msgxrcv subroutine.

The mode.h file.