2 ==========================
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
11 LimitCPU is the direct child of CPUlimit, a creation of Angelo Marletta,
12 which can be found at http://cpulimit.sourceforge.net.
17 Copying, License and Distribution
18 ===================================
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
24 Copyright 2005, Angelo Marletta <marlonx80@hotmail.com>
25 Copyright 2011-2016, Jesse Smith <jessefrgsmith@yahoo.ca>
32 ==========================
34 The LimitCPU program can be aquired from http://limitcpu.sourceforge.net
39 How to compile and install
40 ===========================
42 Once you have downloaded a copy of LimitCPU building should be fairly
43 straight forward. First we unpack the source code
45 tar zxf cpulimit-2.6.tar.gz
47 Then we run the makefile.
52 This should produce the executable file "cpulimit". If you would like
53 to install the program to make it available system-wide, run
58 Later should you wish to remove the program from your system, run
59 the following command from the limitcpu directory
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
75 in order to build on FreeBSD or OS X respectively.
82 ==========================
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
89 cpulimit -p 12345 -l 25
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
95 cpulimit -p 12345 -l 25 -b
97 We can also limit running processes based on their name instead of
98 their process ID, as in this example:
100 cpulimit --exe /usr/bin/bigexe --limit 50
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
107 cpulimit --exe /usr/bin/bigexe --limit 50 -z
109 The "-z" flag tells LimitCPU to stop running once its target is
110 no longer running itself.
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.
119 cpulimit -p $! -l 25 -b
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
130 cpulimit -c 2 -p 12345 -l 150
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
138 cpulimit -l 10 firefox
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.
147 cpulimit -l 25 -- firefox -private
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:
155 cpulimit -l 50 -k yellow
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.
162 cpulimit -l 50 -k -r yellow
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
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
177 cpulimit -l 25 -p 1234 -s SIGTERM
179 And here we accomplish the same thing using a numeric value
180 instead of the written form of the signal.
182 cpulimit -l 25 -p 1234 --signal=15
184 LimitCPU can be used to watch not only one target process, but also
185 child processes the target spawns. This means new processs the
186 target creates will also be throttled. By default, LimitCPU
187 only watches one target process and ignores children, but monitoring
188 children can be enabled using the "-m" or "--monitor-forks" flag.
190 cpulimit -l 25 -p 1234 -m
194 Accessing the latest code
195 ============================
197 For developers who would like to test or modify the latest
198 LimitCPU code, the code is available in a Subversion (svn)
199 repository. The code can be checked out using the command
201 svn checkout svn://svn.code.sf.net/p/limitcpu/code/ limitcpu-code
207 =============================
209 Should you have comments, questions, or bugs to report, please send
210 an e-mail to jessefrgsmith@yahoo.ca with the word "LimitCPU" in the