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