MSGOP(2)            Linux Programmer's Manual            MSGOP(2)

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 allo-
       cates 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
       identifier is specified by the value of  the  msqid  argu-
       ment.

       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 condition 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 sys-
       tem  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 struc-
       ture is updated as follows:

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

              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  struc-
       ture is updated as follows:

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

              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  indicat-
       ing  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 accessi-
                  ble.

       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  accessi-
                  ble.

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

       EINTR      While the process was  sleeping  to  receive  a
                  message, 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  mes-
                  sage  of the requested type existed on the mes-
                  sage queue.

NOTES
       The followings are system limits affecting a msgsnd system
       call:

       MSGMAX     Maximum  size for a message text: the implemen-
                  tation 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).

Linux 0.99.13            November 1, 1993                       1