From 8739aab49af732719b57cc64de3fc48c332c8880 Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Sat, 30 Jun 2007 19:20:48 +0000 Subject: [PATCH] Clean up a bit. --- lib/libc/sys/sys_checkpoint.2 | 81 +++++++++++++++++++++++++------------------ usr.bin/checkpt/checkpt.1 | 30 +++++++++------- 2 files changed, 64 insertions(+), 47 deletions(-) diff --git a/lib/libc/sys/sys_checkpoint.2 b/lib/libc/sys/sys_checkpoint.2 index 03134ef127..f7d654fd5e 100644 --- a/lib/libc/sys/sys_checkpoint.2 +++ b/lib/libc/sys/sys_checkpoint.2 @@ -30,9 +30,9 @@ .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $DragonFly: src/lib/libc/sys/sys_checkpoint.2,v 1.7 2007/06/30 19:03:52 swildner Exp $ +.\" $DragonFly: src/lib/libc/sys/sys_checkpoint.2,v 1.8 2007/06/30 19:20:48 swildner Exp $ .\" -.Dd November 22, 2004 +.Dd June 29, 2007 .Dt SYS_CHECKPOINT 2 .Os .Sh NAME @@ -52,7 +52,7 @@ system call executes a checkpoint function as specified by .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 will generate a checkpoint file 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 resumed program if 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 files mapped by the program 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 main loop. .Sh HISTORY The .Fn sys_checkpoint -function call -appeared in +function call appeared in .Dx 1.1 . diff --git a/usr.bin/checkpt/checkpt.1 b/usr.bin/checkpt/checkpt.1 index 2e3be6be52..2e580f9dd3 100644 --- a/usr.bin/checkpt/checkpt.1 +++ b/usr.bin/checkpt/checkpt.1 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $DragonFly: src/usr.bin/checkpt/checkpt.1,v 1.4 2005/08/01 03:49:17 swildner Exp $ +.\" $DragonFly: src/usr.bin/checkpt/checkpt.1,v 1.5 2007/06/30 19:20:48 swildner Exp $ .\" .Dd October 19, 2003 .Dt CHECKPT 1 @@ -37,30 +37,34 @@ The .Nm utility will resume the checkpointed program from the specified checkpoint -file. Programs can be checkpointed using ^E. +file. +Programs can be checkpointed using ^E. .Pp By default, only members of the wheel group can checkpoint a program. -The group can be changed with the sysctl kern.ckptgroup. -The checkpoint file template can be changed with the sysctl kern.ckptfile. +The group can be changed with the sysctl +.Va kern.ckptgroup . +The checkpoint file template can be changed with the sysctl +.Va kern.ckptfile . .Pp -The checkpointing utility is fairly primitive. Only programs -operating on normal files can be properly restored. Programs which operate -on devices, sockets, or pipes (including piped commands) cannot be completely. +The checkpointing utility is fairly primitive. +Only programs operating on normal files can be properly restored. +Programs which operate on devices, sockets, or pipes (including piped +commands) cannot be completely. File descriptors 0, 1, and 2, are not saved and the restored program will inherit the descriptors from -.Nm +.Nm . .Pp Programs can actively support checkpointing by catching the .Dv SIGCKPT signal, cleaning up, and manually calling the .Fn sys_checkpoint -system call. The program can then choose whether to continue running or -exit. The resumed program will get a (typically) positive return value -from +system call. +The program can then choose whether to continue running or exit. +The resumed program will get a (typically) positive return value from .Fn sys_checkpoint which it can use to determine whether it just made the system call or whether -it is being resumed from the system call. The program can then reconstruct -non-checkpointed elements and resume. +it is being resumed from the system call. +The program can then reconstruct non-checkpointed elements and resume. .Sh SEE ALSO .Xr stty 1 , .Xr sys_checkpoint 2 -- 2.11.4.GIT