Remove trailing whitespace from debian/*.
[debian/cpulimit.git] / cpulimit.1
1 .TH CPULIMIT "1" "June 2012" "cpulimit" "User commands"
2 .SH NAME
3 cpulimit -- limits the CPU usage of a process
4 .SH SYNOPSIS
5 .B cpulimit
6 \fI[TARGET\fR] \fR[\fIOPTIONS\fR...] \fR[ -- \fIPROGRAM\fR]
7 .SH DESCRIPTION
8 .P
9 \fITARGET \fRmust be exactly one of these:
10 .TP
11 \fB\-p\fR, \fB\-\-pid\fR=\fIN\fR
12 pid of the process
13 .TP
14 \fB\-e\fR, \fB\-\-exe\fR=\fIFILE\fR
15 name of the executable program file
16 .TP
17 \fB\-P\fR, \fB\-\-path\fR=\fIPATH\fR
18 absolute path name of the executable program file
19 .P
20 \fIOPTIONS\fR
21 .TP
22 \fB\-b\fR, \fB\-\-background\fR
23 run cpulimit in the background, freeing up the terminal
24 .TP
25 \fB\-f\fR, \fB\-\-foreground\fR
26 run cpulimit in foreground while waiting for launched process to finish
27 .TP
28 \fB\-c\fR, \fB\-\-cpu\fR
29 specify the number of CPU cores available. Usually this is detected for us.
30 .TP
31 \fB\-l\fR, \fB\-\-limit\fR=\fIN\fR
32 percentage of CPU allowed from 1 up. Usually 1 - 100, but can be higher on multi-core CPUs. (mandatory)
33 .TP
34 \fB\-q\fR, \fB\-\-quiet\fR
35 Runs in quiet mode, avoids writing update messages to console.
36 .TP
37 \fB\-k\fR, \fB\-\-kill\fR
38 kill target process instead of throttling its CPU usage
39 .TP
40 \fB\-m\fR, \fB\-\-monitor\-forks\fR
41 watch and throttle child processes of the target process
42 Warning: It is usually a bad idea to use this flag on a shell script. The commands
43 in the script will each spawn a process which will, in turn, spawn more copies of
44 this program to throttle them, bogging down the system.
45 .TP
46 \fB\-r\fR, \fB\-\-restore\fR
47 restore a process killed using the \-k flag.
48 .TP
49 \fB\-s\fR, \fB\-\-signal\fR
50 send an alternative signal to the watched process when we exit. Default is SIGCONT.
51 .TP
52 \fB\-v\fR, \fB\-\-verbose\fR
53 show control statistics
54 .TP
55 \fB\-z\fR, \fB\-\-lazy\fR
56 exit if there is no suitable target process, or if it dies
57 .TP
58 \fB\--\fR 
59 This is the final CPUlimit option. All following 
60 options are for another program we will launch.
61 .TP
62 \fB\-h\fR, \fB\-\-help\fR
63 display this help and exit
64 .SH EXAMPLES
65 Assuming you have started \fB`foo \-\-bar`\fR and you find out with \fItop\fR(1) or
66 \fIps\fR(1) that this process uses all your CPU time you can either
67 .TP
68 \[sh] \fBcpulimit \-e foo \-l 50\fR
69 limits the CPU usage of the process by acting on the executable program file
70 (note: the argument "\-\-bar" is omitted)
71 .TP
72 \[sh] \fBcpulimit \-p 1234 \-l 50\fR
73 limits the CPU usage of the process by acting on its PID, as shown by
74 \fIps\fR(1)
75 .TP
76 \[sh] \fBcpulimit \-P /usr/bin/foo \-l 50\fR
77 same as \fI\-e\fR but uses the absolute path name
78 .TP
79 \[sh] \fB/usr/bin/someapp \&
80 .TP
81 \[sh] \fBcpulimit \-p $! \-l 25 \-b\fR
82 Useful for scripts where you want to throttle
83 the last command run.
84 .TP
85 \[sh] \fBcpulimit \-l 20 firefox\fR
86 Launch Firefox web browser and limit its CPU usage to
87 20%
88 .TP
89 \[sh] \fBcpulimit \-l 25 \-\- firefox \-private\fR
90 Launch Firefox web browser in private mode and limit its CPU usage to
91 25%
92 .TP
93 \[sh] \fBcpulimit \-c 2 \-p 12345 \-l 25\fR
94 The \fB\-c\fR flag sets the number of CPU cores the
95 program thinks are available. Usually this is detected
96 for us, but can be over-ridden.
97 .TP
98 \[sh] \fBcpulimit \-l 20 \-k firefox\fr
99 Launch the Firefox program and kill it if the process goes
100 over 20% CPU usage.
101 .TP
102 \[sh] \fBcpulimit \-l 20 \-p 1234 \-s SIGTERM
103 Throttle process 1234 at 20% CPU usage. If cpulimit is forced to exit, 
104 it sends the watched process the SIGTERM signal.
105 .SH NOTES
106 .IP \(bu 4
107 cpulimit always sends the SIGSTOP and SIGCONT signals to a process, 
108 both to verify
109 that it can control it and 
110 to limit the average amount of CPU it consumes.  This can result in
111 misleading (annoying) job control messages that indicate that the job 
112 has been stopped (when actually it was, but immediately restarted).  
113 This can also cause issues with interactive shells that detect or otherwise
114 depend on SIGSTOP/SIGCONT.   For example,
115 you may place a job in the foreground, only to see it immediately stopped
116 and restarted in the background.  (See also <http://bugs.debian.org/558763>.)
117 .IP \(bu 4
118 When invoked with the \fI\-e\fR or \fI\-P\fR options, cpulimit looks for 
119 any process under /proc with a name that matches the process name argument 
120 given.  Furthermore, it uses the first instance of the process found.  
121 To control a specific instance of a process, use the \fI\-p\fR option 
122 and provide a PID.
123 .IP \(bu 4
124 The current version of cpulimit assumes the kernel HZ value 100.
125
126 .SH AUTHOR
127 This manpage was written for the Debian project by gregor herrmann 
128 <gregoa@debian.org> but may be used by others.