File: cpulimit.1

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

.SH AUTHOR
This manpage was written for the Debian project by gregor herrmann 
<gregoa@debian.org> but may be used by others.