I tried to configure a launch daemon to OS X but stumbled on a configuration issue that in my opinion isn’t explained very clearly in the documentation. Perhaps I’m the only one to find it unclear but in the case that somebody else should get stuck with the same issue I’ll explain it here.
This issue is about the
ProgramArguments keys in the
launchd.plist configuration file. Those keys specify the command that should be run as the launch daemon or agent. I won’t explain anything general about launch daemons or agents here since it’s documented in many places already.
The Program and ProgramArguments keys
Here is the relevant documentation that I used first in order to get a launch daemon configured.
This key maps to the first argument of execvp(3). 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 key.
ProgramArguments <array of strings>
This key maps to the second argument of execvp(3). This key is required in the absence of the Program key. Please note: many people are confused by this key. Please read execvp(3) very carefully!
That documentation refers the reader to execvp(3) documentation. Which is stupid in my opinion – it could just explain the parameters there in place and not make half-arsed notes about people getting confused. If users get confused while reading documentation it’s a sign that the documentation should be improved!
ProgramArguments repeat execvp‘s arguments. So let’s read execvp(3) carefully then.
man execvp (emphasis mine)
int execvp(const char *file, char *const argv);
The initial argument for these functions is the pathname of a file which is to be executed.
The [–] execvp() [–] function[s] provide an array of pointers to null-terminated strings that represent the argument list available to the new program. The first argument, by convention, should point to the file name associated with the file being executed. [–]
So the first argument (
file) is the program to be executed. The second argument (
argv) contains the arguments for the program and of those the first one is by convention the name of the program that is executed. So pretty much the same as the
I know that programs usually get the name of the program file as the first command line argument. And perhaps there is a valid use case for an interface like execvp. But I can’t understand why Apple considered this interface to be so suitable for the
launchd.plist configuration files that they decided to carefully replicate it.
How to use the Program and ProgramArguments parameters
So here’s my newly developed guidelines for using these parameters.
- never use both
ProgramArgumentsparameters in the same configuration file.
- if your program is run without arguments you can use
Programand save some typing. But still
- you can always use
ProgramArguments. The first array member shall be the executable name.
Using only Program
This runs the
date program without any arguments as expected.
Using only ProgramArguments
<key>ProgramArguments</key> <array> <string>/usr/bin/touch</string> <string>/tmp/test</string> </array>
touch /tmp/test as expected.
Using both Program and ProgramArguments
Don’t do this unless you really understand what you are asking for and need it!
<key>Program</key> <string>/usr/bin/touch</string> <key>ProgramArguments</key> <array> <string>/bin/date</string> <string>/tmp/test</string> </array>
This does not run
touch /bin/date /tmp/test as one might think. This runs the equivalent of
touch /tmp/test. The first member in the arguments array (
/bin/date) is effectively dropped. Better avoid this since it’s so confusing.