Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
msgop(2)							      msgop(2)

Name
       msgsnd, msgrcv -	message	operations

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

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

       int msgrcv (msqid, msgp,	msgsz, msgtyp, msgflg)
       int msqid;
       void *msgp;
       size_t msgsz;
       long msgtyp;
       int msgflg;

Description
       There are two message operations	system calls, and

   msgsnd
       The  system call	is used	to send	a message to the queue associated with
       the message queue identifier specified by msqid.	  The  msgp  parameter
       points  to  a structure containing the message.	This structure is com-
       posed of	the  following	members:  long mtype;	 /*  message  type  */
       char mtext[];  /*  message  text	 */  The mtype parameter is a positive
       integer that can	be used	by the receiving process  for  message	selec-
       tion.   For  more  information, see the section of this reference page.
       The mtext parameter is any text	of  length  msgsz  bytes.   The	 msgsz
       parameter can range from	0 to a system-imposed maximum.

       The  msgflg parameter specifies the action to be	taken if the number of
       bytes already on	the queue is equal to msg_qbytes.  (For	further	infor-
       mation,	see ) The parameter also specifies what	happens	when the total
       number of messages on all queues	system-wide is equal  to  the  system-
       imposed limit.

       If  either of these conditions is true, and if (msgflg &	IPC_NOWAIT) is
       true, the message is not	sent and the calling process  returns  immedi-
       ately.	However,  if  either  of  the conditions is true and (msgflg &
       IPC_NOWAIT) is false, the calling process suspends 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	msqid parameter	is  removed  from  the	system.	  For  further
	    information,  see  When  this occurs, errno	is set equal to	EIDRM,
	    and	a value	of -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

       The system call fails and no message is sent under the following	condi-
       tions:

       [EINVAL]	      The msqid	parameter is not a valid message queue identi-
		      fier.

       [EACCES]	      Operation	permission is denied to	the  calling  process.
		      For more information, see

       [EINVAL]	      The mtype	parameter is less than 1.

       [EAGAIN]	      The  message cannot be sent for one of the reasons cited
		      above and	(msgflg	& IPC_NOWAIT) is true.

       [EINVAL]	      The msgsz	parameter is less than zero  or	 greater  than
		      the system-imposed limit.

       [EFAULT]	      The msgp parameter points	to an illegal address.

       Upon  successful	 completion,  the  following  actions  are  taken with
       respect to the data structure associated	with msqid (for	more  informa-
       tion, see ):

       o    The	msg_qnum is incremented	by 1.

       o    The	 msg_lspid  is	set  equal  to	the  process ID	of the calling
	    process.

       o    The	msg_stime is set equal to the current time.

   msgrcv
       The system call reads a message from the	queue associated with the mes-
       sage queue identifier specified by msqid	and places it in the structure
       pointed to by msgp.  This structure is composed of the  following  mem-
       bers:

       long	mtype;	     /*	message	type */	char	mtext[];    /* message
       text */ The mtype parameter is the received message's type,  as	speci-
       fied  by	 the  sending process.	The mtext parameter is the text	of the
       message.	 The msgsz parameter specifies the size, in bytes,  of	mtext.
       The  received  message is truncated to msgsz bytes if it	is larger than
       msgsz and (msgflg & MSG_NOERROR)	is true.  The truncated	 part  of  the
       message	is  lost  and  no indication of	the truncation is given	to the
       calling process.

       The msgtyp parameter specifies the type of message requested,  as  fol-
       lows:

       o    If	msgtyp	is  equal  to  0,  the	first  message on the queue is
	    received.

       o    If msgtyp is greater than 0, the first message of type  msgtyp  is
	    received.

       o    If	msgtyp	is  less  than 0, the first message of the lowest type
	    that is less than or equal to the  absolute	 value	of  msgtyp  is
	    received.

       The  msgflg  parameter specifies	the action to be taken if a message of
       the desired type	is not on the queue.  These specified actions  are  as
       follows:

       o    If	(msgflg	 &  IPC_NOWAIT)	 is  true, the calling process returns
	    immediately	with a value of	-1 and errno set to ENOMSG.

       o    If (msgflg & IPC_NOWAIT) is	false, the  calling  process  suspends
	    execution until one	of the following occurs:

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

	    -	 The  msqid  parameter	is removed from	the system.  When this
		 occurs, errno is set equal to EIDRM, and a  value  of	-1  is
		 returned.

	    -	 The  calling  process receives	a signal that is to be caught.
		 In this case, a message  is  not  received  and  the  calling
		 process resumes execution in the manner prescribed in

       The  system  call  fails	and no message is received under the following
       conditions:

       [EINVAL]	      The msqid	parameter is not a valid message queue identi-
		      fier.

       [EACCES]	      Operation	permission is denied to	the calling process.

       [EINVAL]	      The msgsz	parameter is less than 0.

       [E2BIG]	      The  mtext parameter is greater than msgsz and (msgflg &
		      MSG_NOERROR) is false.

       [ENOMSG]	      The queue	does not contain a message of the desired type
		      and (msgtyp & IPC_NOWAIT)	is true.

       [EFAULT]	      The msgp parameter points	to an illegal address.

       Upon  successful	 completion,  the  following  actions  are  taken with
       respect to the data structure associated	with msqid:

       o    The	msg_qnum is decremented	by 1.

       o    The	msg_lrpid is set equal	to  the	 process  ID  of  the  calling
	    process.

       o    The	msg_rtime is set equal to the current time.

Return Values
       If  the	or system calls	return due to the receipt of a signal, a value
       of -1 is	returned to the	calling	process, and errno is  set  to	EINTR.
       If  they	 return	due to removal of msqid	from the system, a value of -1
       is returned, and	errno is set to	EIDRM.

       Upon successful completion, the return value is as follows:

       o    The	system call returns a value of 0.

       o    The	system call returns a value equal to the number	of bytes actu-
	    ally placed	into mtext.

       Otherwise,  a value of -1 is returned, and errno	is set to indicate the
       error.

See Also
       errno(2), intro(2), msgctl(2), msgget(2), signal(3)

								      msgop(2)

Name | Syntax | Description | Return Values | See Also

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=msgsnd&sektion=2&manpath=ULTRIX+4.2>

home | help