ckpt_create(3)
ckpt_setup, ckpt_create, ckpt_restart, ckpt_stat, ckpt_remove - checkpoint and restart (CPR) library interfaces
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
NAME ckpt_setup, ckpt_create, ckpt_restart, ckpt_stat, ckpt_remove - checkpoint and restart (CPR) library interfaces SYNOPSIS #include <ckpt.h> int ckpt_setup(struct ckpt_args *args[], size_t nargs); int ckpt_create(const char *path, ckpt_id_t id, u_long type, struct ckpt_args *args[], size_t nargs); ckpt_id_t ckpt_restart(const char *path, struct ckpt_args *args[], size_t nargs); int ckpt_stat(const char *path, struct ckpt_stat **sp); int ckpt_remove(const char *path); DESCRIPTION The functions provided here are used to issue checkpoint and restart (CPR) requests to a process or group of processes. The ckpt_setup, ckpt_create, ckpt_restart, and ckpt_remove routines are implemented according to the IEEE standard POSIX 1003.1m Draft 1, with minor modifications (described below). The ckpt_stat function is an IRIX extension. Silicon Graphics intends to follow the future development of POSIX 1003.1m draft standards and endeavor to be compliant. ckpt_setup This routine currently does not perform any operation on IRIX systems. The interface is reserved for future addition of features. The POSIX ckpt_args structure defined in <ckpt.h> includes the following members: unsigned long ckpt_type; /* data type */ void *ckpt_data; /* data */ None of the POSIX ckpt_type definitions (CKPT_ID, CKPT_LOCK, CKPT_SIGNAL, CKPT_POSTRESTART, CKPT_PRERESTART, and CKPT_POSTCREATE) is implemented in IRIX because CPR handles these functions directly and transparently. ckpt_create This routine performs a checkpoint operation against a process or group of processes. It creates a set of checkpoint statefiles in the directory path, based on the user-specified checkpoint ID id, which has a type as defined in <ckpt.h>: P_PID for Unix process ID P_PGID for Unix process group ID P_SID for Unix process session ID; see termio(7) P_ASH for IRIX Array Session ID; see array_services(5) P_HID for process hierarchy (tree) rooted at that PID P_SGP for IRIX sproc shared group; see sproc(2) Note that ckpt_id_t is defined as an int64_t type in <ckpt.h>. The original POSIX standard requires id to be a pid_t which is not long enough to support the SGI 64-bit Array ID (ASH) number. However, any application binary using regular POSIX ckpt_create should work fine since type casting from 32-bit pid_t to 64-bit ckpt_id_t is transparent. The *args[] and nargs arguments from the POSIX draft standard, similar to the definitions in ckpt_setup, are ignored in IRIX. See cpr(1) for more information about the CPR attribute file $HOME/.cpr, checkpointable objects and limitations, the SIGCKPT and SIGRESTART signals, event handling using atcheckpoint(3C) and atrestart(3C), CPR security, and other issues. In addition to the CPR attribute file, a global variable cpr_flags defined in <ckpt.h> may specify checkpoint-related options. The option available is: CKPT_OPENFILE_DISTRIBUTE This flag alters the default location, which is the centralized directory given by path, for saving open files. Instead, open files are saved in the same directory where the original open files resided, with a new and unique name identifying them. For example, if a process has the /etc/passwd file open when a checkpoint is issued, with the CKPT_OPENFILE_DISTRIBUTE bit set, the /etc/passwd file is saved distributively in /etc/passwd.ckpt.pidXXX. Distribute mode is useful when disk space is a concern. However, the centralized mode (the default) is far more secure and self- contained. Users should be cautious when this bit is set. CKPT_CHECKPOINT_CONT This flag makes checkpoint target processes continue running after this checkpoint is finished. It overrides the default WILL policy, and the WILL policy specified in a user's CPR attribute file. CKPT_CHECKPOINT_KILL This flag kills checkpoint target processes after this checkpoint is finished. This is the default WILL policy, but overrides a CONT setting in the user's CPR attribute file. CKPT_CHECKPOINT_UPGRADE Use this flag only when issuing a checkpoint immediately before an operating system upgrade. This forces a save of all executable files and DSO libraries used by the current processes, so that target processes can be restarted in an upgraded environment. This flag must be used again if restarted processes must be recursively checkpointed in the new environment. ckpt_restart This routine restarts a set of processes from the statefile created at checkpoint time and identified by path. If a restart involves more than one process, the restart on all processes has to succeed before any process is enabled to run. If one restart in a group fails, all fail. In addition to the CPR attribute file, a global variable cpr_flags defined in <ckpt.h> may specify checkpoint-related options. The option available is: CKPT_RESTART_INTERACTIVE This flag makes a process or group of processes interactive (that is, subject to UNIX job-control), if the original processes were interactive. The calling process or the calling process' group leader becomes the group leader of restarted processes, but the original process group ID cannot be restored. Without this flag, the default is to restart target processes as an independent process group with the original group ID restored. ckpt_remove This routine deletes a statefile identified by path. The ckpt_remove routine removes all statefiles, including all the saved open files, mapped files, pipe data, and so forth. Only the superuser and the checkpoint owner can remove checkpoint files. ckpt_stat This routine is issued to existing statefiles in path to get basic information about the checkpointed processes saved there. The information is returned through a single-link list of ckpt_stat_t structures pointed by *sp, defined in <ckpt.h>. Each structure represents one process with the following members: struct ckpt_stat *cs_next; /* next process */ long cs_revision; /* CPR revision # */ pid_t cs_pid; /* proc pid */ pid_t cs_ppid; /* proc parent pid */ pid_t cs_pgrp; /* proc group leader */ pid_t cs_sid; /* session id */ struct stat cs_stat; /* see stat(2) */ char cs_nfiles; /* # of open files */ char cs_comm[PSCOMSIZ]; /* process name */ char cs_psargs[PSARGSZ]; /* and arguments */ char cs_cdir[MAXPATHLEN]; /* current directory */ int cs_board; /* board (sys/invent.h) */ int cs_cpu; /* cpu (sys/invent.h) */ int cs_abi; /* abi (sys/kabi.h) */ Applications can traverse through the next pointer cs_next to reach all processes associated with the statefile. It is important to note that although applications are not required to allocate the memory buffers needed for the sp linked list, it is an application's responsibility to release these memory buffers after examining the data. Applications should follow the cs_next link to free all of the ckpt_stat_t buffers. The following example shows how to use this function: ckpt_stat_t *sp, *sp_next; if (ckpt_stat(path, &sp)) < 0) return (-1); while (sp) { /* examine the data sp */ ... sp_next = sp->cs_next; free(sp); sp = sp_next; } NOTES All the CPR interfaces are found in the libcpr.so DSO, and are loaded at runtime if the -lcpr option is passed to cc(1) or ld(1). The contents of ckpt_stat_t are likely to change between releases. The ckpt_stat() interface is not supported for 32 bit abis running on 64 bit kernels. SEE ALSO cpr(1), cview(1), atcheckpoint(3C), atrestart(3C) IEEE standard POSIX 1003.1m Draft 1, October 1995. This draft standard is still being discussed and modified. No assurances can be given as to when P1003.1m will be approved or what it will contain. DIAGNOSTICS ckpt_setup is a no-op interface and currently always returns 0. ckpt_create returns 0 upon success. Upon failure it returns -1 and sets errno to indicate one of the following: [ECKPT] An unrecoverable resource, such as a socket connection, is associated with the target process. [EEXIST] The file named by path already exists. [ENOMEM] Checkpointing requires more memory than allowed by the hardware or available swap space. [ENOSPC] Space remaining on the device is insufficient for the checkpoint file. [EACCES] Search permission is denied on a component of the path prefix or write permission is denied on the parent directory of the checkpoint file to be created. [EPERM] The calling process does not have appropriate privileges to checkpoint one or more of the target processes. [EBUSY] A resource associated with the target process is in use by the system. [ELOOP] Too many symbolic links were encountered during resolution of the path argument; a loop probably exists. [ENOENT] The path argument names a nonexistent directory or points to an empty string. [ENOTDIR] A component of the path prefix is not a directory. [EROFS] The checkpoint file being created would reside on a read-only file system. [EINVAL] An invalid argument was passed to the function call. [ESRCH] The process or process group specified by id cannot be found. ckpt_restart returns the ID (ckpt_id_t) of the restarted process, process group leader, session leader, tree root of processes in an array, tree root of a process hierarchy, or sproc group leader. Note that the 64-bit return value ckpt_id_t is different from the 32-bit value POSIX specifies; however, the difference doesn't affect API compatibility. On failure, ckpt_restart returns -1 and sets errno to indicate one of the following: [ECKPT] Restart operation can not be completed or an unrecoverable resource is associated with the target process. [EBUSY] The system resource required to restart the processes requested is already taken at this moment. For example, a process ID is currently being used by another process and if the action ORIGINAL is set for the FORK function in the $HOME/.cpr attribute file. [EAGAIN] A system-imposed limit on the total number of processes belonging to a single user (CHILD_MAX) would be exceeded by restarting the target process set. [ENOMEM] Restarting the target process set requires more memory than allowed by the hardware or available swap space. [EACCES] Search permission is denied on a component of the path prefix. [EPERM] The real user ID of the calling process does not match the real user ID of one or more processes defined by the checkpoint file, or the calling process does not have appropriate privileges to restart one or more of the target processes. [ELOOP] Too many symbolic links were encountered during resolution of the path argument; a loop probably exists. [ENOENT] The path argument names a nonexistent directory or points to an empty string. [ENOTDIR] A component of the path prefix is not a directory. [EROFS] Restarted files would be created in a read-only file system. [EINVAL] An invalid argument was passed to the function call. ckpt_remove and ckpt_stat return 0 on success. On failure, they return -1 and set errno to indicate one of the following: [EACCES] Search permission is denied on a component of the path prefix, or write permission is denied on the parent directory of the checkpoint file to be removed. [EPERM] The calling process does not have appropriate privileges to remove or stat the target statefiles. [ELOOP] Too many symbolic links were encountered during resolution of the path argument; a loop probably exists. [ENOENT] The path argument names a nonexistent directory or points to an empty string. [ENOTDIR] A component of the path prefix is not a directory. [EROFS] The checkpoint file to be removed resides on a read-only file system. [EINVAL] The file to be removed is not a checkpoint file.