msgget()--Get Message Queue
Syntax
#include <sys/msg.h> #include <sys/stat.h> int msgget(key_t key, int msgflg);
Service Program Name: QP0ZUSHR
Default Public Authority: *USE
Threadsafe: Yes
The msgget() function either creates a new message queue or returns the message queue identifier associated with the key parameter for an existing message queue. A new message queue is created if one of the following is true:
- The key parameter is equal to IPC_PRIVATE.
- The key parameter does not already have a message queue identifier
associated with it and the IPC_CREAT flag is specified in the msgflg parameter.
The system maintains status information about a message queue which can be retrieved with the msgctl() function. When a new message queue is created, the system initializes the members of the msqid_ds structure as follows:
- msg_perm.cuid and msg_perm.uid are set equal to
the effective user ID of the calling thread.
- msg_perm.cgid and msg_perm.gid are set equal to
the effective group ID of the calling thread.
- The low-order 9 bits of msg_perm.mode are set equal to the
low-order 9 bits of the msgflg parameter.
- msg_qbytes is set equal to the system limit.
- msg_ctime is set equal to the current time.
- msg_qnum, msg_lspid, msg_lrpid,
msg_stime, and msg_rtime are set equal to 0.
Parameters
- key
- (Input) Key associated with the message queue. A key of
IPC_PRIVATE (0x00000000) guarantees that a unique message queue is created. A key also can
be specified by the caller or generated by the ftok()
function.
- msgflg
- (Input) Operations and permissions flag. The value of msgflg is either zero or is obtained by performing an OR operation on one or more of the following constants:
- S_IRUSR (0x00000100)
- Allow the owner of the message queue to read from it.
- S_IWUSR (0x00000080)
- Allow the owner of the message queue to write to it.
- S_IRGRP (0x00000020)
- Allow the group of the message queue to read from it.
- S_IWGRP (0x00000010)
- Allow the group of the message queue to write to it.
- S_IROTH (0x00000004)
- Allow others to read from the message queue.
- S_IWOTH (0x00000002)
- Allow others to write to the message queue.
- IPC_CREAT (0x00000200)
- Create the message queue if it does not exist.
- IPC_EXCL (0x00000400)
- Return an error if the IPC_CREAT flag is set and the message queue already exists.
Authorities
Authorization Required for msgget()
Object Referred to | Authority Required | errno |
---|---|---|
Message queue to be created | None | None |
Existing message queue to be accessed | See Note | EACCES |
Note: If the thread is accessing an existing message queue, the mode specified in the last 9 bits of msgflg must be a subset of the mode of the existing message queue.
Return Value
value | msgget() was successful. The value returned is the message queue identifier associated with the key parameter. |
-1 | msgget() was not successful. The errno variable is set to indicate the error. |
Error Conditions
If msgget() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
- [EACCES]
-
Permission denied.
An attempt was made to access an object in a way forbidden by its object access permissions.
The thread does not have access to the specified file, directory, component, or path.
A message queue identifier exists for the parameter key, but permissions specified in the low-order 9 bits of semflg are not a subset of the current permissions.
- [EDAMAGE]
-
A damaged object was encountered.
A referenced object is damaged. The object cannot be used.
The message queue has been damaged by a previous message queue operation.
- [EEXIST]
-
File exists.
The file specified already exists and the specified operation requires that it not exist.
The named file, directory, or path already exists.
A message queue identifier exists for the key parameter and both the IPC_CREAT and IPC_EXCL flags are set in the msgflg parameter.
- [ENOENT]
-
No such path or directory.
The directory or a component of the path name specified does not exist.
A named file or directory does not exist or is an empty string.
A message queue identifier does not exist for the key parameter, and the IPC_CREAT flag is not set in the msgflg parameter.
- [ENOSPC]
-
No space available.
The requested operations required additional space on the device and there is no space left. This could also be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.
Insufficient space remains to hold the intended file, directory, or link.
A message queue identifier cannot be created because the system limit on the maximum number of allowed message queue identifiers would be exceeded.
- [EUNKNOWN]
-
Unknown system state.
The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.
Error Messages
None.
Usage Notes
- The best way to generate a unique key is to use the ftok() function.
Related Information
- The <sys/msg.h> file (see
Header Files for UNIX®-Type Functions)
- Message Queue Functions for the current system limits.
- ftok()--Generate IPC Key from File Name
- msgctl()--Perform Message Control Operations
- msgrcv()--Receive Message Operation
- msgsnd()--Send Message Operation
Example
The following example creates a message queue.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <sys/msg.h> #include <sys/stat.h> main() { int msqid; msqid = msgget(IPC_PRIVATE, IPC_CREAT | S_IRUSR | S_IWUSR); }
API introduced: V3R6