lib/libc/sys/sys_checkpoint.2

   1 .\" Copyright (c) 2003,2004 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $DragonFly: src/lib/libc/sys/sys_checkpoint.2,v 1.2 2004/11/24 02:56:43 hmp Exp $
  34 .\"
  35 .Dd November 22, 2004
  36 .Dt SYS_CHECKPOINT 2
  37 .Os
  38 .Sh NAME
  39 .Nm sys_checkpoint
  40 .Nd checkpoint or restore a process
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/checkpoint.h
  46 .Ft int
  47 .Fn sys_checkpoint "int type" "int fd" "pid_t pid" "int retval"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn sys_checkpoint
  51 system call executes a checkpoint function as specified by
  52 .Fa type .
  53 Supported types are as follows:
  54 .Pp
  55 .Bl -tag -width CKPT_FREEZE -offset indent
  56 .It Dv CKPT_FREEZE
  57 Generate a checkpoint file.
  58 Currently
  59 .Fa pid
  60 must be -1 or the pid of the current process.
  61 The checkpoint file will be written out to
  62 .Fa fd ,
  63 and
  64 .Fa retval
  65 is unused but must be specified as -1.
  66 As a special case, if
  67 .Fa pid
  68 and
  69 .Fa fd
  70 are both specified as -1, the system will generate a checkpoint file
  71 using the system checkpoint template.
  72 .Pp
  73 This function returns 0 on success, -1 on error, and typically 1
  74 on resume.  The value returned on resume is controlled by the
  75 .Fa retval
  76 argument passed to
  77 .Fn sys_checkpoint
  78 when resuming a checkpoint file.  A user program which installs its
  79 own
  80 .Dv SIGCKPT
  81 signal handler and calls
  82 .Fn sys_checkpoint
  83 manually thus has control over both termination/continuance and
  84 resumption.
  85 .It Dv CKPT_THAW
  86 Restore a checkpointed program.
  87 The
  88 .Fa pid
  89 must be specified as -1, and
  90 .Fa fd
  91 represents the checkpoint file.
  92 The
  93 .Fa retval
  94 specifies the value returned to the resumed program if
  95 .Fn sys_checkpoint
  96 was called directly.
  97 .Pp
  98 The checkpointed program will replace the current program, similar to
  99 an exec call.
 100 .El
 101 .Sh RETURN VALUES
 102 Upon successful completion, the value 0 is typically returned.  A checkpoint
 103 being resumed typically returns a positive value; otherwise the value -1
 104 is returned and the global variable
 105 .Li errno
 106 is set to indicate the error.
 107 .Sh ERRORS
 108 .Bl -tag -width Er
 109 .It Bq Er EBADF
 110 The given
 111 .Fa fd
 112 is not a valid regular file, socket descriptor, or pipe.  Note that not
 113 all systems necessarily support checkpointing to sockets and pipes.
 114 .It Bq Er EPERM
 115 The caller does not have permission to issue the checkpoint command.
 116 Checkpointing may be restricted or disabled using sysctls.
 117 .It Bq Er EIO
 118 An I/O error occurred while reading from the file system.
 119 .It Bq Er EINVAL
 120 An invalid parameter was specified.
 121 .El
 122 .Sh CHECKPOINT FEATURES
 123 The system checkpointing code will save the process register state (including
 124 floating point registers), signal state, file descriptors representing
 125 regular files or directories (anything that can be converted into a file
 126 handle for storage), and both shared and private memory mappings.
 127 Private, writable mappings are copied to the checkpoint file while shared
 128 mappings and stored by referencing the file handle and offset.
 129 Note that the system checkpointing code does not retain references to
 130 deleted files, so mappings and open descriptors of deleted files
 131 cannot be restored.
 132 Unpredictable operation will occur if a checkpoint-unaware program
 133 is restored and some of the underlying files mapped by the program
 134 have changed.
 135 .Pp
 136 The system checkpointing code is not able to retain the process pid, process
 137 group, user/group creds, or descriptors 0, 1, and 2.  These will be inherited
 138 from whomever restores the checkpoint.
 139 .Pp
 140 When a checkpointed program is restored modified private mappings will
 141 be mapped from the checkpoint file itself, but major portions of the
 142 original program binary will be mapped from the original program binary.
 143 If the resumed program is checkpointed again the system will automatically
 144 copy any mappings from the original checkpoint file to the new one, since
 145 the original is likely being replaced.
 146 The caller must not truncate the existing checkpoint file when creating
 147 a new one or specify the existing file's file descriptor as the new
 148 one as this will destroy the data that the checkpoint operation needs
 149 to copy to the new file.
 150 .Sh SECURITY
 151 The sysctl
 152 .Em kern.ckptgroup
 153 controls which group can use system checkpointing.
 154 By default, only users in the
 155 .Ql wheel
 156 group are allowed to checkpoint and restore processes.
 157 To allow users in any group to have this capability (risky), set sysctl
 158 .Em kern.ckptgroup
 159 to -1.
 160 .Sh SIGNALS
 161 Two signals are associated with checkpointing.
 162 .Dv SIGCKPT
 163 is delivered via the tty ckpt character, usually control-E.  Its default
 164 action is to checkpoint a program and continue running it.  The
 165 .Dv SIGCKPTEXIT
 166 signal can only be delivered by
 167 .Xr kill 2 .
 168 Its default action is to checkpoint a program and then exit.
 169 .Dv SIGCKPTEXIT
 170 might not be implemented by the system.  Both signals are defined to
 171 be greater or equal to signal 32 and cannot be manipulated using legacy
 172 masking functions.
 173 .Pp
 174 If a program overrides the default action for a checkpoint signal the
 175 system will not undertake any action of its own.  The program may issue
 176 the checkpoint command from the signal handler itself or simply set a
 177 reminder for later action.  It is usually safest to set a reminder and
 178 do the actual checkpointing from your main loop.
 179 .Sh EXAMPLE
 180 .Bd -literal -offset indent -compact
 181
 182 /*
 183  * Demonstrate checkpointing.  Use control-E to checkpoint
 184  * the program and 'checkpt -r x.ckpt' to resume it.
 185  */
 186 #include <sys/types.h>
 187 #include <sys/signal.h>
 188 #include <sys/checkpoint.h>
 189 #include <stdio.h>
 190 #include <unistd.h>
 191 #include <fcntl.h>
 192 #include <errno.h>
 193
 194 void docheckpoint(void);
 195
 196 int wantckpt;
 197
 198 void
 199 dockpt(int sig)
 200 {
 201     wantckpt = 1;
 202 }
 203
 204 int
 205 main(int argc, char** argv)
 206 {
 207      int i = 0;
 208
 209      signal(SIGCKPT, dockpt);
 210
 211      for (;;) {
 212         printf("iteration: %d\en", i);
 213         ++i;
 214         sleep(1);
 215         if (wantckpt) {
 216                 wantckpt = 0;
 217                 printf("Checkpoint requested\en");
 218                 docheckpoint();
 219         }
 220     }
 221     return(0);
 222 }
 223
 224 void
 225 docheckpoint(void)
 226 {
 227     int ret;
 228     int fd;
 229
 230     fd = open("x.ckpt", O_RDWR|O_CREAT|O_TRUNC, 0666);
 231     if (fd < 0) {
 232         printf("unable to create checkpoint file: %s\en",
 233                 strerror(errno));
 234         return;
 235     }
 236
 237     ret = sys_checkpoint(CKPT_FREEZE, fd, -1, -1);
 238     if (ret < 0) {
 239         printf("unable to checkpoint: %s\en",
 240                 strerror(errno));
 241     } else if (ret == 0) {
 242         printf("checkpoint successful, continuing\en");
 243     } else if (ret == 1) {
 244         printf("resuming from checkpoint.\en");
 245     } else {
 246         printf("unknown return value %d from sys_checkpoint\en", ret);
 247         exit(1);
 248     }
 249     /* note that the file descriptor is still valid on a resume */
 250     close(fd);
 251 }
 252 .Ed
 253 .Sh SEE ALSO
 254 .Xr checkpt 1 ,
 255 .Xr signal 3
 256 .Sh HISTORY
 257 The
 258 .Fn sys_checkpoint
 259 function call
 260 appeared in
 261 DragonFly 1.1 .