launchd Reference

Kip Landergren

(Updated: )

Contents

Domains, Services, and Identifiers

For gui/501/com.apple.example:
gui / GUI domain (?? capitalization doesn’t matter ??)
501 the user id (UID)
gui/501/ domain-target
com.apple.example service-name / identifier
gui/501/com.apple.example service-target

Useful Keys

Explanations taken from launchd.plist(5) man page.
WorkingDirectory string This optional key is used to specify a directory to chdir(2) to before running the job.
EnvironmentVariables dictionary of strings This optional key is used to specify additional environmental variables to be set before running the job. Each key in the dictionary is the name of an environment variable, with the corresponding value being a string representing the desired value. NOTE: Values other than strings will be ignored.
Program string This key maps to the first argument of execv(3) and indicates the absolute path to the executable for the job. If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead. This key is required in the absence of the ProgramArguments and BundleProgram keys.
ProgramArguments array of strings This key maps to the second argument of execvp(3) and specifies the argument vector to be passed to the job when a process is spawned. This key is required in the absence of the Program key. IMPORTANT: Many people are confused by this key. Please read execvp(3) very carefully!
StartInterval integer refer to man page
StartCalendarInterval dictionary of integers or array of dictionaries of integers refer to man page
StandardOutPath string refer to man page
StandardErrorPath string refer to man page

Common Operations

Creating an Agent

Managing a LaunchAgent

For ~/Library/LaunchAgents/local.example.plist:
create the .plist file
launchctl bootstrap gui/501 ~/Library/LaunchAgents/local.example.plist ?? loads and enables the agent ??
launchctl kickstart gui/501/local.example ?? run the service immediately ??
launchctl bootout gui/501/local.example ?? stops and removes the service immediately ??

Frequently Asked Questions (FAQs)

What exactly is an agent? How is it different than a daemon?

From Technical Note TN2083: Daemons and Agents:

Daemons and agents, collectively known as background programs, are programs that operate without any graphical user interface. As a developer, you can use background programs to perform actions without user interaction, and also to manage a shared state between multiple other programs.

...

A daemon is a program that runs in the background as part of the overall system (that is, it is not tied to a particular user). A daemon cannot display any GUI; more specifically, it is not allowed to connect to the window server. A web server is the perfect example of a daemon.

...

An agent is a process that runs in the background on behalf of a particular user. Agents are useful because they can do things that daemons can’t, like reliably access the user’s home directory or connect to the window server.

Resources