NAME

     msgop - message operations


SYNOPSIS

     # include <sys/types.h>
     # include <sys/ipc.h>
     # include <sys/msg.h>

     int msgsnd ( int msqid, struct msgbuf *msgp, int msgsz,  int
     msgflg )

     int msgrcv ( int msqid, struct msgbuf *msgp, int msgsz, long
     msgtyp, int msgflg )


DESCRIPTION

     To send or receive a message, the calling process  allocates
     a structure that looks like the following

          struct msgbuf {
               long mtype;     /* message type, must be > 0 */
               char mtext[1];  /* message data */
          };

     but with an  array  mtext  of  size  msgsz,  a  non-negative
     integer  value.   The  structure  member  mtype  must have a
     strictly positive integer value that  can  be  used  by  the
     receiving  process  for  message  selection (see the section
     about msgrcv).

     The calling process must have write  access  permissions  to
     send and read access permissions to receive a message on the
     queue.

     The msgsnd system call enqueue a copy of the message pointed
     to  by the msgp argument on the message queue whose identif-
     ier is specified by the value of the msqid argument.

     The argument msgflg specifies the system call  behaviour  if
     enqueuing  the new message will require more than msg_qbytes
     in the queue.  Asserting IPC_NOWAIT the message will not  be
     sent  and  the system call fails returning with errno set to
     EAGAIN.  Otherwise the process is suspended until the condi-
     tion  for the suspension no longer exists (in which case the
     message is sent and the system call succeeds), or the  queue
     is  removed  (in which case the system call fails with errno
     set to EIDRM), or the process receives a signal that has  to
     be  caught  (in  which case the system call fails with errno
     set to EINTR).

     Upon successful completion the message queue data  structure
     is updated as follows:

          msg_lspid is set to the process-ID of the calling  pro-
          cess.

          msg_qnum is incremented by 1.

          msg_stime is set to the current time.

     The system call msgrcv reads  a  message  from  the  message
     queue  specified  by msqid into the msgbuf pointed to by the
     msgp argument removing from the queue, on success, the  read
     message.

     The argument msgsz specifies the maximum size in  bytes  for
     the  member  mtext  of  the structure pointed to by the msgp
     argument.  If the  message  text  has  length  greater  than
     msgsz,  then if the msgflg argument asserts MSG_NOERROR, the
     message text will be truncated (and the truncated part  will
     be lost), otherwise the message isn't removed from the queue
     and the system call fails returning with errno set to E2BIG.

     The argument msgtyp specifies the type of message  requested
     as follows:

          If msgtyp is 0, then the message on the  queue's  front
          is read.

          If msgtyp is greater than 0, then the first message  on
          the  queue  of  type msgtyp is read if MSG_EXCEPT isn't
          asserted by the msgflg argument,  otherwise  the  first
          message  on  the queue of type not equal to msgtyp will
          be read.

          If msgtyp is less than 0, then the first message on the
          queue  with  the  lowest type less than or equal to the
          absolute value of msgtyp will be read.

     The msgflg argument asserts none, one or more (or-ing  them)
     among the following flags:

          IPC_NOWAIT For immediate return if no  message  of  the
          requested  type is on the queue.  The system call fails
          with errno set to ENOMSG.

          MSG_EXCEPT Used with msgtyp greater than 0 to read  the
          first  message  on  the  queue  with  message type that
          differs from msgtyp.

          MSG_NOERROR To truncate the message text if longer than
          msgsz bytes.

     If no  message  of  the  requested  type  is  available  and
     IPC_NOWAIT  isn't asserted in msgflg, the calling process is
     blocked until one of the following conditions occurs:

          A message of the desired type is placed on the queue.

          The message queue is removed from the system.  In  such
          a case the system call fails with errno set to EIDRM.

          The calling process receives a signal that  has  to  be
          caught.   In  such  a  case  the system call fails with
          errno set to EINTR.

     Upon successful completion the message queue data  structure
     is updated as follows:

          msg_lrpid is set to the process-ID of the calling  pro-
          cess.

          msg_qnum is decremented by 1.

          msg_rtime is set to the current time.


RETURN VALUE

     On a failure both functions return -1 with errno  indicating
     the error, otherwise msgsnd returns 0 and msgrvc returns the
     number of bytes actually copied into the mtext array.


ERRORS

     When msgsnd fails, at return errno will be set to one  among
     the following values:

     EAGAIN     The message can't be sent due to  the  msg_qbytes
                limit  for  the queue and IPC_NOWAIT was asserted
                in mgsflg.

     EACCES     The calling process has no write  access  permis-
                sions on the message queue.

     EFAULT     The address pointed to by msgp isn't accessible.

     EIDRM      The message queue was removed.

     EINTR      Sleeping on a full message queue  condition,  the
                process received a signal that had to be caught.

     EINVAL     Invalid msqid value, or nonpositive mtype  value,
                or  invalid  msgsz  value (less than 0 or greater
                than the system value MSGMAX).

     ENOMEM     The system has not enough memory to make  a  copy
                of the supplied msgbuf.


     When msgrcv fails, at return errno will be set to one  among
     the following values:

     E2BIG      The message text length is greater than msgsz and
                MSG_NOERROR isn't asserted in msgflg.

     EACCES     The calling process has no  read  access  permis-
                sions on the message queue.

     EFAULT     The address pointed to by msgp isn't accessible.

     EIDRM      While the process was sleeping to receive a  mes-
                sage, the message queue was removed.

     EINTR      While the process was sleeping to receive a  mes-
                sage,  the  process received a signal that had to
                be caught.

     EINVAL     Illegal msgqid value, or msgsz less than 0.

     ENOMSG     IPC_NOWAIT was asserted in msgflg and no  message
                of  the  requested  type  existed  on the message
                queue.


NOTES

     The followings are system limits affecting a  msgsnd  system
     call:

     MSGMAX     Maximum size for a message text: the  implementa-
                tion set this value to 4080 bytes.

     MSGMNB     Default maximum size in bytes of a message queue:
                policy  dependent.   The  super-user can increase
                the size of a message queue beyond  MSGMNB  by  a
                msgctl system call.

     The implementation has no intrinsic limits  for  the  system
     wide  maximum number of message headers (MSGTQL) and for the
     system wide maximum  size  in  bytes  of  the  message  pool
     (MSGPOOL).


CONFORMING TO

     SVr4, SVID.


SEE ALSO

     ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2).