1 .\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved.
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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
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.
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
33 .\" $DragonFly: src/lib/libc/sys/sys_checkpoint.2,v 1.5 2006/02/17 19:35:06 swildner Exp $
40 .Nd checkpoint or restore a process
47 .Fn sys_checkpoint "int type" "int fd" "pid_t pid" "int retval"
51 system call executes a checkpoint function as specified by
53 Supported types are as follows:
55 .Bl -tag -width CKPT_FREEZE -offset indent
57 Generate a checkpoint file.
60 must be -1 or the pid of the current process.
61 The checkpoint file will be written out to
65 is unused but must be specified as -1.
70 are both specified as -1, the system will generate a checkpoint file
71 using the system checkpoint template.
73 This function returns 0 on success, -1 on error, and typically 1
74 on resume. The value returned on resume is controlled by the
78 when resuming a checkpoint file. A user program which installs its
81 signal handler and calls
83 manually thus has control over both termination/continuance and
86 Restore a checkpointed program.
89 must be specified as -1, and
91 represents the checkpoint file.
94 specifies the value returned to the resumed program if
98 The checkpointed program will replace the current program, similar to
102 Upon successful completion, the value 0 is typically returned. A checkpoint
103 being resumed typically returns a positive value; otherwise the value -1
104 is returned and the global variable
106 is set to indicate the error.
108 .Bd -literal -offset indent -compact
111 * Demonstrate checkpointing. Use control-E to checkpoint
112 * the program and 'checkpt -r x.ckpt' to resume it.
114 #include <sys/types.h>
115 #include <sys/signal.h>
116 #include <sys/checkpoint.h>
122 void docheckpoint(void);
133 main(int argc, char** argv)
137 signal(SIGCKPT, dockpt);
140 printf("iteration: %d\en", i);
145 printf("Checkpoint requested\en");
158 fd = open("x.ckpt", O_RDWR|O_CREAT|O_TRUNC, 0666);
160 printf("unable to create checkpoint file: %s\en",
165 ret = sys_checkpoint(CKPT_FREEZE, fd, -1, -1);
167 printf("unable to checkpoint: %s\en",
169 } else if (ret == 0) {
170 printf("checkpoint successful, continuing\en");
171 } else if (ret == 1) {
172 printf("resuming from checkpoint.\en");
174 printf("unknown return value %d from sys_checkpoint\en", ret);
177 /* note that the file descriptor is still valid on a resume */
186 is not a valid regular file, socket descriptor, or pipe. Note that not
187 all systems necessarily support checkpointing to sockets and pipes.
189 The caller does not have permission to issue the checkpoint command.
190 Checkpointing may be restricted or disabled using sysctls.
192 An I/O error occurred while reading from the file system.
194 An invalid parameter was specified.
196 .Sh CHECKPOINT FEATURES
197 The system checkpointing code will save the process register state (including
198 floating point registers), signal state, file descriptors representing
199 regular files or directories (anything that can be converted into a file
200 handle for storage), and both shared and private memory mappings.
201 Private, writable mappings are copied to the checkpoint file while shared
202 mappings and stored by referencing the file handle and offset.
203 Note that the system checkpointing code does not retain references to
204 deleted files, so mappings and open descriptors of deleted files
206 Unpredictable operation will occur if a checkpoint-unaware program
207 is restored and some of the underlying files mapped by the program
210 The system checkpointing code is not able to retain the process pid, process
211 group, user/group creds, or descriptors 0, 1, and 2. These will be inherited
212 from whomever restores the checkpoint.
214 When a checkpointed program is restored modified private mappings will
215 be mapped from the checkpoint file itself, but major portions of the
216 original program binary will be mapped from the original program binary.
217 If the resumed program is checkpointed again the system will automatically
218 copy any mappings from the original checkpoint file to the new one, since
219 the original is likely being replaced.
220 The caller must not truncate the existing checkpoint file when creating
221 a new one or specify the existing file's file descriptor as the new
222 one as this will destroy the data that the checkpoint operation needs
223 to copy to the new file.
227 controls which group can use system checkpointing.
228 By default, only users in the
230 group are allowed to checkpoint and restore processes.
231 To allow users in any group to have this capability (risky), set sysctl
235 Two signals are associated with checkpointing.
237 is delivered via the tty ckpt character, usually control-E. Its default
238 action is to checkpoint a program and continue running it. The
240 signal can only be delivered by
242 Its default action is to checkpoint a program and then exit.
244 might not be implemented by the system. Both signals are defined to
245 be greater or equal to signal 32 and cannot be manipulated using legacy
248 If a program overrides the default action for a checkpoint signal the
249 system will not undertake any action of its own. The program may issue
250 the checkpoint command from the signal handler itself or simply set a
251 reminder for later action. It is usually safest to set a reminder and
252 do the actual checkpointing from your main loop.