msgget

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 isn't zero).  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 (for owner, group and oth-
       ers) to the message queue in the same format, and with the
       same  meaning,  as for the access permissions parameter in
       the open(2) or creat(2) system calls (though  the  execute
       permissions are not used by the system).

       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 permis-
       sions 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 positive 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 as to be removed.

       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 don't inhibits to other processes the
       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.

SEE ALSO

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