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 associated
     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 follows:

          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  system
                has not enough memory for the new data structure.

     ENOSPC     A message queue has to be created but the  system
                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 creates
     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
     processes  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 created, 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).