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 49The 50.Fn sys_checkpoint 51system call executes a checkpoint function as specified by 52.Fa type . 53Supported types are as follows: 54.Pp 55.Bl -tag -width ".Dv CKPT_FREEZE" -offset indent 56.It Dv CKPT_FREEZE 57Generate a checkpoint file. 58Currently 59.Fa pid 60must be -1 or the pid of the current process. 61The checkpoint file will be written out to 62.Fa fd , 63and 64.Fa retval 65is unused but must be specified as -1. 66As a special case, if 67.Fa pid 68and 69.Fa fd 70are both specified as -1, the system will generate a checkpoint file 71using the system checkpoint template. 72.Pp 73This function returns 0 on success, -1 on error, and typically 1 74on resume. 75The value returned on resume is controlled by the 76.Fa retval 77argument passed to 78.Fn sys_checkpoint 79when resuming a checkpoint file. 80A user program which installs its own 81.Dv SIGCKPT 82signal handler and calls 83.Fn sys_checkpoint 84manually thus has control over both termination/continuance and 85resumption. 86.It Dv CKPT_THAW 87Restore a checkpointed program. 88The 89.Fa pid 90must be specified as -1, and 91.Fa fd 92represents the checkpoint file. 93The 94.Fa retval 95specifies the value returned to the resumed program if 96.Fn sys_checkpoint 97was called directly. 98.Pp 99The checkpointed program will replace the current program, similar to 100an 101.Xr exec 3 102call. 103.El 104.Sh RETURN VALUES 105Upon successful completion, the value 0 is typically returned. 106A checkpoint being resumed typically returns a positive value; 107otherwise the value -1 is returned and the global variable 108.Va errno 109is 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 124void docheckpoint(void); 125 126int wantckpt; 127 128void 129dockpt(int sig) 130{ 131 wantckpt = 1; 132} 133 134int 135main(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 154void 155docheckpoint(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 186The given 187.Fa fd 188is not a valid regular file, socket descriptor, or pipe. 189Note that not 190all systems necessarily support checkpointing to sockets and pipes. 191.It Bq Er EPERM 192The caller does not have permission to issue the checkpoint command. 193Checkpointing may be restricted or disabled using sysctls. 194.It Bq Er EIO 195An I/O error occurred while reading from the file system. 196.It Bq Er EINVAL 197An invalid parameter was specified. 198.El 199.Sh CHECKPOINT FEATURES 200The system checkpointing code will save the process register state (including 201floating point registers), signal state, file descriptors representing 202regular files or directories (anything that can be converted into a file 203handle for storage), and both shared and private memory mappings. 204Private, writable mappings are copied to the checkpoint file while shared 205mappings and stored by referencing the file handle and offset. 206Note that the system checkpointing code does not retain references to 207deleted files, so mappings and open descriptors of deleted files 208cannot be restored. 209Unpredictable operation will occur if a checkpoint-unaware program 210is restored and some of the underlying files mapped by the program 211have changed. 212.Pp 213The system checkpointing code is not able to retain the process pid, process 214group, user/group creds, or descriptors 0, 1, and 2. 215These will be inherited from whomever restores the checkpoint. 216.Pp 217When a checkpointed program is restored modified private mappings will 218be mapped from the checkpoint file itself, but major portions of the 219original program binary will be mapped from the original program binary. 220If the resumed program is checkpointed again the system will automatically 221copy any mappings from the original checkpoint file to the new one, since 222the original is likely being replaced. 223The caller must not truncate the existing checkpoint file when creating 224a new one or specify the existing file's file descriptor as the new 225one as this will destroy the data that the checkpoint operation needs 226to copy to the new file. 227It is best to checkpoint to a new file and then rename-over the old, or to 228.Xr remove 3 229the old file before creating the new 230one so it remains valid as long as the program continues to run. 231.Pp 232Threaded programs cannot currently be checkpointed. 233The program must be 234reduced to a single thread before it can be safely checkpointed. 235.Pp 236.Dv MAP_VPAGETABLE 237mappings cannot currently be checkpointed. 238A program must restore such mappings manually on resumption. 239Only regular file and 240anonymous memory mappings are checkpointed and restored. 241Device and other special mappings are not. 242Only regular file descriptors are checkpointed and restored. 243Devices, pipes, sockets, and other special descriptors are not. 244Memory wiring states are not checkpointed or restored. 245.Xr madvise 2 246states are not checkpointed or restored. 247Basic mapping permissions are checkpointed and restored. 248.Sh SECURITY 249The sysctl 250.Va kern.ckptgroup 251controls which group can use system checkpointing. 252By default, only users in the 253.Ql wheel 254group are allowed to checkpoint and restore processes. 255To allow users in any group to have this capability (risky), set sysctl 256.Va kern.ckptgroup 257to -1. 258.Sh SIGNALS 259Two signals are associated with checkpointing. 260.Dv SIGCKPT 261is delivered via the tty ckpt character, usually control-E. 262Its default action is to checkpoint a program and continue running it. 263The 264.Dv SIGCKPTEXIT 265signal can only be delivered by 266.Xr kill 2 . 267Its default action is to checkpoint a program and then exit. 268.Dv SIGCKPTEXIT 269might not be implemented by the system. 270Both signals are defined to 271be greater or equal to signal 32 and cannot be manipulated using legacy 272masking functions. 273.Pp 274If a program overrides the default action for a checkpoint signal the 275system will not undertake any action of its own. 276The program may issue 277the checkpoint command from the signal handler itself or simply set a 278reminder for later action. 279It is usually safest to set a reminder and 280do the actual checkpointing from your main loop. 281.Sh SEE ALSO 282.Xr checkpt 1 , 283.Xr signal 3 284.Sh HISTORY 285The 286.Fn sys_checkpoint 287function call appeared in 288.Dx 1.1 . 289