msgsnd(2)

NAME

     msgsnd - message send operation

SYNOPSIS

     #include <sys/msg.h>

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

DESCRIPTION

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

     The msgp argument points to a user-defined buffer that  must
     contain first a field of type long int that will specify the
     type of the message, and then a data portion that will  hold
     the  data  bytes  of  the message. The structure below is an
     example of what this user-defined buffer might look like:

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

     The mtype member is a non-zero positive type long  int  that
     can be used by the receiving process for message selection.

     The mtext member is any text  of  length  msgsz  bytes.  The
     msgsz argument can range from 0 to a system-imposed maximum.

     The msgflg argument specifies the action to be taken if  one
     or more of the following are true:

        o  The number of bytes already on the queue is  equal  to
           msg_qbytes; see intro(2).

        o  The total number of messages on all queues system-wide
           is equal to the system-imposed limit.

     These actions are as follows:

        o  If (msgflg&IPC_NOWAIT) is non-zero, the  message  will
           not  be  sent  and  the  calling  process  will return
           immediately.

        o  If (msgflg&IPC_NOWAIT) is 0, the calling process  will
           suspend execution until one of the following occurs:

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

              o  The message queue identifier  msqid  is  removed
                 from  the  system  (see  msgctl(2));  when  this
                 occurs, errno is set equal to EIDRM  and  -1  is
                 returned.

              o  The calling process receives a signal that is to
                 be  caught; in this case the message is not sent
                 and the calling process resumes execution in the
                 manner prescribed in sigaction(2).

     Upon successful completion, the following actions are  taken
     with  respect  to  the  data structure associated with msqid
     (see intro(2)):

        o  msg_qnum is incremented by 1.

        o  msg_lspid is set equal to the process ID of  the  cal-
           ling process.

        o  msg_stime is set equal to the current time.

RETURN VALUES

     Upon successful completion, 0 is returned. Otherwise, -1  is
     returned,  no  message is sent, and errno is set to indicate
     the error.

ERRORS

     The msgsnd() function will fail if:

     EACCES
           Operation permission is denied to the calling process.
           See intro(2).

     EAGAIN
           The message cannot be sent  for  one  of  the  reasons
           cited above and (msgflg&IPC_NOWAIT) is non-zero.

     EIDRM The message queue identifier msgid is removed from the
           system.

     EINTR The msgsnd() function was interrupted by a signal.

     EINVAL
           The value of msqid is not a valid message queue  iden-
           tifier,  or  the value of mtype is less than 1; or the
           value of msgsz is less than  0  or  greater  than  the
           system-imposed limit.

     The msgsnd() function may fail if:

      EFAULT
           The msgp argument points to an illegal address.

USAGE

     The value passed as the msgp argument should be converted to
     type void *.

SEE ALSO

     intro(2), msgctl(2), msgget(2), msgrcv(2), sigaction(2)