launchctl Tutorial

Posted: December 5th, 2010 | Author: | Filed under: launchctl, Mac | Tags: , , , , , , , , , , , , , , , | No Comments »

launchctl allows users to start / stop applications that is typically processed via launchd. (MacOS’s equivalent of cron).

launchctl command configurations are stored as XML formatted .plist files located in directories /System/Library/LaunchAgents or /System/Library/LaunchDaemons for system wide start items, for user specific items the plist files are stored in ~/Library/LaunchAgents or ~/Library/LaunchDaemons directories.

Agents or Daemons?
An agent is a program that requires access to specific users’ information. A daemon is a program that runs in the background and requires generally no input from any user.

For more a comparison between Agents and Daemons refer to this Apple technote.

What is in a .plist?
A .plist file must contain at the very least the keys Label, ProgramArguments array and a key to tell launchd how the application is run eg KeepAlive, RunAtLoad for one time operations. or StartonMount, StartInterval, StartCalendarInterval for repeating occurrences.

A complete dictionary of all the property keys can be found here. A few things it can do is to monitor modified paths (via the key WatchPath), HardResourceLimits etc.

Here is an example for com.companyname.agentorapplicationname.plist, which runs the application full/path/to/binary every 60 seconds:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
< ?xml version="1.0" encoding="UTF-8"?>
< !DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" \
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">
 <dict>
  <key>Label</key>
  <string>com.companyname.agentorapplicationname</string>
  <key>ProgramArguments</key>
   <array>
    <string>/full/path/to/binary</string>
    <string>-firstargument</string>
    <string>valueoffirstargument</string>
    <string>-secondargument</string>
    <string>valueofsecondargument</string>
   </array>
  <key>StartInterval 60</key>
  <true />
 </dict>
</plist>


launctl operations

Command Description
launchctl list Lists the PID, status and name of loaded processes
launchctl list com.com.exampleco.eg Output the runtime information (eg. PATH) of com.exampleco.eg
launchctl start com.exampleco.eg Starts com.exampleco.eg
launchctl stop com.exampleco.eg Stop com.exampleco.eg
launchctl loads -w /path/example.plist Loads a process by its plist filename
launchctl unloads /path/example.plist Stop and unload a process by its plist filename
submit -l labelname -p /path/eg/binary -o /path2/stdout -e /path2/sterr Manually run binary under the label labelname with to specified stdout and sterr devices/files

Leave a Reply

You must be logged in to post a comment.