* New upstream maintainer and location:
[debian/cpulimit.git] / debian / cpulimit.1
1 .TH CPULIMIT "1" "December 2009" "cpulimit" "User commands"
2 .SH NAME
3 cpulimit -- limits the CPU usage of a process
4 .SH SYNOPSIS
5 .B cpulimit
6 \fITARGET \fR[\fIOPTIONS\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\-l\fR, \fB\-\-limit\fR=\fIN\fR
23 percentage of CPU allowed from 0 to 100 (mandatory)
24 .TP
25 \fB\-v\fR, \fB\-\-verbose\fR
26 show control statistics
27 .TP
28 \fB\-z\fR, \fB\-\-lazy\fR
29 exit if there is no suitable target process, or if it dies
30 .TP
31 \fB\-h\fR, \fB\-\-help\fR
32 display this help and exit
33 .SH EXAMPLES
34 Assuming you have started \fB`foo \-\-bar`\fR and you find out with \fItop\fR(1) or
35 \fIps\fR(1) that this process uses all your CPU time you can either
36 .TP
37 \[sh] \fBcpulimit \-e foo \-l 50\fR
38 limits the CPU usage of the process by acting on the executable program file
39 (note: the argument "\-\-bar" is omitted)
40 .TP
41 \[sh] \fBcpulimit \-p 1234 \-l 50\fR
42 limits the CPU usage of the process by acting on its PID, as shown by
43 \fIps\fR(1)
44 .TP
45 \[sh] \fBcpulimit \-P /usr/bin/foo \-l 50\fR
46 same as \fI\-e\fR but uses the absolute path name
47 .SH NOTES
48 .IP \(bu 4
49 cpulimit always sends the SIGSTOP and SIGCONT signals to a process, 
50 both to verify
51 that it can control it and 
52 to limit the average amount of CPU it consumes.  This can result in
53 misleading (annoying) job control messages that indicate that the job 
54 has been stopped (when actually it was, but immediately restarted).  
55 This can also cause issues with interactive shells that detect or otherwise
56 depend on SIGSTOP/SIGCONT.   For example,
57 you may place a job in the foreground, only to see it immediately stopped
58 and restarted in the background.  (See also <http://bugs.debian.org/558763>.)
59 .IP \(bu 4
60 When invoked with the \fI\-e\fR or \fI\-P\fR options, cpulimit looks for 
61 any process under /proc with a name that matches the process name argument 
62 given.  Furthermore, it uses the first instance of the process found.  
63 To control a specific instance of a process, use the \fI\-p\fR option 
64 and provide a PID.
65 .IP \(bu 4
66 The current version of cpulimit assumes the kernel HZ value 100.
67
68 .SH AUTHOR
69 This manpage was written for the Debian project by gregor herrmann 
70 <gregoa@debian.org> but may be used by others.