ckpt_setup man page on IRIX

Man page or keyword search:  
man Server   31559 pages
apropos Keyword Search (all sections)
Output format
IRIX logo
[printable version]



ckpt_create(3)							ckpt_create(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.

   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)

									Page 1

ckpt_create(3)							ckpt_create(3)

     P_JID   for IRIX job ID

     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 or the SGI 64-bit
     Job ID (JID) 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 options
     available are:

     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.

									Page 2

ckpt_create(3)							ckpt_create(3)

     CKPT_ATTRFILE_IN_CWD
	  Use this flag if you would like to checkpoint using the CPR
	  attribute file residing in your current working directory (versus
	  $HOME/.cpr).

   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 restart-related options.  The options
     available are:

     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_ATTRFILE_IN_CWD
	  Use this flag if you would like to restart using the CPR attribute
	  file residing in your current working directory (versus $HOME/.cpr).

     CKPT_RESTART_MIGRATE
	  This flag migrates process memory so it is restored to the location
	  in the system topology where the restart is executing (within a
	  specific cpuset, within the global cpuset, etc.).  Without this
	  option, the default restart behavior on NUMA systems is to restore
	  process memory back to where it was at the time of the checkpoint.
	  This option has no effect on non-NUMA systems.  See the migration(3)
	  man page for scenarios which may prevent pages from migrating
	  properly.

   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:

									Page 3

ckpt_create(3)							ckpt_create(3)

	    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.

     All the CPR interfaces log their error and notice messages to SYSLOG
     file.

									Page 4

ckpt_create(3)							ckpt_create(3)

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.

									Page 5

ckpt_create(3)							ckpt_create(3)

     [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, sproc group leader, or job.  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.

									Page 6

ckpt_create(3)							ckpt_create(3)

     [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.

									Page 7

[top]

List of man pages available for IRIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net