NAME

C SPECIFICATION

#include <cx/ModuleCommand.h>

void *cxInputAdd( int fd,
    cxInputMask condition,
    cxInputCallbackProc callback,
    void *client_data)

FORTRAN SPECIFICATION

None

PARAMETERS

fd

The Unix file descripter to monitor. Unix file descriptors are small integers zero or greater and are generally the return value from an open() system call.

condition

This routine can be used to monitor a file descripter for any combination of conditions: available input, writability, or an exception condition. The value of the condition argument can be cx_InputReadMask , cx_InputWriteMask , or cx_InputExceptMask. These correspond to the read set, write set, and exception set in the Unix select(2) system call. Though these values contain the word Mask, they cannot be combined with an inclusive ``or'' operation.

callback

The user callback routine. This subroutine is called by the control wrapper when one of the conditions is satisfied. See below for the calling sequence used by cxInputAdd.

client_data

Arbitrary client data. This value is passed to the user callback routine when the condition occurs.

DESCRIPTION

The return value of this function is an opaque handle that can be used in a subsequent call to cxInputRemove for removing the monitoring function.

When the specified condition occurs, the Control Wrapper will call the function named in the callback argument to cxInputAdd. This function is assumed to have three formal arguments, as follows:

void (*cxInputCallbackProc)( void *client_data,
     int fd,
     void *handle)

The argument client_data is the value passed in to cxInputAdd. Argument fd is the Unix file descripter that is affected. Argument handle is the return value from cxInputAdd that corresponds to this activity. It may be used in a call to cxInputRemove if conditions warrant.

The action of calling a callback procedure is not equivalent to actually firing the module. If the callback routine decides that the module should be fired based on new information resulting from the file descriptor activity, it should use cxFireASAP to schedule the future firing of the module.

Because of the synchronous nature of the firing behavior of IRIS Explorer modules, a file descripter callback procedure will never be called when the module is firing. These callbacks are only called when the module is quiescent.

This facility works for both X and non-X modules.

EXAMPLE

The following code fragment shows an example of how this routine might be used within a module:

#include <cx/Typedefs.h>
#include <cx/ModuleCommand.h>
      ...
      FILE *fd;
      void *handle;
      void haveData();
      ...
      /*
       * Use "popen(3E)" to start some external shell command.
       */
      if ( (fd=popen( command, "r" )) == NULL) {
            cxModAlert( "Command failed." );
            return;
      }
      /*
       * Now attach the file descripter to the scheduler.
       */
      handle = cxInputAdd( fileno(fd), cx_InputReadMask,
            haveData, (void *)fd );
      ...
/*
 * User callback -- called whenever data can be read.
 */
void haveData( client_data, fd, handle )
void *client_data;
int fd;
void *handle;
{
      char buf[BUFSIZ];
      int len;
      len = read( fd, buf, sizeof buf );
      /*
       * If EOF or error was encountered, close the pipe and remove the
       * descripter from the scheduler.
       */
      if (len <= 0) {
            pclose( (FILE *)client_data );
            cxInputRemove( handle );
      }
      /*
       * If conditions warrent, schedule the module for firing.
       */
      if ( /* some condition */ ) {
            cxFireASAP();
      }
}

SEE ALSO