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