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