msgget Subroutine

Edit online

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.

Limits on message size and number of messages in the queue can be found in General Programming Concepts: Writing and Debugging Programs.

Parameters

Item Description
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:

Item Description
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.