releasing version 1.5-1
[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, 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-1.5.tar.gz
46
47 Then we run the makefile.
48
49 cd cpulimit-1.5
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 Common usage
66 ==========================
67
68 The LimitCPU program is generally used to throttle the CPU usage of
69 one process. This can be done with the following command where
70 12345 is the process ID number of a running program and 25 is the
71 maximum percentage of the CPU we are willing to give that program
72
73 cpulimit -p 12345 -l 25
74
75 The above example will cause LimitCPU to keep an eye on the process
76 with ID number 12345 until the program exits. Should we wish to
77 run LimitCPU in the background we can use
78
79 cpulimit -p 12345 -l 25 -b
80
81 We can also limit running processes based on their name instead of
82 their process ID, as in this example:
83
84 cpulimit --exe /usr/bin/bigexe --limit 50
85
86 The above example will keep an eye on "bigexe" and, if the application
87 quits and another program called "bigexe" is run, LimitCPU will
88 monitor the new process too. Should we wish to only track the first
89 program and then exit, we can use 
90
91 cpulimit --exec /usr/bin/bigexe --limit 50 -z
92
93 The "-z" flag tells LimitCPU to stop running once its target is
94 no longer running itself.
95
96 The following example is useful for scripts where we want
97 to launch a program and then immediately throttle it
98 without knowing its process ID. The "$!" symbol refers to
99 the last program run and the -b flag tells cpulimit to
100 run in the background, returning control to the shell.
101
102 /usr/bin/someapp &
103 cpulimit -p $! -l 25 -b
104
105
106
107 Bugs and Feedback
108 =============================
109
110 Should you have comments, questions, or bugs to report, please send
111 an e-mail to jessefrgsmith@yahoo.ca with the word "LimitCPU" in the
112 subject line.
113