Creceive()

check for a message from a process

Synopsis:

#include <sys/kernel.h>
pid_t Creceive( pid_t pid, void *msg,
                unsigned nbytes );

The kernel function Creceive() checks to see if a message is waiting from the process identified by pid. If pid is nonzero, only messages from pid are received. If pid is zero, a message from any process or proxy is received. If a suitable message is waiting, it is received into the message buffer pointed to by msg, and is limited to a maximum size of nbytes.

By default, messages sent to a process are queued in time order. This may be changed to priority order by using the qnx_pflags() function.

This function's behavior is identical to that of Receive(), except that it doesn't block if a message isn't waiting. This function can be used to poll for messages. In general this is bad practice, and designs should attempt to avoid polling.

The number of bytes transferred is the minimum of that specified by both the sender and the receiver. The send data never overflows the buffer area provided by the receiver.

If a message is received, Creceive() changes the state of the sending task from SEND BLOCKED to REPLY BLOCKED.

Creceive() is a simple cover function. It builds a single part _mxfer_entry on the stack, and calls Creceivemx() (the real kernel function). It's provided for convenience, as it's easier to use than Creceivemx() for simple messages.

Returns:

The process ID of the process that sent the message. This ID is needed to reply to the message. If an error occurs, or no process is waiting, -1 is returned, and errno is set.

Errors:

EFAULT: In order to complete the message exchange, the current process would have incurred a segment violation. You need to make your buffer(s) larger, or limit the number of bytes allowed in the transfer.
EINTR: Call interrupted by a signal.
ENOMSG: No message is available.
ESRCH: The process pid doesn't exist.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/kernel.h>

int main( void )
  {
    pid_t pid;
    short unsigned msg;

    if( pid = fork() )
      {
      Yield();  /* make sure the child runs first */
      Yield();  /* make sure the child runs first */
      Send( pid, &msg, &msg,
            sizeof( msg ), sizeof( msg ) );
      exit( 0 );
      }

    while( ( pid = Creceive( 0, &msg, sizeof( msg ) ) )
            == -1 )
      printf( "No message.\n" );

    printf( "Message.\n" );
    Reply( pid, &msg, sizeof( msg ) );
    return (EXIT_SUCCESS);
  }

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes, but modifies errno
Thread	Yes

Caveats:

Creceive() is a macro.