msgrcv man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

msgrcv(2)							     msgrcv(2)

NAME
       msgrcv - Receive a message from a message queue

SYNOPSIS
       #include <sys/msg.h>

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

       Application  developers	may  want  to  specify #include statements for
       <sys/types.h> and <sys/ipc.h> before the one for	 <sys/msg.h>  if  pro‐
       grams  are  being  developed  for  multiple  platforms.	The additional
       #include statements are not required on Tru64 UNIX systems or by ISO or
       XSH  standards, but may be required on other vendors' systems that con‐
       form to these standards.

STANDARDS
       Interfaces documented on this reference page conform to industry	 stan‐
       dards as follows:

       msgrcv():  XSH4.0, XSH4.2, XSH5.0

       Refer  to  the  standards(5)  reference page for more information about
       industry standards and associated tags.

PARAMETERS
       Specifies the ID of the message queue from which to  receive  the  mes‐
       sage.   Specifies  a pointer to the msgbuf structure that is to receive
       the message.  See the NOTES section for	more  information.   Specifies
       the  maximum  number  of bytes allowed for the received data. The msgsz
       parameter is only used to specify the size of the  msgbuf.mtext	field.
       It  cannot  include the msgbuf.mtype field or else the msgbuf buffer is
       overwritten.  Specifies the message type to read from the queue.	 Spec‐
       ifies  the action to be taken by the kernel if there are no msgtyp mes‐
       sages on the queue.

DESCRIPTION
       The msgrcv() function receives a message from the queue associated with
       the  msqid  parameter.  The function returns the number of bytes in the
       received message.

       The msgp parameter points to a  user-defined  msgbuf  structure.	  This
       structure receives the message read from the queue.

       The msgsz parameter specifies the maximum size allowed for the received
       data.  If the message is	 longer	 than  msgsz,  the  following  occurs,
       depending  upon	the setting of the MSG_NOERROR flag: If MSG_NOERROR is
       not set, the kernel returns an [E2BIG] error to the calling process and
       leaves  the  message  on	 the queue.  If MSG_NOERROR is set, the kernel
       truncates the message to msgsz and discards the truncated portion with‐
       out notifying the calling process.

       The  msgtyp  parameter  specifies  the  message	type  that the process
       expects to receive.  Possible values and their results are as  follows:
       The process receives the message at the head of the queue.  The process
       receives the first message of the requested positive-integer type.  The
       process	receives the first message of the lowest type on the queue. To
       qualify as the lowest type, the negative-integer type must be less than
       or equal to the absolute value of msgtyp.

       The  msgflg  parameter specifies the action that the kernel should take
       if the queue does not contain a message of the requested type.	Either
       of  two	kernel	actions can be specified, as follows: If IPC_NOWAIT is
       set,  the  function  returns  immediately  with	a  return   value   of
       (ssize_t)-1  and sets errno to [ENOMSG].	 If IPC_NOWAIT is not set, the
       kernel suspends the calling process.

	      The process remains suspended until one of the following occurs:
	      A	 message  of the requested type appears on the queue.  In this
	      case, the kernel wakes the process to receive the message.   The
	      specified	 message queue ID is removed from the system.  In this
	      case, the kernel sets errno to [EIDRM] and  returns  (ssize_t)-1
	      to  the calling process.	The process catches a signal.  In this
	      case, the process does not receive  the  message	and,  instead,
	      resumes execution as directed by the sigaction() call.

NOTES
       The  parameter msgp points to a user-specified buffer that must contain
       first a field of type long int that specifies the type of the  message,
       and  then a data portion that holds the data bytes of the message.  For
       example:

       struct msgbuf {
	  long int mtype;
	  char mtext[]; }

       The mytpe field is set to the message type supplied by the sender.

       The mtext field is set to the message text.  Unless MSG_NOERROR is set,
       the  message  size will be less than or equal to the msgsz specified on
       the call to msgrcv().

RETURN VALUES
       Upon successful completion, the msgrcv() function returns a value equal
       to  the	number	of  bytes  actually  stored in mtext. Also, the kernel
       updates the msqid_ds structure associated with the message queue ID  as
       follows: Decrements msg_qnum by 1.  Sets msg_lrpid equal to the process
       ID of the calling process.  Sets msg_rtime equal to the	current	 time.
       [Tru64 UNIX]  Decrements msg_cbytes by the message text size.

       When the msgrcv() function fails, it returns a value of (ssize_t)-1 and
       sets errno to indicate the error.

ERRORS
       The msgrcv() function sets errno to the specified values for  the  fol‐
       lowing  conditions:  The	 number	 of  bytes  to be received in mtext is
       greater than msgsz and the MSG_NOERROR flag is not  set.	  The  calling
       process does not have permission for the operation.  Indicates that the
       requested address is in some way invalid, for example, out  of  bounds.
       The  message  queue  identified by the msqid parameter has been removed
       from the system.	 The operation was interrupted by a signal.  The msqid
       parameter  is not a valid message queue ID.  The queue does not contain
       a message of the requested type and the IPC_NOWAIT flag is set.

SEE ALSO
       Functions: msgctl(2), msgget(2), msgsnd(2), sigaction(2)

       Data Structures: msqid_ds(4)

       Standards: standards(5)

								     msgrcv(2)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net