qnx_proxy_attach()

create a proxy process

Synopsis:

#include <sys/proxy.h>
pid_t qnx_proxy_attach( pid_t pid,
                        char *data,
                        int nbytes, int priority );

The qnx_proxy_attach() function creates a proxy process with a canned message of length nbytes pointed to by data. The proxy is attached to process pid. If pid is zero, it's attached to the calling process; this is the normal case. The proxy can be assigned a priority. If priority is -1, the proxy is assigned the priority of the calling process.

If anyone triggers the proxy, the proxy sends its canned message to its owner. The process that triggers the proxy won't block, and the data sent to the proxy is discarded. The proxy acts as a messenger that's always ready to send its message. You cause it to send this message by sending anything to it.

Proxies are most often used in interrupt handlers to wake a process that is receive-blocked, waiting for a message from a client or the hardware via an interrupt. They're also used in cases where a simple nonblocking send is required between processes. Note that proxy messages are queued. If a proxy is triggered 1000 times then the process it is sending to receives 1000 messages all the same. A proxy may have at most 65535 messages pending.

A proxy can send a zero-byte message by setting nbytes to zero. In this case, the owner has to check the pid returned by Receive() against the pid of a known proxy id. A zero-byte message is slightly faster than one with any data.

A proxy message can't be longer than _QNX_PROXY_SIZE_MAX bytes. (see <limits.h> ).

Returns:

A process ID. On error, -1 is returned, and errno is set.

Errors:

EAGAIN: There are no free process entries to make a proxy.
EINVAL: The length of the proxy's message (nbytes) exceeds _QNX_PROXY_SIZE_MAX bytes. (see <limits.h> ).
ENOMEM: The process manager doesn't have enough memory to hold the proxy's message.
ESRCH: The process pid (if nonzero) doesn't exist.

Examples:

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

void main()
  {
    pid_t proxy;

    proxy = qnx_proxy_attach( 0, 0, 0, -1 );
    if( proxy == -1 ) {
      printf( "Unable to attach a proxy.\n" );
      return;
    }

    if( fork() )
      server();           /* Parent owns the proxy  */
    else
      client( proxy );    /* Child triggers the proxy */
  }

void client( pid_t proxy )
  {
    int i;

    for( i = 0 ; i < 10 ; ++i ) {
      printf( "Trigger %d\n", proxy );
      Trigger( proxy );
    }
  }

void server()
  {
    int i;
    pid_t pid;
    unsigned msg;

    for( i = 0 ; i < 10 ; ++i ) {
      pid = Receive( 0, &msg, sizeof( msg ) );
      printf( "Received from %d\n", pid );
    }
  }

Classification:

QNX

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