msgsnd()-Send Message Operation

#include <sys/msg.h>

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

The msgsnd() function is used to send a message to the queue associated with the message queue identifier specified by msqid.

Parameters

msqid

(Input) Message queue identifier to which the message will be sent.

msgp

(Input) Pointer to the message to be sent.

msgsz

(Input) Length of the data part of the message to be sent.

msgflg

(Input) Action to be taken if the message cannot be immediately placed on the queue.

The parameter msgp points to a user-defined buffer that must contain the following:

1. A field of type long int that will specify the type of the message.

2. A data part that will hold the data bytes of the message.

The following structure is an example of what this user-defined buffer might look like:

  struct mymsg {
         long int    mtype;      /* message type */
         char        mtext[1];   /* message text */
  }

The structure member mtype is a long int that is greater than zero. It can be used by the receiving thread for message selection. The structure member mtext is any text of length msgsz bytes. The parameter msgsz can range from zero to a system-imposed maximum.

The parameter msgsz should include any bytes inserted by the compiler for padding or alignment purposes. These bytes are part of the message data and affect the total number of bytes in the message queue.

The following example shows pad data and how it affects the size of a message:

  struct mymsg {
     long int    mtype;      /* 12 bytes padding inserted after */
     char       *pointer;    /* the mtype field by the compiler.*/
     char        c;          /* 15 bytes padding inserted after */
     char       *pointer2;   /* the c field by the compiler.    */
  } msg;                     /* After the mtype field, there are*/
                             /* 33 bytes of user data, but 60   */
                             /* bytes of data including padding.*/
  msgsz = sizeof(msg) - sizeof(long int);        /* 60 bytes.   */

Authorities

Figure 1-7. Authorization Required for msgsnd()

Object Referred to	Authority Required	errno
Message queue on which message is placed	Write	EACCES

Return Value

0

msgsnd() was successful.

-1

msgsnd() was not successful. The errno variable is set to indicate the error.

Error Conditions

If msgsnd() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

The calling thread does not have write permission.

[EAGAIN]

Operation would have caused the process to be suspended.

The message cannot be sent for one of the reasons cited above and (msgflg & IPC_NOWAIT) is not zero. (& is a bitwise AND.)

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

The message queue has been damaged by a previous message queue operation.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EIDRM]

ID has been removed.

The message queue identifier msqid was removed from the system.

[EINTR]

Interrupted function call.

The function msgsnd() was interrupted by a signal.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

One of the following has occurred:

• The value of msgp is NULL.

• The value of msqid is not a valid message queue identifier.

• The value of mtype is less than or equal to zero.

• The value of msgsz is greater than the system-imposed limit.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

1. The parameter msgflg specifies the action to be taken if the number of bytes already on the queue is equal to msg_qbytes (see Message Queues or the <sys/msg.h> header file). The possible actions are as follows:

   • If (msgflg & IPC_NOWAIT) is not zero, the message is not sent. The calling thread will return immediately with a return value of -1 and errno set to [EAGAIN].

   • If (msgflg & IPC_NOWAIT) is zero, the calling process suspends processing until one of the following occurs:

     • The condition responsible for the suspension no longer exists, in which case the message is sent.

     • The message queue identifier msqid is removed from the system. When this occurs, errno is set to [EIDRM] and a value of -1 is returned.

     • The calling thread receives a signal that is to be caught. In this case, a message is not sent and the calling thread resumes processing in the manner prescribed in sigaction().

2. The msgsnd() function does not tag message data with a CCSID (coded character set identifier) value. If a CCSID value is required to correctly interpret the message data, it is the responsibility of the caller to include the CCSID value as part of the data.

3. On successful completion, the following actions are taken with respect to the data structure associated with msqid:

   • msg_qnum is incremented by 1.

   • msg_lspid is set to the process ID of the calling thread.

   • msg_stime is set to the current time.

4. If the msgsnd() function does not complete successfully, the requested message is not placed on the message queue.

Related Information

• The <sys/msg.h> file (see Header Files for UNIX-Type Functions)

• msgctl()-Perform Message Control Operations

• msgget()-Get Message Queue

• msgrcv()-Receive Message Operation

Example

The following example sends a message to a message queue:

#include <sys/msg.h>

main() {
  int msqid = 0;
  int msgflg = 0;
  int rc;
  size_t msgsz;
  struct mymsg {
      long int mtype;
      char     mtext[256];
  };

  msgsz = 256;
  mymsg.mtype = 1;
  rc = msgsnd(msqid, &mymsg, msgsz, msgflg | IPC_NOWAIT);
}