--- src/lib/libc/sys/sys_checkpoint.2 2007/06/30 19:03:52 1.7 +++ src/lib/libc/sys/sys_checkpoint.2 2007/06/30 19:20:48 1.8 @@ -32,7 +32,7 @@ .\" .\" $DragonFly$ .\" -.Dd November 22, 2004 +.Dd June 29, 2007 .Dt SYS_CHECKPOINT 2 .Os .Sh NAME @@ -52,7 +52,7 @@ system call executes a checkpoint functi .Fa type . Supported types are as follows: .Pp -.Bl -tag -width CKPT_FREEZE -offset indent +.Bl -tag -width ".Dv CKPT_FREEZE" -offset indent .It Dv CKPT_FREEZE Generate a checkpoint file. Currently @@ -71,12 +71,13 @@ are both specified as -1, the system wil using the system checkpoint template. .Pp This function returns 0 on success, -1 on error, and typically 1 -on resume. The value returned on resume is controlled by the +on resume. +The value returned on resume is controlled by the .Fa retval argument passed to .Fn sys_checkpoint -when resuming a checkpoint file. A user program which installs its -own +when resuming a checkpoint file. +A user program which installs its own .Dv SIGCKPT signal handler and calls .Fn sys_checkpoint @@ -96,17 +97,18 @@ specifies the value returned to the resu was called directly. .Pp The checkpointed program will replace the current program, similar to -an exec call. +an +.Xr exec 3 +call. .El .Sh RETURN VALUES -Upon successful completion, the value 0 is typically returned. A checkpoint -being resumed typically returns a positive value; otherwise the value -1 -is returned and the global variable +Upon successful completion, the value 0 is typically returned. +A checkpoint being resumed typically returns a positive value; +otherwise the value -1 is returned and the global variable .Va errno is set to indicate the error. .Sh EXAMPLE .Bd -literal -offset indent -compact - /* * Demonstrate checkpointing. Use control-E to checkpoint * the program and 'checkpt -r x.ckpt' to resume it. @@ -183,7 +185,8 @@ docheckpoint(void) .It Bq Er EBADF The given .Fa fd -is not a valid regular file, socket descriptor, or pipe. Note that not +is not a valid regular file, socket descriptor, or pipe. +Note that not all systems necessarily support checkpointing to sockets and pipes. .It Bq Er EPERM The caller does not have permission to issue the checkpoint command. @@ -208,8 +211,8 @@ is restored and some of the underlying f have changed. .Pp The system checkpointing code is not able to retain the process pid, process -group, user/group creds, or descriptors 0, 1, and 2. These will be inherited -from whomever restores the checkpoint. +group, user/group creds, or descriptors 0, 1, and 2. +These will be inherited from whomever restores the checkpoint. .Pp When a checkpointed program is restored modified private mappings will be mapped from the checkpoint file itself, but major portions of the @@ -220,50 +223,61 @@ the original is likely being replaced. The caller must not truncate the existing checkpoint file when creating a new one or specify the existing file's file descriptor as the new one as this will destroy the data that the checkpoint operation needs -to copy to the new file. It is best to checkpoint to a new file and then -rename-over the old, or to remove() the old file before creating the new +to copy to the new file. +It is best to checkpoint to a new file and then rename-over the old, or to +.Xr remove 3 +the old file before creating the new one so it remains valid as long as the program continues to run. .Pp -Threaded programs cannot currently be checkpointed. The program must be +Threaded programs cannot currently be checkpointed. +The program must be reduced to a single thread before it can be safely checkpointed. .Pp -MAP_VPAGETABLE mappings cannot currently be checkpointed. A program must -restore such mappings manually on resumption. Only regular file and -anonymous memory mappings are checkpointed and restored. Device and other -special mappings are not. Only regular file descriptors are checkpointed -and restored. Devices, pipes, sockets, and other special descriptors are -not. Memory wiring states are not checkpointed or restored. madvise() -states are not checkpointed or restored. Basic mapping permissions are -checkpointed and restored. +.Dv MAP_VPAGETABLE +mappings cannot currently be checkpointed. +A program must restore such mappings manually on resumption. +Only regular file and +anonymous memory mappings are checkpointed and restored. +Device and other special mappings are not. +Only regular file descriptors are checkpointed and restored. +Devices, pipes, sockets, and other special descriptors are not. +Memory wiring states are not checkpointed or restored. +.Xr madvise 2 +states are not checkpointed or restored. +Basic mapping permissions are checkpointed and restored. .Pp .Sh SECURITY The sysctl -.Em kern.ckptgroup +.Va kern.ckptgroup controls which group can use system checkpointing. By default, only users in the .Ql wheel group are allowed to checkpoint and restore processes. To allow users in any group to have this capability (risky), set sysctl -.Em kern.ckptgroup +.Va kern.ckptgroup to -1. .Sh SIGNALS Two signals are associated with checkpointing. .Dv SIGCKPT -is delivered via the tty ckpt character, usually control-E. Its default -action is to checkpoint a program and continue running it. The +is delivered via the tty ckpt character, usually control-E. +Its default action is to checkpoint a program and continue running it. +The .Dv SIGCKPTEXIT signal can only be delivered by .Xr kill 2 . Its default action is to checkpoint a program and then exit. .Dv SIGCKPTEXIT -might not be implemented by the system. Both signals are defined to +might not be implemented by the system. +Both signals are defined to be greater or equal to signal 32 and cannot be manipulated using legacy masking functions. .Pp If a program overrides the default action for a checkpoint signal the -system will not undertake any action of its own. The program may issue +system will not undertake any action of its own. +The program may issue the checkpoint command from the signal handler itself or simply set a -reminder for later action. It is usually safest to set a reminder and +reminder for later action. +It is usually safest to set a reminder and do the actual checkpointing from your main loop. .Sh SEE ALSO .Xr checkpt 1 , @@ -271,6 +285,5 @@ do the actual checkpointing from your ma .Sh HISTORY The .Fn sys_checkpoint -function call -appeared in +function call appeared in .Dx 1.1 .