Standards
Standards / Extensions |
C or C++ |
Dependencies |
XPG4
XPG4.2
Single UNIX Specification, Version 3
|
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.