msgsnd() -- General Function (libc)

Send a message
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
msgsnd(id, buffer, size, flag)
int id, size, flag; long *buffer;

The  function msgsnd()  inserts a  message into  the queue  associated with
identifier id.

buffer points to  a user-defined buffer that holds a  code that defines the
type of the message, and the  text of the message.  buffer can be described
by a structure something like the following (if we pretend mtext[] is legal
C):

struct msgbuf {
     long mtype;            /* message type */
     char mtext[];          /* message text */
};

Field mtype is a positive long  integer that gives the type of message this
is.  Function msgrcv() examines this field to see if this message is of the
type that it  seeks.  The text of the message  immediately follows mtype in
memory, for size  bytes.  size can range from zero  to a maximum defined in
the kernel variable NMSC.

If any of the following error conditions occurs, msgsnd() does not send the
message, sets errno to the value given in parentheses, and returns -1:

-> id is not a valid message queue identifier (EINVAL).

-> The calling  process does not  have permission to  manipulate this queue
   (EACCES).

-> Field  mtype in  the structure  pointed to  by buffer  is less  than one
   (EINVAL).

-> size  is  less  than  zero  or  greater than  the  system-imposed  limit
   (EINVAL).

-> buffer points to an illegal address (EFAULT).

Sending a  message may exceed  a system-defined limit.  There  are two such
limits: one limits the size of a queue, and the other sets the total number
of messages  available to your system.   The maximum size of  this queue is
given in the field msg_qbytes  of the structure msqid_ds that controls that
queue.  If issuing  a message size bytes long would  push the total size of
the queue's  messages past the  value of msg_qbytes, then  an error occurs.
Likewise, an  error occurs if the system already  holds the maximum maximum
number of message available to it, as set by the kernel variable NMSG.

flag indicates how msgsnd() is to  react to either of the above conditions.
If flag  is OR'd to  include value IPC_NOWAIT,  then msgsnd() reacts  as it
does with any other error: it does not send the message, it returns -1, and
it sets errno to an appropriate value (in this case, EAGAIN).  If, however,
flag is  not OR'd to include  IPC_NOWAIT, then msgsnd() waits  until any of
the following happens:

1. The error condition resolves.   In this case, msgsnd() sends the message
   and returns normally.

2. The message queue identified by id  is removed from the system.  In this
   case, msgsnd() does not send the message; it sets errno to EIDRM; and it
   returns -1.

3. The process that issued the call to msgsnd() receives a signal.  In this
   case,  msgsnd() does  not send  the  message, sets  errno to  EINTR, and
   returns -1.   The calling process then executes  the action requested by
   the signal.   For information on the behavior  that each signal invokes,
   see the Lexicon entry for signal().

msgsnd()  successfully  sends  a message,  returns  zero  and modifies  the
message queue in the following manner:

-> It increments by one the value in field msg_qnum.

-> It sets field msg_lspid to the process ID of the calling process.

-> It sets msg_stime to the current time.

Example

For an example of this function, see the Lexicon entry for msgget().

Files

/usr/include/sys/ipc.h
/usr/include/sys/msg.h

See Also

libc,
msgctl(),
msgget(),
msgrcv()

© 2012 by Stephen A. Ness