kwpar_checkpoint_status Kernel Service

Purpose

Provides a method for kernel services to inform the system that an event occurred within a workload partition (WPAR) that denies or subsequently reallows a checkpoint of the WPAR.

Syntax

#include <sys/wparid.h>
int kwpar_checkpoint_status (kcid, cmd, varp)
cid_t kcid;
int cmd;
void * varp;

Parameters

Item Description
cmd An integer command that informs the API what action to take on behalf of the caller.
kcid The WPAR ID where the command operation is to take place.
varp A void pointer to different elements that depends on the cmd parameter.
  • If the cmd parameter is set to the WPAR_CHECKPOINT_TRY value, the varp parameter is a pointer to an integer variable that contains the number of seconds that the caller is willing to wait before a blocking event is removed.
  • If the cmd parameter is set to the WPAR_CHECKPOINT_DENY value, the varp parameter is a pointer to a null terminated character string that contains a user readable reason for posting the event.

Cmd Types

The cmd parameter is supplied on input to the kwpar_checkpoint_status API and describes the type of action or event notification the caller is expecting. The following cmd types are supported:

Item Description
WPAR_CHECKPOINT_DENY The caller is experiencing an event within the WPAR identified by the kcid parameter that would deny a checkpoint operation. The caller must supply a pointer to a user readable character string in the varp parameter.
WPAR_CHECKPOINT_ALLOW The caller is clearing a previous checkpoint denial operation. Deny and allow operations are cumulative and thus each denial operation must be matched with an allow operation before a checkpoint is finally reallowed.
WPAR_CHECKPOINT_TRY Used by the AIX® checkpoint system itself. The caller supplies the varp pointer to an integer that contains a “willing to wait” timeout in seconds before a checkpoint denial operation is cleared.
WPAR_CHECKPOINT_CLEAR Used by the AIX checkpoint system itself. The caller completed a checkpoint after a successful WPAR_TRY_CHKPNT operation.
WPAR_RESTART_CLEAR Used by the AIX checkpoint system itself. The caller completed a restart. The WPAR restart state is initially set when the WPAR is re-created on the arrival system.

Description

The kwpar_checkpoint_status kernel service provides a mechanism for kernel services to inform or query the system about a checkpoint denial event. Kernel extensions that experience a temporary event which prevents a WPAR from being the target of a checkpoint operation, must use this API to deny and then to subsequently reallow a checkpoint when the event clears. An example denial event might occur if a device open is in an unserialized interim state that cannot handle a checkpoint operation.

Execution Environment

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

Return Values

Item Description
0 Success.
non-zero Failure.

Error Codes

The kwpar_checkpoint_status service fails if one or more of the following errors occur:

Item Description
EINVAL The caller supplied an invalid cmd or other parameter.
ENOENT No WPAR with the kcid ID is active in the system.
EBUSY Either of the following situations can lead to the EBUSY error.
  • WPAR is in a checkpoint or restart state. The caller is unsuccessful in a WPAR_CHECKPOINT_DENY operation.
  • WPAR is in a state that cannot participate in a checkpoint. The caller is unsuccessful in a WPAR_CHECKPOINT_TRY operation.
ETIMEDOUT The caller is waiting for a timeout period during a WPAR_CHECKPOINT_TRY operation but the timer expired.