console_arm()

trigger specified proxies when events occur on a console

Synopsis:

#include <sys/console.h>
int console_arm( struct _console_ctrl *cc,
                 int console,
                 pid_t proxy,
                 unsigned events );

Description:

The console_arm() function triggers the specified proxy whenever one of the indicated console events occurs on this console.

The argument cc is a pointer to a control structure that was returned by a previous call to console_open(). console has a value of 1 to represent the device named /dev/con1, a value of 2 for /dev/con2, and so on. A value of zero for console indicates the default console (that is, the one used by console_open()). A value of -1 for console indicates the currently visible console.

The console_arm() function always returns immediately. If any of the events are currently true, the proxy is triggered immediately. If not, the request is remembered, and the proxy is triggered when (and if) the indicated event occurs. The proxy is only triggered once.

If proxy is the bitwise complement of a signal number (that is, ~SIGXXX), that signal is generated on the calling process when the event occurs, instead of a proxy. See <signal.h> for the list of signals.

If proxy is -1, the specified events are discarded.

Events are defined in <sys/console.h>, and include such events as:

_CON_EVENT_OUTPUT: Output has changed on this console.
_CON_EVENT_SIZE: The console has changed size.
_CON_EVENT_INACTIVE: The console is no longer visible.
_CON_EVENT_ACTIVE: The console is now visible.

Returns:

0: Success
-1: An error occurred. errno is set to indicate the error.

Errors:

EINVAL: The control structure is in the wrong format.
ENXIO: The console value is invalid.

Examples:

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

char msg[100];

int main( void )
  {
    struct _console_ctrl *cc;
    int fd;
    pid_t proxy, pid;
    unsigned events, state;

    /*
     * Open up a channel to the console driver
     */
    fd = open( "/dev/con1", O_RDWR );
    cc = console_open( fd, O_RDWR );
    close( fd );

    events = ( _CON_EVENT_OUTPUT|_CON_EVENT_SIZE );
    proxy = qnx_proxy_attach( 0, 0, 0, -1 );
    /*
     * Clear events and setup triggers
     */
    console_state( cc, 0, 0, events );
    console_arm( cc, 0, proxy, events );

    /*
     * Main loop
     */

    for( ;; ) {
      /*
       * Wait for something to happen
       */
      pid = Receive( 0, &msg, sizeof( msg ) );

      if( pid == proxy ) {
        state = console_state( cc, 0, 0, events );
        if( state & _CON_EVENT_SIZE ) {
          printf( "Size has changed\n" );
      }
      if( state & _CON_EVENT_OUTPUT ) {
        printf( "Display has changed\n" );
      }
      console_arm( cc, 0, proxy, events );
      } else {
      /*
       * Process message from task or other proxy
       */
      }
    }

    /*
     * Close the channel
     */
    console_close( cc );
    return (EXIT_SUCCESS);
  }

Classification:

QNX

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