unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



msgget(2)							    msgget(2)



NAME

  msgget - Returns (and	possibly creates) the ID for a message queue

SYNOPSIS

  #include <&lt;sys/msg.h>&gt;

  int msgget(
	  key_t	key,
	  int msgflg);

  Application developers may want to specify #include statements for
  <&lt;sys/types.h>&gt;	and <&lt;sys/ipc.h>&gt;	before the one for <&lt;sys/msg.h>&gt; if programs
  are being developed for multiple platforms. The additional #include state-
  ments	are not	required on Tru64 UNIX systems or by ISO or X/Open standards,
  but may be required on other vendors'	systems	that conform to	these stan-
  dards.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  msgget():  XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  key Specifies	the key	that identifies	the message queue.  The	value for the
      key parameter can	be IPC_PRIVATE or a random number other	than zero
      (0).  To ensure that the msgget()	function returns a new message queue
      ID, specify the IPC_PRIVATE keyword.

  msgflg
      Specifies	flags that control the msgget()	function. Possible values are
      as follows:

      IPC_CREAT

		Specifies creating a message queue ID.

		If the specified key does not exist, the msgget	function
		creates	a message queue	ID and associates it with the speci-
		fied key.

		If the specified key does exist, and IPC_EXCL is not set, the
		msgget function	returns	the message queue ID associated	with
		key.

		If the specified key does exist	and IPC_EXCL is	set, the
		msgget function	fails and returns an error.

      IPC_EXCL	Specifies that you want	to ensure that your application	is
		the only one using the specified key parameter.	 If the
		specified key already exists, the msgget function fails	and
		returns	an error notification.

DESCRIPTION

  The msgget function returns the message queue	ID for the message queue
  identified by	the key	parameter.  If the message queue ID does not exist,
  the msgget() function	attempts to create it.

  If you specify IPC_PRIVATE for the key parameter, the	msgget function
  returns the ID for a private (that is, newly created)	message	queue.

  The msgflg parameter supplies	creation options for the msgget	function. The
  IPC_CREAT flag specifies that	you want the kernel to create a	message	queue
  for your application.	 The kernel returns the	message	queue ID to your
  application as the return value of the successful call to the	msgget()
  function.

  The msgget() function	does not create	a message queue	ID for your applica-
  tion under the following conditions:

    +  A message queue ID that is associated with the specified	key already
       exists.	In this	case, the msgget() function returns the	message	queue
       ID associated with the key parameter (unless you	have set the IPC_EXCL
       flag).

    +  You have	set the	IPC_EXCL flag and another application is using the
       specified key. In this case, the	msgget() function fails	and returns
       an error	to your	application.

  After	creating a new message queue ID, the msgget function initializes the
  msqid_ds structure associated	with the ID as follows:

    +  The msg_perm.cuid and msg_perm.uid members are set equal	to the effec-
       tive user ID of the calling process.

    +  The msg_perm.cgid and msg_perm.gid members are set equal	to the effec-
       tive group ID of	the calling process.

    +  The low-order nine bits of the msg_perm.mode member are set equal to
       the low-order nine bits of msgflg.

    +  The msg_qnum, msg_lspid,	msg_lrpid, msg_stime, and msg_rtime members
       are all set equal to zero.

    +  The msg_ctime member is set equal to the	current	time.

    +  The msg_qbytes member is	set equal to the system	limit.

RETURN VALUES

  Upon successful completion, the msgget() function returns a message queue
  identifier.  Otherwise, the function returns a value of -1 and sets errno
  to indicate the error.

ERRORS

  The msgget function sets errno to the	specified values for the following
  conditions:

  [EACCES]  A message queue identifier exists for the key parameter, but the
	    calling process does not have the appropriate privileges to
	    perform the	operation. The permission is specified by the low-
	    order nine bits of the msgflg parameter.

  [EEXIST]  A message queue identifier exists for the key parameter, and both
	    IPC_CREAT and IPC_EXCL are set.

  [ENOENT]  A message queue identifier does not	exist for the key parameter
	    and	the IPC_CREAT value is not set.

  [ENOSPC]  A message queue identifier can be created, but the system-imposed
	    limit on the maximum number	of allowed message queue identifiers
	    has	been exceeded.

RELATED	INFORMATION

  Functions: msgctl(2),	msgrcv(2), msgsnd(2), table(2),	ftok(3)

  Files: msqid_ds(4)

  Standards: standards(5)