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.2 2004/11/24 02:56:43 hmp 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 ERRORS 108.Bl -tag -width Er 109.It Bq Er EBADF 110The given 111.Fa fd 112is not a valid regular file, socket descriptor, or pipe. Note that not 113all systems necessarily support checkpointing to sockets and pipes. 114.It Bq Er EPERM 115The caller does not have permission to issue the checkpoint command. 116Checkpointing may be restricted or disabled using sysctls. 117.It Bq Er EIO 118An I/O error occurred while reading from the file system. 119.It Bq Er EINVAL 120An invalid parameter was specified. 121.El 122.Sh CHECKPOINT FEATURES 123The system checkpointing code will save the process register state (including 124floating point registers), signal state, file descriptors representing 125regular files or directories (anything that can be converted into a file 126handle for storage), and both shared and private memory mappings. 127Private, writable mappings are copied to the checkpoint file while shared 128mappings and stored by referencing the file handle and offset. 129Note that the system checkpointing code does not retain references to 130deleted files, so mappings and open descriptors of deleted files 131cannot be restored. 132Unpredictable operation will occur if a checkpoint-unaware program 133is restored and some of the underlying files mapped by the program 134have changed. 135.Pp 136The system checkpointing code is not able to retain the process pid, process 137group, user/group creds, or descriptors 0, 1, and 2. These will be inherited 138from whomever restores the checkpoint. 139.Pp 140When a checkpointed program is restored modified private mappings will 141be mapped from the checkpoint file itself, but major portions of the 142original program binary will be mapped from the original program binary. 143If the resumed program is checkpointed again the system will automatically 144copy any mappings from the original checkpoint file to the new one, since 145the original is likely being replaced. 146The caller must not truncate the existing checkpoint file when creating 147a new one or specify the existing file's file descriptor as the new 148one as this will destroy the data that the checkpoint operation needs 149to copy to the new file. 150.Sh SECURITY 151The sysctl 152.Em kern.ckptgroup 153controls which group can use system checkpointing. 154By default, only users in the 155.Ql wheel 156group are allowed to checkpoint and restore processes. 157To allow users in any group to have this capability (risky), set sysctl 158.Em kern.ckptgroup 159to -1. 160.Sh SIGNALS 161Two signals are associated with checkpointing. 162.Dv SIGCKPT 163is delivered via the tty ckpt character, usually control-E. Its default 164action is to checkpoint a program and continue running it. The 165.Dv SIGCKPTEXIT 166signal can only be delivered by 167.Xr kill 2 . 168Its default action is to checkpoint a program and then exit. 169.Dv SIGCKPTEXIT 170might not be implemented by the system. Both signals are defined to 171be greater or equal to signal 32 and cannot be manipulated using legacy 172masking functions. 173.Pp 174If a program overrides the default action for a checkpoint signal the 175system will not undertake any action of its own. The program may issue 176the checkpoint command from the signal handler itself or simply set a 177reminder for later action. It is usually safest to set a reminder and 178do the actual checkpointing from your main loop. 179.Sh EXAMPLE 180.Bd -literal -offset indent -compact 181 182/* 183 * Demonstrate checkpointing. Use control-E to checkpoint 184 * the program and 'checkpt -r x.ckpt' to resume it. 185 */ 186#include <sys/types.h> 187#include <sys/signal.h> 188#include <sys/checkpoint.h> 189#include <stdio.h> 190#include <unistd.h> 191#include <fcntl.h> 192#include <errno.h> 193 194void docheckpoint(void); 195 196int wantckpt; 197 198void 199dockpt(int sig) 200{ 201 wantckpt = 1; 202} 203 204int 205main(int argc, char** argv) 206{ 207 int i = 0; 208 209 signal(SIGCKPT, dockpt); 210 211 for (;;) { 212 printf("iteration: %d\en", i); 213 ++i; 214 sleep(1); 215 if (wantckpt) { 216 wantckpt = 0; 217 printf("Checkpoint requested\en"); 218 docheckpoint(); 219 } 220 } 221 return(0); 222} 223 224void 225docheckpoint(void) 226{ 227 int ret; 228 int fd; 229 230 fd = open("x.ckpt", O_RDWR|O_CREAT|O_TRUNC, 0666); 231 if (fd < 0) { 232 printf("unable to create checkpoint file: %s\en", 233 strerror(errno)); 234 return; 235 } 236 237 ret = sys_checkpoint(CKPT_FREEZE, fd, -1, -1); 238 if (ret < 0) { 239 printf("unable to checkpoint: %s\en", 240 strerror(errno)); 241 } else if (ret == 0) { 242 printf("checkpoint successful, continuing\en"); 243 } else if (ret == 1) { 244 printf("resuming from checkpoint.\en"); 245 } else { 246 printf("unknown return value %d from sys_checkpoint\en", ret); 247 exit(1); 248 } 249 /* note that the file descriptor is still valid on a resume */ 250 close(fd); 251} 252.Ed 253.Sh SEE ALSO 254.Xr checkpt 1 , 255.Xr signal 3 256.Sh HISTORY 257The 258.Fn sys_checkpoint 259function call 260appeared in 261DragonFly 1.1 . 262