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.5 2006/02/17 19:35:06 swildner Exp $ 34.\" 35.Dd November 22, 2004 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 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. The value returned on resume is controlled by the 75.Fa retval 76argument passed to 77.Fn sys_checkpoint 78when resuming a checkpoint file. A user program which installs its 79own 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 exec call. 100.El 101.Sh RETURN VALUES 102Upon successful completion, the value 0 is typically returned. A checkpoint 103being resumed typically returns a positive value; otherwise the value -1 104is returned and the global variable 105.Li errno 106is set to indicate the error. 107.Sh EXAMPLE 108.Bd -literal -offset indent -compact 109 110/* 111 * Demonstrate checkpointing. Use control-E to checkpoint 112 * the program and 'checkpt -r x.ckpt' to resume it. 113 */ 114#include <sys/types.h> 115#include <sys/signal.h> 116#include <sys/checkpoint.h> 117#include <stdio.h> 118#include <unistd.h> 119#include <fcntl.h> 120#include <errno.h> 121 122void docheckpoint(void); 123 124int wantckpt; 125 126void 127dockpt(int sig) 128{ 129 wantckpt = 1; 130} 131 132int 133main(int argc, char** argv) 134{ 135 int i = 0; 136 137 signal(SIGCKPT, dockpt); 138 139 for (;;) { 140 printf("iteration: %d\en", i); 141 ++i; 142 sleep(1); 143 if (wantckpt) { 144 wantckpt = 0; 145 printf("Checkpoint requested\en"); 146 docheckpoint(); 147 } 148 } 149 return(0); 150} 151 152void 153docheckpoint(void) 154{ 155 int ret; 156 int fd; 157 158 fd = open("x.ckpt", O_RDWR|O_CREAT|O_TRUNC, 0666); 159 if (fd < 0) { 160 printf("unable to create checkpoint file: %s\en", 161 strerror(errno)); 162 return; 163 } 164 165 ret = sys_checkpoint(CKPT_FREEZE, fd, -1, -1); 166 if (ret < 0) { 167 printf("unable to checkpoint: %s\en", 168 strerror(errno)); 169 } else if (ret == 0) { 170 printf("checkpoint successful, continuing\en"); 171 } else if (ret == 1) { 172 printf("resuming from checkpoint.\en"); 173 } else { 174 printf("unknown return value %d from sys_checkpoint\en", ret); 175 exit(1); 176 } 177 /* note that the file descriptor is still valid on a resume */ 178 close(fd); 179} 180.Ed 181.Sh ERRORS 182.Bl -tag -width Er 183.It Bq Er EBADF 184The given 185.Fa fd 186is not a valid regular file, socket descriptor, or pipe. Note 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. These will be inherited 212from 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. 224.Sh SECURITY 225The sysctl 226.Em kern.ckptgroup 227controls which group can use system checkpointing. 228By default, only users in the 229.Ql wheel 230group are allowed to checkpoint and restore processes. 231To allow users in any group to have this capability (risky), set sysctl 232.Em kern.ckptgroup 233to -1. 234.Sh SIGNALS 235Two signals are associated with checkpointing. 236.Dv SIGCKPT 237is delivered via the tty ckpt character, usually control-E. Its default 238action is to checkpoint a program and continue running it. The 239.Dv SIGCKPTEXIT 240signal can only be delivered by 241.Xr kill 2 . 242Its default action is to checkpoint a program and then exit. 243.Dv SIGCKPTEXIT 244might not be implemented by the system. Both signals are defined to 245be greater or equal to signal 32 and cannot be manipulated using legacy 246masking functions. 247.Pp 248If a program overrides the default action for a checkpoint signal the 249system will not undertake any action of its own. The program may issue 250the checkpoint command from the signal handler itself or simply set a 251reminder for later action. It is usually safest to set a reminder and 252do the actual checkpointing from your main loop. 253.Sh SEE ALSO 254.Xr checkpt 1 , 255.Xr signal 3 256.Sh HISTORY 257The 258.Fn sys_checkpoint 259function call 260appeared in 261.Dx 1.1 . 262