Index Index for
Section 2
Index Alphabetical
listing for M
Bottom of page Bottom of
page		 

msgsnd(2)


NAME

  msgsnd - Send a message to a message queue


SYNOPSIS

  #include <sys/msg.h>

  int msgsnd(
	  int msqid,
	  const void *msgp,
	  size_t msgsz,
	  int msgflg );

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


STANDARDS

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

  msgsnd(): XSH4.0, XSH4.2, XSH5.0

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


PARAMETERS

  msqid
      Specifies the ID of the message queue on which to place the message.
      The ID is typically returned by a previous msgget() function.

  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 mtype field is a positive integer that indicates the type of the
  message. 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
	    signaction() 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.

    ·  [Tru64 UNIX]  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 message
      headers has been allocated or the message queue is full.

  [EFAULT]
      [Tru64 UNIX]  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.


SEE ALSO

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

  Data Structures: msqid_ds(4)

  Standards: standards(5)

Index Index for
Section 2
Index Alphabetical
listing for M
Top of page Top of
page