qnx_vc_poll_parm()

change polling parameters for a virtual circuit

Synopsis:

#include <sys/kernel.h>
#include <sys/vc.h>
int qnx_vc_poll_parm( pid_t vid,
            struct _vc_poll_parm_set *parm_ptr );

The qnx_vc_poll_parm() function attempts to change the virtual circuit polling parameters to those pointed to by parm_ptr, on the node where the process manager may be communicated with using process ID vid.

If you wish to change the poll parameters on your local node, simply use PROC_PID for vid. If you wish to change the polling parameters on a remote node, you must attach a virtual circuit to the process manager on that remote node, using the qnx_vc_attach() function, and use its returned value for vid.

You should examine <sys/vc.h> for the appropriate definition of the _vc_poll_parm_set structure. It contains at least the following members:

poll_period: The length of time, in seconds, that the process manager waits between scans of the process table, when it checks for idle virtual circuits. Note that the value of poll_period should be coordinated with the value of idle_time, for best results.
idle_time: The length of time, in seconds, that the process manager allows a virtual circuit to remain idle before it sends a network poll packet to the remote node, asking the remote node to check the validity of the virtual circuit.
max_idle_time: The length of time, in seconds, that a virtual circuit may have no network transactions occur on it, before the virtual circuit is torn down, and any process blocked on it made READY.
num_polls: The number of times that the process manager transmits a network poll packet to a remote node, before it concludes that the remote node is permanently down.
num_qpkts: The maximum number of process manager-to-network manager queue packets that are consumed by the process manager every time it wakes up to scan the process table.

If you don't wish to change a parameter, simply set it to -1 and the process manager will ignore it. Also, it's considered good form to set all the zero* members of the _vc_poll_parm_set structure to zero to allow cleanly for future extensions to the structure.

Returns:

The qnx_vc_poll_parm() function returns a zero on success. Note that if zero is returned, the process manager has written all of the current virtual circuit poll parameters into the buffer pointed to by parm_ptr. A -1 is returned on failure, and errno is set.

Errors:

If any of the following conditions occurs, the qnx_vc_poll_parm() function returns -1, and sets errno to the corresponding value:

EINVAL: One of the members of the structure is invalid.
EPERM: Only a superuser process may perform this.
ESRCH: The vid is invalid.

Examples:

#include <stdio.h>
#include <errno.h>
#include <sys/vc.h>
#include <sys/kernel.h>

void main()
  {
    pid_t                     vid;
    struct _vc_poll_parm_set  poll_parm;

    /*
     *    change the maximum permitted virtual circuit
     *    idle time to 10 minutes ( 600 seconds ), leave
     *    all other poll parameters unchanged
     */
    poll_parm.poll_period   = -1;
    poll_parm.idle_time     = -1;
    poll_parm.max_idle_time = 600;
    poll_parm.num_polls     = -1;
    poll_parm.num_qpkts     = -1;
    poll_parm.zero1         = 0;
    poll_parm.zero2         = 0;

    /*
     *    could call qnx_vc_attach() here, if we wanted to
     *    change the poll parameters on another node
     */
    vid = PROC_PID;

    if( qnx_vc_poll_parm( vid, &poll_parm ) != 0 ) {
      printf( "error: process manager set errno = %d\n",
      errno );
    }

    /*
     *    if we want, we can now look at poll_parm, which
     *    the process manager has loaded with all of the
     *    current poll parameter values
     */
  }

Classification:

QNX

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

Caveats:

If you wish to change the poll parameters, your program must run as root.