Posts Tagged XPC LaunchAgent

LaunchAgents launchctl and the ServiceManagement API

I’m writing the installer for my LaunchAgent and associated bits and bobs and once again I’ve entered the Alice in Wonderland world of documentation for launchctl* and the ServiceManagement API***.

To register a LaunchAgent with launchd** you can’t use SMJobBless. SMJobBless works only with the kSMDomainSystemLaunchd domain. A LaunchAgent is by definition a member of the kSMDomainUserLaunchd domain.

The ServiceManagement function SMJobSubmit submits a job (in my case this is my LaunchAgent) with launchd. This means that launchd will manage the starting of the LaunchAgent when a request is made of a service the LaunchAgent provides. The function SMJobSubmit doesn’t however add the job plist file**** to an appropriate location, in my case (~/Library/LaunchAgents) and as a result after the user logs out, or reboots the LaunchAgent is no longer managed by launchd. Launchd can also be configured to stop the service or to run the service to a schedule. After much reading it has become clear that the ServiceManagement API is not going to be of use to me, which leaves me with using the command line tool launchctl to configure launchd to manage my LaunchAgent.

For my purposes I’m using launchd to manage the starting of the LaunchAgent, but the LaunchAgent itself decides when to exit.

If I copy my LaunchAgent’s plist file to ~/Library/LaunchAgents then after I next log in or reboot the LaunchAgent becomes a service managed by launchd. If I don’t want to have to wait until after rebooting or logging back in again then I need to run the launchctl command:

launchctl load ~/Library/LaunchAgents/

where is the job plist file specific to my LaunchAgent and apart from the extension plist has the same name as the LaunchAgent.

If I want to stop launchd managing my LaunchAgent then I need to run the launchctl command:

launchctl unload ~/Library/LaunchAgents/

But if I don’t want launchd to manage the LaunchAgent again next time I log in I need to remove the LaunchAgent’s plist file from “~/Library/LaunchAgents/”.

I’ve found apple’s documentation poor and have had trouble with getting a sure handle on what various terms mean.

The terms “job/service/LaunchAgent” I’ve used here interchangeably. The term “job” I believe apple is using to mean a generic term encompassing different types of jobs like LaunchDaemon/LaunchAgent/LoginItem/Service. In this case a job is not a single task to be performed but an executable that can perform a particular type of job. For my project the job is the LaunchAgent.

The terms “register/submit/add to list” I’ve also used interchangeably. These all relate to the daemon/agent manager launchd. Submit is used because the ServiceManagement function SMJobSubmit. I’ve used the phrase “add to list” because launchd has a list of jobs it manages. Register just seems to make most sense to me, if I register my LaunchAgent/Service etc. with launchd then launchd manages the job. If I deregister then launchd no longer manages the LaunchAgent.

* launchctl is a command line tool for configuring the operation of launchd including adding and removing Agents/Daemons/Services to the list of things that launchd manages.
** launchd is a daemon/agent manager.
*** ServiceManagement API is the programming interface for adding and removing Agents/Daemons/Services to the list of things that launchd manages.
**** job plist file. Describes to launchd the job. The service the job provides, under what circumstances to start the job and the location of the job executable to be run. For more information see the cryptic and not very helpful man page launchd.plist.


For debugging purposes, if you want to start the LaunchAgent once it is managed by launchd then you can run the following command.

launchctl start

To stop the job running.

launchctl stop

I would not recommend using the -w switch when using the launchctl subcommands load and unload. I was hoping that by specifying the -w switch when registering the LaunchAgent with launchd then the LaunchAgent would still be registered after reboot or logging out and back in again but it is not. You still need to copy the LaunchAgent’s plist file to ~/Library/LaunchAgent.

launchctl load -w

But more confusing is using the -w switch with unload. The job is not only deregistered but disabled and you can’t load it again unless you use the -w switch with load.
Don’t use the -w switch with load and really don’t use it with unload. The -w switch doesn’t provide a useful option and if you use it with unload it can leave you completely confused.

For completeness the -w option creates or modifies an entry in the users launchd database to disable a particular job. The file it modifies is:


Where NNN is your user id, which you can find out using the id command in the terminal:


The information about the -w switch comes from:


LaunchAgents and XPC

Getting a LaunchAgent up and running

I’ve had quite a struggle getting a LaunchAgent with the features I want working. This blog piece I hope will be your short cut to avoid wasting the amount of time I have getting my LaunchAgent working. Much of this blog piece is a gripe about the unclear documentation.

You can download my example LaunchAgent project from GitHub.

Please read the file and you can then play around with the project.

A LaunchAgent belongs to a collection of executables that includes, LaunchDaemons, LoginItems and XPC Services from now on I’ll call them service providers. Service providers add functionality or do work for an application or the operating system. They mostly don’t display any User Interface (UI). LoginItems can display UI and can be full applications, LaunchDaemons can’t display any UI and the same goes for XPC services, LaunchAgents can display UI though it is not recommended.
Read the rest of this entry »


Cocoa Interprocess Communication with XPC

WWDC 2012 Session 308

Different ways of communicating between the different parts of a multi-process application, otherwise known as Interprocess Communication (IPC).

  • Mach messages
  • Sockets
  • Distributed Objects
  • XPC

Read the rest of this entry »

Tags: ,