How do I set a task to run every so often?

Just use launchd. It is a very powerful launcher system and meanwhile it is the standard launcher system for Mac OS X (current OS X version wouldn’t even boot without it). For those who are not familiar with launchd (or with OS X in general), it is like a crossbreed between init, cron, at, SysVinit (init.d), inetd, upstart and systemd. Borrowing concepts of all these projects, yet also offering things you may not find elsewhere.

Every service/task is a file. The location of the file depends on the questions: “When is this service supposed to run?” and “Which privileges will the service require?”

System tasks go to

/Library/LaunchDaemons/

if they shall run no matter if any user is logged in to the system or not. They will be started with “root” privileges.

If they shall only run if any user is logged in, they go to

/Library/LaunchAgents/

and will be executed with the privileges of the user that just logged in.

If they shall run only if you are logged in, they go to

~/Library/LaunchAgents/

where ~ is your HOME directory. These task will run with your privileges, just as if you had started them yourself by command line or by double clicking a file in Finder.

Note that there also exists /System/Library/LaunchDaemons and /System/Library/LaunchAgents, but as usual, everything under /System is managed by OS X. You shall not place any files there, you shall not change any files there, unless you really know what you are doing. Messing around in the Systems folder can make your system unusable (get it into a state where it will even refuse to boot up again). These are the directories where Apple places the launchd tasks that get your system up and running during boot, automatically start services as required, perform system maintenance tasks, and so on.

Every launchd task is a file in PLIST format. It should have reverse domain name notation. E.g. you can name your task

com.example.my-fancy-task.plist

This plist can have various options and settings. Writing one per hand is not for beginners, so you may want to get a tool like LaunchControl (commercial, $18) or Lingon (commercial, $14.99) to create your tasks.

Just as an example, it could look like this

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.my-fancy-task</string>
    <key>OnDemand</key>
    <true/>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/sh</string>
        <string>/usr/local/bin/my-script.sh</string>
    </array>
    <key>StartInterval</key>
    <integer>1800</integer>
</dict>
</plist>

This agent will run the shell script /usr/local/bin/my-script.sh every 1800 seconds (every 30 minutes). You can also have task run on certain dates/times (basically launchd can do everything cron can do) or you can even disable “OnDemand” causing launchd to keep the process permanently running (if it quits or crashes, launchd will immediately restart it). You can even limit how much resources a process may use.

Update: Even though OnDemand is still supported, it is deprecated. The new setting is named KeepAlive, which makes much more sense. It can have a boolean value, in which case it is the exact opposite of OnDemand (setting it to false behaves as if OnDemand is true and the other way round). The great new feature is, that it can also have a dictionary value instead of a boolean one. If it has a dictionary value, you have a couple of extra options that give you more fine grain control under which circumstances the task shall be kept alive. E.g. it is only kept alive as long as the program terminated with an exit code of zero, only as long as a certain file/directory on disk exists, only if another task is also alive, or only if the network is currently up.

Also you can manually enable/disable tasks via command line:

launchctl <command> <parameter>

command can be load or unload, to load a plist or unload it again, in which case parameter is the path to the file. Or command can be start or stop, to just start or stop such a task, in which case parameter is the label (com.example.my-fancy-task). Other commands and options exist as well.

Update: Even though load, unload, start, and stop do still work, they are legacy now. The new commands are bootstrap, bootout, enable, and disable with slightly different syntax and options. One big difference is that disable is persistent, so once a service has been disabled, it will stay disabled, even across reboots until you enable it again. Also you can use kickstart to run a task immediately, regardless how it has been configured to run.

The main difference between the new and the old commands is that they separate tasks by “domain”. The system has domain and so has every user. So equally labeled tasks may exist in different domains and launctl can still distinguish them. Even different login and different UI sessions of the same user have their own domain (e.g. the same user may once be logged locally and once remote via SSH and different tasks may run for either session) and so does every single running processes. Thus instead of com.example.my-fancy-task, you now would use system/com.example.my-fancy-task or user/501/com.example.my-fancy-task to identify a task, with 501 being the user ID of a specific user.

See documentation of the plist format and of the launchctl command line tool.

Leave a Comment