launchd Reference

Kip Landergren

(Updated: )

Contents

Files
~/Library/LaunchAgents Per-user agents provided by the user.
/Library/LaunchAgents Per-user agents provided by the administrator.
/Library/LaunchDaemons System-wide daemons provided by the administrator.
/System/Library/LaunchAgents Per-user agents provided by Apple.
/System/Library/LaunchDaemons System-wide daemons provided by Apple.

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:
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 ??

And alternatively:
launchctl unload ~/Library/LaunchAgents/local.example.plist ?? unloads the agent from launchd and stops the program associated with the agent ??
launchctl load ~/Library/LaunchAgents/local.example.plist ?? loads the agent into launchd and starts the program associated with the agent ??

Figuring Out What Went Wrong

launchctl list | grep <identifer>

Output:

launchctl error <error number>

Gotchas

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.

launchd Terminology

disable
?? marks the agent as disabled in launchd's configuration, preventing it from running even if its conditions are met; stops the agent if it is currently running ??
enable
?? marks the agent as enabled in launchd's configuration, allowing it to run when triggered by its defined conditions (e.g., KeepAlive, RunAtLoad); does not start the agent immediately ??
load
?? loads the .plist into launchd and starts managing the agent ??
start
?? manually starts the program defined by the agent without reloading the .plist ??
stop
?? manually stops the running program defined by the agent, but if KeepAlive is true, the process restarts immediately (use unload if you want to fully stop and disable restarts) ??
unload
?? unloads the .plist from launchd, stopping the program and removing it from launchd's control ??

Resources