MSGGET(2)           Linux Programmer's Manual           MSGGET(2)

NAME
       msgget - get a message queue identifier

SYNOPSIS
       # include <sys/types.h>
       # include <sys/ipc.h>
       # include <sys/msg.h>

       int msgget ( key_t key, int msgflg )

DESCRIPTION
       The  function returns the message queue identifier associ-
       ated to the value of the  key  argument.   A  new  message
       queue is created if key has value IPC_PRIVATE or key isn't
       IPC_PRIVATE, no existing message queue  is  associated  to
       key,   and   IPC_CREAT   is   asserted   in  msgflg  (i.e.
       msgflg&IPC_CREAT is nonzero).  The presence in  msgflg  of
       the  fields  IPC_CREAT  and  IPC_EXCL plays the same role,
       with respect to the existence of the message queue, as the
       presence of O_CREAT and O_EXCL in the mode argument of the
       open(2) system call: i.e. the  msgget  function  fails  if
       msgflg  asserts  both IPC_CREAT and IPC_EXCL and a message
       queue already exists for key.

       Upon creation, the lower 9 bits  of  the  argument  msgflg
       define the access permissions of the message queue.  These
       permission bits have the same format and semantics as  the
       access permissions parameter in open(2) or creat(2) system
       calls.  (The execute permissions are not used.)

       Furthermore, while creating, the system  call  initializes
       the  system  message queue data structure msqid_ds as fol-
       lows:

              msg_perm.cuid  and  msg_perm.uid  are  set  to  the
              effective user-ID of the calling process.

              msg_perm.cgid  and  msg_perm.gid  are  set  to  the
              effective group-ID of the calling process.

              The lowest order 9 bits of msg_perm.mode are set to
              the lowest order 9 bit of msgflg.

              msg_qnum,   msg_lspid,   msg_lrpid,  msg_stime  and
              msg_rtime are set to 0.

              msg_ctime is set to the current time.

              msg_qbytes is set to the system limit MSGMNB.

       If the message queue already exists the access permissions
       are  verified,  and a check is made to see if it is marked
       for destruction.

RETURN VALUE
       If successful, the return value will be the message  queue
       identifier  (a  nonnegative  integer),  otherwise  -1 with
       errno indicating the error.

ERRORS
       For a failing return, errno will be set to one  among  the
       following values:

       EACCES     A message queue exists for key, but the calling
                  process has no access permissions to the queue.

       EEXIST     A  message  queue exists for key and msgflg was
                  asserting both IPC_CREAT and IPC_EXCL.

       EIDRM      The message queue is marked for removal.

       ENOENT     No message queue  exists  for  key  and  msgflg
                  wasn't asserting IPC_CREAT.

       ENOMEM     A  message queue has to be created but the sys-
                  tem has not enough  memory  for  the  new  data
                  structure.

       ENOSPC     A  message queue has to be created but the sys-
                  tem limit for the  maximum  number  of  message
                  queues (MSGMNI) would be exceeded.

NOTES
       IPC_PRIVATE  isn't a flag field but a key_t type.  If this
       special value is used for key,  the  system  call  ignores
       everything  but the lowest order 9 bits of msgflg and cre-
       ates a new message queue (on success).

       The following is a system limit on message queue resources
       affecting a msgget call:

       MSGMNI     System  wide  maximum number of message queues:
                  policy dependent.

BUGS
       Use of IPC_PRIVATE does not actually prohibit  other  pro-
       cesses from getting access to the allocated message queue.

       As for the files, there is currently no intrinsic way  for
       a  process  to ensure exclusive access to a message queue.
       Asserting both  IPC_CREAT  and  IPC_EXCL  in  msgflg  only
       ensures (on success) that a new message queue will be cre-
       ated, it doesn't imply exclusive  access  to  the  message
       queue.

CONFORMING TO
       SVr4,  SVID.  SVr4 does not document the EIDRM error code.

SEE ALSO
       ftok(3), ipc(5), msgctl(2), msgsnd(2), msgrcv(2).

Linux 0.99.13            November 1, 1993                       1