unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



msgsnd(2)							    msgsnd(2)



NAME
  msgsnd - Sends a message to a	message	queue

SYNOPSIS

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

  int msgsnd(
	  int msqid,
	  const	void *msgp,
	  size_t msgsz,
	  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:

  msgsnd():  XPG4, XPG4-UNIX

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

PARAMETERS

  msqid	    Specifies the ID of	the message queue on which to place the	mes-
	    sage.  The ID is typically returned	by a previous msgget() func-
	    tion.

  msgp	    Specifies a	pointer	to the msgbuf structure	that contains the
	    message.

  msgsz	    Specifies the size of the data array in the	msgbuf structure.

  msgflg    Specifies the action to be taken by	the kernel if it runs out of
	    internal buffer space.

DESCRIPTION

  The msgsnd() function	sends a	message	to the queue associated	with the
  msqid	parameter.  When the kernel sends a message, it	allocates space	for
  the message and copies the data from user space.  The	kernel then allocates
  a structure of type msg (message header), sets its fields, and inserts the
  structure at the end of the message queue associated with the	message	queue
  ID.  The msg structure is defined as follows:

  struct msg {
	  struct msg	 *msg_next;
	  long		  msg_type;
	  long		  msg_ts;
	  caddr_t	  msg_addr;
  };

  The msg_next field is	a pointer to the next message in the queue.  The
  msg_type field is the	message	type supplied in the user-specified msgbuf
  structure.  The msg_ts field is the size of the message text.	 The msg_addr
  field	is the address of the message text.

  You pass the message that the	kernel adds to the message queue in the	msgp
  parameter. This parameter points to a	msgbuf structure that you define as
  follows:

  struct msgbuf	{
	  long int mtype;
	  char mtext[];	}

  The mytpe field is a positive	integer	that indicates the type	of the mes-
  sage.	 A receiving process can use this message type to select only those
  messages it wants to receive from the	queue.	For more information about
  the values you can specify in	this field, see	msgrcv(2).

  The mtext field contains the text of the message.  You specify the size in
  bytes	of the message in the msgsz parameter.	You can	specify	a value
  between 0 (zero) and,	by default, 8192 bytes.	 Note that the maximum number
  of bytes allowed in a	message	string is configured at	system configuration
  time using the msgmax	configuration file keyword, so the limit might be
  different for	your system.

  The msgflg parameter specifies the action that the kernel should take	if
  either or both of the	following are true:

    +  The current number of bytes in the message queue	is equal to
       msg_qbytes (in the msqid_ds structure).

    +  The total number	of messages on all message queues is equal to the
       limit defined by	the msgtql configuration file keyword. By default the
       limit is	40, but	it might have been changed for your system at system
       configuration time.

  One of two kernel actions can	be specified, as follows:

    +  If IPC_NOWAIT is	set, the kernel	does not send the message and returns
       to the calling process immediately.

    +  If IPC_NOWAIT is	not set, the kernel suspends the calling process.
       The process remains suspended until one of the following	occurs:

	 -- The	blocking condition is removed.	In this	case, the kernel
	    sends the message.

	 -- The	specified message queue	ID is removed from the system.	In
	    this case, the kernel sets errno to	[EIDRM]	and returns -1 to the
	    calling process.

	 -- The	calling	process	catches	a signal.  In this case, the message
	    is not sent	and the	process	resumes	execution as directed by the
	    signal() function.

  If the msgsnd() function completes successfully, the kernel updates the
  msqid_ds structure associated	with the msgid parameter.  Specifically, it:

    +  Increments msg_qnum by 1.

    +  Increments msg_cbytes by	the message text size.

    +  Sets msg_lspid equal to the process ID of the calling process.

    +  Sets msg_stime equal to the current time.

RETURN VALUES

  Upon successful completion, the msgrcv() function returns a value of 0
  (zero).  Otherwise, the function returns a value of -1 and sets errno	to
  indicate the error.

ERRORS

  The msgsnd() function	sets errno to the specified values for the following
  conditions:

  [EACCES]  The	calling	process	does not have permission for the operation.

  [EAGAIN]  The	IPC_NOWAIT flag	is set,	and either the maximum number of mes-
	    sage headers has been allocated or the message queue is full.

  [EFAULT]  Indicates that the requested address is in some way	invalid, for
	    example, out of bounds.

  [EIDRM]   The	message	queue identified by the	msqid parameter	has been
	    removed from the system.

  [EINTR]   The	operation was interrupted by a signal.

  [EINVAL]  The	msqid parameter	is not a valid message queue ID, mtype is
	    less than 1, or msgsz is less than 0 (zero)	or greater than	the
	    limit defined by the msgmax	configuration file keyword. By
	    default the	limit is 8192 bytes, but it might have been changed
	    for	your system at system configuration time.

RELATED	INFORMATION

  Functions: msgctl(2),	msgget(2), msgrcv(2), sigaction(2)

  Data Structures: msqid_ds(4)

  Standards: standards(5)