ckptcreate(3) ckptcreate(3)
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.
ckptsetup
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.
ckptcreate
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)
Page 1
ckptcreate(3) ckptcreate(3)
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.
ckptrestart
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
Page 2
ckptcreate(3) ckptcreate(3)
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.
ckptremove
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.
ckptstat
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
Page 3
ckptcreate(3) ckptcreate(3)
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.
Page 4
ckptcreate(3) ckptcreate(3)
[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.
Page 5
ckptcreate(3) ckptcreate(3)
[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.
Page 6
ckptcreate(3) ckptcreate(3)
[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.
Page 7