Imported Upstream version 2.2
[debian/cpulimit.git] / README
1 README for LimitCPU
2 ==========================
3
4 LimitCPU is a program to throttle the CPU cycles used by other applications.
5 LimitCPU will monitor a process and make sure its CPU usage stays at or
6 below a given percentage. This can be used to make sure your system
7 has plenty of CPU cycles available for other tasks. It can also be used
8 to keep laptops cool in the face of CPU-hungry processes and for limiting
9 virtual machines.
10
11 LimitCPU is the direct child of CPUlimit, a creation of Angelo Marletta,
12 which can be found at http://cpulimit.sourceforge.net.
13
14
15
16
17 Copying, License and Distribution
18 ===================================
19
20 LimitCPU is licensed under the GNU General Public License (version 2).
21 A copy of the license should be included with this program in a
22 file named LICENSE.
23
24 Copyright 2005, Angelo Marletta <marlonx80@hotmail.com>
25 Copyright 2011-2014, Jesse Smith <jessefrgsmith@yahoo.ca>
26
27
28
29
30
31 Where to get LimitCPU
32 ==========================
33
34 The LimitCPU program can be aquired from http://limitcpu.sourceforge.net
35
36
37
38
39 How to compile and install
40 ===========================
41
42 Once you have downloaded a copy of LimitCPU building should be fairly
43 straight forward. First we unpack the source code
44
45 tar zxf cpulimit-2.2.tar.gz
46
47 Then we run the makefile.
48
49 cd cpulimit-2.2
50 make
51
52 This should produce the executable file "cpulimit". If you would like
53 to install the program to make it available system-wide, run
54
55 make install
56
57
58 Later should you wish to remove the program from your system, run
59 the following command from the limitcpu directory
60
61 make deinstall
62
63
64
65 Note on compiling for non-Linux operating systems:
66 LimitCPU can be compiled on FreeBSD and OS X (though at this time
67 LimitCPU has not been tested and may not work properly on OS X).
68 To compile LimitCPU on these platforms, instead of running "make"
69 to build the executable, instead run either
70
71 make freebsd
72 or
73 make osx
74
75 in order to build on FreeBSD or OS X respectively.
76
77
78
79
80
81 Common usage
82 ==========================
83
84 The LimitCPU program is generally used to throttle the CPU usage of
85 one process. This can be done with the following command where
86 12345 is the process ID number of a running program and 25 is the
87 maximum percentage of the CPU we are willing to give that program
88
89 cpulimit -p 12345 -l 25
90
91 The above example will cause LimitCPU to keep an eye on the process
92 with ID number 12345 until the program exits. Should we wish to
93 run LimitCPU in the background we can use
94
95 cpulimit -p 12345 -l 25 -b
96
97 We can also limit running processes based on their name instead of
98 their process ID, as in this example:
99
100 cpulimit --exe /usr/bin/bigexe --limit 50
101
102 The above example will keep an eye on "bigexe" and, if the application
103 quits and another program called "bigexe" is run, LimitCPU will
104 monitor the new process too. Should we wish to only track the first
105 program and then exit, we can use 
106
107 cpulimit --exe /usr/bin/bigexe --limit 50 -z
108
109 The "-z" flag tells LimitCPU to stop running once its target is
110 no longer running itself.
111
112 The following example is useful for scripts where we want
113 to launch a program and then immediately throttle it
114 without knowing its process ID. The "$!" symbol refers to
115 the last program run and the -b flag tells cpulimit to
116 run in the background, returning control to the shell.
117
118 /usr/bin/someapp &
119 cpulimit -p $! -l 25 -b
120
121
122 Note: As of version 1.7 LimitCPU will attempt to guess the
123 number of CPUs available on the machine and limit usage
124 accordingly. For example, machines with dual-cores will
125 be able to run processes with 1-200% limits. In case the
126 automatic detection does not work, users can over-ride the
127 number of CPUs LimitCPU thinks are available using the
128 -c command line flag. For example
129
130 cpulimit -c 2 -p 12345 -l 150
131
132
133 Commands can be launched by LimitCPU by appending the command
134 to the end of of LimitCPU's argument list. For example, the
135 following command will launch Firefox and limit it to 10% CPU
136 usage:
137
138 cpulimit -l 10 firefox
139
140 Sometimes we wish to launch other programs and pass them parameters.
141 To avoid confusing cpulimit as to which parameters are for it and
142 which ones are for the child process, we can use the -- flag. For
143 example, the following command launches Firefox in Private Browsing
144 mode. To make sure the "-p" in Firefox's "-private" option does not
145 confuse cpulimit, we use the -- flag.
146
147 cpulimit -l 25 -- firefox -private
148
149 In some special cases it may be desirable to kill a program
150 instead of simple throttling its CPU usage. In these cases
151 the -k flag can be used. For example, if we want to run a
152 program called "yellow" and kill it when it goes over 50%
153 CPU usage run the following:
154
155 cpulimit -l 50 -k yellow
156
157 The -k flag will terminate a process going over its limit,
158 but what if we want to bring back the killed process to
159 let it run again? For that purpose we have the -r flag. The
160 -r flag causes a killed process to be restored.
161
162 cpulimit -l 50 -k -r yellow
163
164 The restore flag (-r) only works when the process to launch
165 has been launched by cpulimit. For this reason it is necessary
166 to specify the target program at the end of the command line
167 as shown above.
168
169 LimitCPU, by default, will tell a watched process to continue
170 running when LimitCPU terminates. This is accomplished by
171 sending the watched process the SIGCONT signal just before
172 LimitCPU exits. The user can specify an alternative signal to
173 send the watched process when LimitCPU terminates. This is
174 accomplished using the -s or --signal command line flag. Here
175 is an example of terminating a watched process
176
177 cpulimit -l 25 -p 1234 -s SIGTERM
178
179 And here we accomplish the same thing using a numeric value
180 instead of the written form of the signal.
181
182 cpulimit -l 25 -p 1234 --signal=15
183
184
185
186
187 Accessing the latest code
188 ============================
189
190 For developers who would like to test or modify the latest
191 LimitCPU code, the code is available in a Subversion (svn)
192 repository. The code can be checked out using the command
193
194 svn checkout svn://svn.code.sf.net/p/limitcpu/code/ limitcpu-code
195
196
197
198
199 Bugs and Feedback
200 =============================
201
202 Should you have comments, questions, or bugs to report, please send
203 an e-mail to jessefrgsmith@yahoo.ca with the word "LimitCPU" in the
204 subject line.
205