Unix/Linux Go Back    


RedHat 9 (Linux i386) - man page for msgsnd (redhat section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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, size_t msgsz, int msgflg);

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

DESCRIPTION
       To  send  or receive a message, the calling process allocates a structure of the following
       general form:

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

       The mtext field is an array (or other structure) whose size is specified by msgsz, a  non-
       negative  integer  value.   Messages  of zero length (i.e., no mtext field) are permitted.
       The mtype field 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 permission to send and read permission to receive a
       message on the queue.

       The msgsnd system call appends a copy of the message pointed to by  msgp  to  the  message
       queue whose identifier is specified by msqid.

       If  sufficient  space  is available on the queue, msgsnd succeeds immediately.  (The queue
       capacity is defined by the msg_bytes field in the associated data structure for	the  mes-
       sage  queue.   During  queue  creation this field is initialised to MSGMNB bytes, but this
       limit can be modified using msgctl.)  If insufficient space is  available  on  the  queue,
       then  the  default  behaviour  of  msgsnd  is  to block until space becomes available.  If
       IPC_NOWAIT is asserted in msgflg then the call instead fails with the error EAGAIN.

       A blocked msgsnd call may also fail if the queue is removed (in which case the system call
       fails with errno set to EIDRM), or a signal is caught (in which case the system call fails
       with errno set to EINTR).  (msgsnd and msgrcv  are  never  automatically  restarted  after
       being  interrupted by a signal handler, regardless of the  setting  of the SA_RESTART flag
       when establishing a signal handler.)

       Upon successful completion the message queue data structure 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 the read message from the queue.

       The  argument msgsz specifies the maximum size in bytes for the member mtext of the struc-
       ture 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 first message in the queue is read.

	      If  msgtyp is greater than 0, then the first message on the queue of type msgtyp is
	      read, unless MSG_EXCEPT was asserted in msgflg, in which case 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) of 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 this case the system call fails
	      with errno set to EIDRM.

	      The calling process catches a signal.  In this 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 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 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 permission 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 caught a signal.

       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 does not have read permission on the message queue.

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

       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 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 implementation  set  this  value  to  8192
		  bytes.

       MSGMNB	  Default  maximum size in bytes of a message queue: 16384 bytes.  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 (MSG-
       POOL).

CONFORMING TO
       SVr4, SVID.

NOTE
       The pointer argument is declared as struct msgbuf * with libc4, libc5,  glibc  2.0,  glibc
       2.1.  It  is  declared as void * (const void * for msgsnd()) with glibc 2.2, following the
       SUSv2.

SEE ALSO
       ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2)

Linux 2.4.18				    2002-06-01					 MSGOP(2)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:08 PM.