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.10 2008/05/02 02:05:04 swildner Exp $
  34 .\"
  35 .Dd June 29, 2007
  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 .Bl -tag -width ".Dv CKPT_FREEZE" -offset indent
  55 .It Dv CKPT_FREEZE
  56 Generate a checkpoint file.
  57 Currently
  58 .Fa pid
  59 must be -1 or the pid of the current process.
  60 The checkpoint file will be written out to
  61 .Fa fd ,
  62 and
  63 .Fa retval
  64 is unused but must be specified as -1.
  65 As a special case, if
  66 .Fa pid
  67 and
  68 .Fa fd
  69 are both specified as -1, the system will generate a checkpoint file
  70 using the system checkpoint template.
  71 .Pp
  72 This function returns 0 on success, -1 on error, and typically 1
  73 on resume.
  74 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.
  79 A user program which installs its 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
 100 .Xr exec 3
 101 call.
 102 .El
 103 .Sh RETURN VALUES
 104 Upon successful completion, the value 0 is typically returned.
 105 A checkpoint being resumed typically returns a positive value;
 106 otherwise the value -1 is returned and the global variable
 107 .Va errno
 108 is set to indicate the error.
 109 .Sh EXAMPLE
 110 .Bd -literal -offset indent -compact
 111 /*
 112  * Demonstrate checkpointing.  Use control-E to checkpoint
 113  * the program and 'checkpt -r x.ckpt' to resume it.
 114  */
 115 #include <sys/types.h>
 116 #include <sys/signal.h>
 117 #include <sys/checkpoint.h>
 118 #include <stdio.h>
 119 #include <unistd.h>
 120 #include <fcntl.h>
 121 #include <errno.h>
 122
 123 void docheckpoint(void);
 124
 125 int wantckpt;
 126
 127 void
 128 dockpt(int sig)
 129 {
 130     wantckpt = 1;
 131 }
 132
 133 int
 134 main(int argc, char** argv)
 135 {
 136      int i = 0;
 137
 138      signal(SIGCKPT, dockpt);
 139
 140      for (;;) {
 141         printf("iteration: %d\en", i);
 142         ++i;
 143         sleep(1);
 144         if (wantckpt) {
 145                 wantckpt = 0;
 146                 printf("Checkpoint requested\en");
 147                 docheckpoint();
 148         }
 149     }
 150     return(0);
 151 }
 152
 153 void
 154 docheckpoint(void)
 155 {
 156     int ret;
 157     int fd;
 158
 159     fd = open("x.ckpt", O_RDWR|O_CREAT|O_TRUNC, 0666);
 160     if (fd < 0) {
 161         printf("unable to create checkpoint file: %s\en",
 162                 strerror(errno));
 163         return;
 164     }
 165
 166     ret = sys_checkpoint(CKPT_FREEZE, fd, -1, -1);
 167     if (ret < 0) {
 168         printf("unable to checkpoint: %s\en",
 169                 strerror(errno));
 170     } else if (ret == 0) {
 171         printf("checkpoint successful, continuing\en");
 172     } else if (ret == 1) {
 173         printf("resuming from checkpoint.\en");
 174     } else {
 175         printf("unknown return value %d from sys_checkpoint\en", ret);
 176         exit(1);
 177     }
 178     /* note that the file descriptor is still valid on a resume */
 179     close(fd);
 180 }
 181 .Ed
 182 .Sh ERRORS
 183 .Bl -tag -width Er
 184 .It Bq Er EBADF
 185 The given
 186 .Fa fd
 187 is not a valid regular file, socket descriptor, or pipe.
 188 Note that not
 189 all systems necessarily support checkpointing to sockets and pipes.
 190 .It Bq Er EPERM
 191 The caller does not have permission to issue the checkpoint command.
 192 Checkpointing may be restricted or disabled using sysctls.
 193 .It Bq Er EIO
 194 An I/O error occurred while reading from the file system.
 195 .It Bq Er EINVAL
 196 An invalid parameter was specified.
 197 .El
 198 .Sh CHECKPOINT FEATURES
 199 The system checkpointing code will save the process register state (including
 200 floating point registers), signal state, file descriptors representing
 201 regular files or directories (anything that can be converted into a file
 202 handle for storage), and both shared and private memory mappings.
 203 Private, writable mappings are copied to the checkpoint file while shared
 204 mappings and stored by referencing the file handle and offset.
 205 Note that the system checkpointing code does not retain references to
 206 deleted files, so mappings and open descriptors of deleted files
 207 cannot be restored.
 208 Unpredictable operation will occur if a checkpoint-unaware program
 209 is restored and some of the underlying files mapped by the program
 210 have changed.
 211 .Pp
 212 The system checkpointing code is not able to retain the process pid, process
 213 group, user/group creds, or descriptors 0, 1, and 2.
 214 These will be inherited from whomever restores the checkpoint.
 215 .Pp
 216 When a checkpointed program is restored modified private mappings will
 217 be mapped from the checkpoint file itself, but major portions of the
 218 original program binary will be mapped from the original program binary.
 219 If the resumed program is checkpointed again the system will automatically
 220 copy any mappings from the original checkpoint file to the new one, since
 221 the original is likely being replaced.
 222 The caller must not truncate the existing checkpoint file when creating
 223 a new one or specify the existing file's file descriptor as the new
 224 one as this will destroy the data that the checkpoint operation needs
 225 to copy to the new file.
 226 It is best to checkpoint to a new file and then rename-over the old, or to
 227 .Xr remove 3
 228 the old file before creating the new
 229 one so it remains valid as long as the program continues to run.
 230 .Pp
 231 Threaded programs cannot currently be checkpointed.
 232 The program must be
 233 reduced to a single thread before it can be safely checkpointed.
 234 .Pp
 235 .Dv MAP_VPAGETABLE
 236 mappings cannot currently be checkpointed.
 237 A program must restore such mappings manually on resumption.
 238 Only regular file and
 239 anonymous memory mappings are checkpointed and restored.
 240 Device and other special mappings are not.
 241 Only regular file descriptors are checkpointed and restored.
 242 Devices, pipes, sockets, and other special descriptors are not.
 243 Memory wiring states are not checkpointed or restored.
 244 .Xr madvise 2
 245 states are not checkpointed or restored.
 246 Basic mapping permissions are checkpointed and restored.
 247 .Sh SECURITY
 248 The sysctl
 249 .Va kern.ckptgroup
 250 controls which group can use system checkpointing.
 251 By default, only users in the
 252 .Ql wheel
 253 group are allowed to checkpoint and restore processes.
 254 To allow users in any group to have this capability (risky), set sysctl
 255 .Va kern.ckptgroup
 256 to -1.
 257 .Sh SIGNALS
 258 Two signals are associated with checkpointing.
 259 .Dv SIGCKPT
 260 is delivered via the tty ckpt character, usually control-E.
 261 Its default action is to checkpoint a program and continue running it.
 262 The
 263 .Dv SIGCKPTEXIT
 264 signal can only be delivered by
 265 .Xr kill 2 .
 266 Its default action is to checkpoint a program and then exit.
 267 .Dv SIGCKPTEXIT
 268 might not be implemented by the system.
 269 Both signals are defined to
 270 be greater or equal to signal 32 and cannot be manipulated using legacy
 271 masking functions.
 272 .Pp
 273 If a program overrides the default action for a checkpoint signal the
 274 system will not undertake any action of its own.
 275 The program may issue
 276 the checkpoint command from the signal handler itself or simply set a
 277 reminder for later action.
 278 It is usually safest to set a reminder and
 279 do the actual checkpointing from your main loop.
 280 .Sh SEE ALSO
 281 .Xr checkpt 1 ,
 282 .Xr signal 3
 283 .Sh HISTORY
 284 The
 285 .Fn sys_checkpoint
 286 function call appeared in
 287 .Dx 1.1 .