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