w_clear Kernel Service

Purpose

Removes a watchdog timer from the list of watchdog timers known to the kernel.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/watchdog.h>

int w_clear ( w)
struct watchdog *w;

Parameter

Item Description
w Specifies the watchdog timer structure.

Description

The watchdog timer services, including the w_clear kernel service, are typically used to verify that an I/O operation completes in a reasonable time.

When the w_clear kernel service removes the watchdog timer, the w->count watchdog count is no longer decremented. In addition, the w->func watchdog timer function is no longer called.

In a uniprocessor environment, the call always succeeds. This is untrue in a multiprocessor environment, where the call will fail if the watchdog timer is being handled by another processor. Therefore, the function now has a return value, which is set to 0 if successful, or -1 otherwise. Funnelled device drivers do not need to check the return value since they run in a logical uniprocessor environment. Multiprocessor-safe and multiprocessor-efficient device drivers need to check the return value in a loop. In addition, if a driver uses locking, it must release and reacquire its lock within this loop, as shown below:

while (w_clear(&watchdog))
  release_then_reacquire_dd_lock;  
                    /* null statement if locks not used */
Note: The w_clear kernel service clears any attributes that were previously set by using the w_setattr() kernel service.

Execution Environment

The w_clear kernel service can be called from the process environment only.

Return Values

Item Description
0 Indicates that the watchdog timer was successfully removed.
-1 Indicates that the watchdog timer could not be removed.