msgsnd()--Send Message Operation

 #include <sys/msg.h>

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

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

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

1. A field of type long int that specifies the type of the message.

2. A data part that contains the data bytes of the message.

The following structure is an example of what the user-defined buffer might look like for a message that has 5 bytes of data.

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

The value of mtype must be greater than zero. When messages are received with msgrcv(), the message type can be used to select the messages. The message data can be any length up to the system limit.

If the message queue is full, the msgflg parameter specifies the action to be taken. The actions are as follows:

• If the IPC_NOWAIT flag is set in the msgflg parameter, the message is not sent. The msgsnd() function returns immediately with a return value of -1 and errno set to EAGAIN.
  
  
• If the IPC_NOWAIT flag is not set in the msgflg parameter, the calling thread suspends processing until one of the following occurs:
  
  
  • Enough messages are received from the message queue so that a message of size msgsz can be placed on the message queue.

  • The message queue identifier msqid is removed from the system. When this occurs, the msgsnd() function returns with a return value of -1 and errno set to EIDRM.

  • A signal is delivered to the calling thread. When this occurs, the msgsnd() function returns with a return value of -1 and errno set to EINTR.

The system maintains status information about a message queue which can be retrieved with the msgctl() function. When a message is successfully sent to the message queue, the system sets the members of the msqid_ds structure as follows:

• 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.

Parameters

msqid

(Input) Message queue identifier, a positive integer. It is returned by the msgget() function and used to identify the message queue to send the message to.

msgp

(Input) Pointer to a buffer with the message to be sent. See above for the details on the format of the buffer.

msgsz

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

msgflg

(Input) Operations flags. The value of msgflg is either zero or is obtained by performing an OR operation on one or more of the following constants:

IPC_NOWAIT (0x00000800)

If the message queue is full, do not wait for space to become available on the message queue and return immediately.

Authorities

Authorization Required for msgsnd()

Return Value

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.

The calling thread does not have write permission to the message queue.

[EAGAIN]

Operation would have caused the process to be suspended.

The message cannot be sent for one of the reasons cited above and the IPC_NOWAIT flag is set in the msgflg parameter.

[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.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

• The *msgp parameter is NULL.
• The msqid parameter is not a valid message queue identifier.
• The mtype parameter is less than or equal to zero.
• The msgsz parameter is greater than the system 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 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 when using datamodel *P128:

    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.   */
   

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. 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)
  
  
• Message Queue Functions for the current system limits.
  
  
• msgctl()--Perform Message Control Operations
  
  
• msgget()--Get Message Queue
  
  
• msgrcv()--Receive Message Operation

• sigaction()--Examine and change signal action

Example

The following example sends a message to a message queue.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <sys/msg.h>

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

  msgsz = sizeof(struct mymsg) - sizeof(long int);
  mymsg.mtype = 1;
  rc = msgsnd(msqid, &mymsg, msgsz, IPC_NOWAIT);
}

[ Back to top | UNIX-Type APIs | APIs by category ]