debian man page for cpulimit

CPULIMIT(1)							   User commands						       CPULIMIT(1)

NAME
       cpulimit -- limits the CPU usage of a process

SYNOPSIS
       cpulimit [TARGET] [OPTIONS...]

DESCRIPTION
       TARGET must be exactly one of these:

       -p, --pid=N
	      pid of the process

       -e, --exe=FILE
	      name of the executable program file

       -P, --path=PATH
	      absolute path name of the executable program file

       OPTIONS

       -b, --background
	      run cpulimit in the background, freeing up the terminal

       -c, --cpu
	      specify the number of CPU cores available. Usually this is detected for us.

       -l, --limit=N
	      percentage of CPU allowed from 1 up. Usually 1 - 100, but can be higher on multi-core CPUs. (mandatory)

       -v, --verbose
	      show control statistics

       -z, --lazy
	      exit if there is no suitable target process, or if it dies

       -h, --help
	      display this help and exit

EXAMPLES
       Assuming you have started `foo --bar` and you find out with top(1) or ps(1) that this process uses all your CPU time you can either

       # cpulimit -e foo -l 50
	      limits the CPU usage of the process by acting on the executable program file (note: the argument "--bar" is omitted)

       # cpulimit -p 1234 -l 50
	      limits the CPU usage of the process by acting on its PID, as shown by ps(1)

       # cpulimit -P /usr/bin/foo -l 50
	      same as -e but uses the absolute path name

       # /usr/bin/someapp

       # cpulimit -p $! -l 25 -b
	      Useful for scripts where you want to throttle the last command run.

       # cpulimit -l 20 firefox
	      Launch Firefox web browser and limit its CPU usage to 20%

       # cpulimit -c 2 -p 12345 -l 25
	      The -c flag sets the number of CPU cores the program thinks are available. Usually this is detected for us, but can be over-ridden.

NOTES
       o   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 back-
	   ground.  (See also <http://bugs.debian.org/558763>.)

       o   When  invoked  with the -e or -P 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	-p  option
	   and provide a PID.

       o   The current version of cpulimit assumes the kernel HZ value 100.

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

cpulimit							     June 2012							       CPULIMIT(1)