msgget() — Get message queue
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
XPG4 |
both |
Format
#define _XOPEN_SOURCE
#include <sys/msg.h>
int msgget(key_t key, int msgflg);General description
The msgget() function returns the message queue identifier associated with the argument key.
A message queue identifier,
associated message queue and data structure (see <sys/msg.h>)
are created for the argument key if one
of the following is true:
- The argument key is equal to IPC_PRIVATE
- The argument key does not already have a message queue identifier associated with it, and the flag IPC_CREAT is on in msgflg.
Valid values for the argument msgflg include
any combination of the following constants defined in <sys/ipc.h>
and <sys/modes.h>:
- IPC_CREAT
- Create a message queue if the key specified does not already have an associated ID. IPC_CREAT is ignored when IPC_PRIVATE is specified
- IPC_EXCL
- Causes the msgget() function to fail if the key specified has an associated ID. IPC_EXCL is ignored when IPC_CREAT is not specified or IPC_PRIVATE is specified
- IPC_RCVTYPEPID
- Creates a message queue that can only be read from msgrcv() when Message_Type is the process ID of the invoker. This restriction does not apply if the msgrcv() invoker has the same effective UID as the message queue creator.
- IPC_SNDTYPEPID
- Creates a message queue that can only be written to msgsnd() when MSG_TYPE is the process ID of the invoker. This restriction does not apply if the msgsnd() invoker has the same effective UID as the message queue creator.
- S_IRUSR
- Permits read access when the effective user ID of the caller matches either msg_perm.cuid or msg_perm.uid
- S_IWUSR
- Permits write access when the effective user ID of the caller matches either msg_perm.cuid or msg_perm.uid
- S_IRGRP
- Permits read access when the effective group ID of the caller matches either msg_perm.cgid or msg_perm.gid
- S_IWGRP
- Permits write access when the effective group ID of the caller matches either msg_perm.cgid or msg_perm.gid
- S_IROTH
- Permits other read access
- S_IWOTH
- Permits other write access
When a message set associated with argument key already exists, setting IPC_EXCL and IPC_CREAT in argument msgflg will force msgget() to fail.
Upon creation, the msg_ds data
structure associated with the new message queue identifier is initialized
as follows:
- The fields msg_perm.cuid, msg_perm.uid, msg_perm.cgid, and msg_perm.gid are set equal to the effective user ID and effective group ID, respectively, of the calling process.
- The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 bits of msgflg.
- The fields msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime are set to zero.
- The field msg_ctime is set equal to the current time.
- The field msg_qbytes is set equal to the system limit.
Usage notes
- In a client/server environment, two message queues can be used. One inbound to the server created with IPC_SNDTYPEPID and the other outbound from the server created with IPC_RCVTYPEPID. This arrangement guarantees that the server knows the process ID of the client and the client is the only process that receives the server's returned message. The server may invoke msgrcv() with PID=0 to see if any messages belong to process IDs that have gone away.
- Important terms and their descriptions are explained:
- Term
- Descriptions
- PLO
- Perform Lock Operation.
- IPC_PLO1
- Use PLO serialization (if available) until a select() involving this message queue is detected.
- IPC_PLO2
- Allow the kernel to use its best judgment with serialization (IPC_PLO1 ignored).
- Message_Flags IPC_PLO1 and IPC_PLO2 are ignored if the PLO instruction is not present on the hardware.
- Performance of the PLO instruction for serialization will vary with the msgrcv type, number of messages on the queue and the number of tasks doing msgsnd() and msgrcv(). Msgrcv() with type<0 and long message queues is expected to be a worse performer. Msgrcv() with type>0 is expected to be an equivalent or good performer. Msgrcv() with type=0 is expected to be a very good performer.
- Message queues created with Ipc_RcvTypePID, Ipc_SndTypePID, IPC_PLO1 and IPC_PLO2 will show these bits and may show the IPC_PLOINUSE bit in the S_MODE byte returned with w_getipc.
- Message queue PLO serialization is not compatible with select() using message queues. When msgrcv() detects a select() for a message queue, serialization will be changed to use traditional latches.
- Performance runs should be made with IPC_PLO1 since IPC_PLO2 may switch to latch serialization and the user would not know when.
Returned value
If successful, msgget() returns a nonnegative integer, namely a message queue identifier.
If
unsuccessful, msgget() returns -1 and sets errno to one of the following
values:
- Error Code
- Description
- EACCES
- A message queue identifier exists for the argument key, but access permission as specified by the low-order 9 bits of msgflg could not be granted
- EEXIST
- A message queue identifier exists for the argument key, but both IPC_CREAT and IPC_EXCL are specified in msgflg
- EINVAL
- The value of argument msgflg is not currently supported
- ENOENT
- A message queue identifier does not exist for the argument key and IPC_CREAT is not specified.
- 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.
When msgflg equals
0, the following applies:
- If a message queue identifier has already been created with key earlier, and the calling process of this msgget() has read and/or write permissions to it, then msgget() returns the associated message queue identifier.
- If a message queue identifier has already been created with key earlier, and the calling process of this msgget() does not have read and/or write permissions to it, then msgget() returns-1 and sets errno to EACCES.
- If a message queue identifier has not been created with key earlier, then msgget() returns -1 and sets errno to ENOENT.