Difference between revisions of "Daemons"

From iPhone Development Wiki
Jump to: navigation, search
m (References: Technical Note TN2083)
(The plist)
Line 17: Line 17:
 
Place your plist, following the reverse DNS notation (com.your.daemon), in <code>layout/Library/LaunchDaemons</code>.
 
Place your plist, following the reverse DNS notation (com.your.daemon), in <code>layout/Library/LaunchDaemons</code>.
  
''To do: table specifying the keys and values.''
+
'''Required Keys'''
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Key
 +
! Description
 +
! Type of Value
 +
! Note
 +
|-
 +
| Label
 +
| Unique identifier for your daemon
 +
| String
 +
| ---
 +
|-
 +
| Program
 +
| This key maps to the first argument of execvp(3). If missing, the first Argument of ProgramArguments is used.
 +
| String
 +
| Only required in absense of '''ProgramArguments''' key
 +
|-
 +
| ProgramArguments
 +
| This key maps to the second argument of execvp(3). If missing, the first Argument of ProgramArguments is used.
 +
| Array of Strings
 +
| Only required in absense of '''Program''' key
 +
|}
 +
 
 +
'''Permission related Keys'''
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Key
 +
! Description
 +
! Type of Value
 +
|-
 +
| UserName
 +
| Specifies the user to run the job as
 +
| String
 +
|-
 +
| GroupName
 +
| Specifies the group to run the job as
 +
| String
 +
|}
 +
 
 +
'''Launch related Keys'''
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Key
 +
! Description
 +
! Type of Value
 +
|-
 +
| RunAtLoad
 +
| Controls whether your job is launched at boot time (when launchd launches) or not.
 +
| Boolean
 +
|-
 +
| LaunchOnlyOnce
 +
| Set this to true if you just want to execute your code once.
 +
| Boolean
 +
|-
 +
| Disabled
 +
| Tells launchctl that it should not submit this job to launchd
 +
| Boolean
 +
|-
 +
| EnvironmentVariables
 +
| Allows you to set additional environmental variables for your job. As an example: DYLD_INSERT_LIBRARIES.
 +
| Dictionary of Strings
 +
|-
 +
| WatchPaths
 +
| launchd will watch the given paths and it will launch your job when one of these paths has been modified.
 +
| Array of Strings
 +
|-
 +
| QueueDirectories
 +
| Similar to '''WatchPaths''' with the difference that watches directories not being empty.
 +
| Array of Strings
 +
|-
 +
| StartInterval
 +
| This optional key causes the job to be started every N seconds.
 +
| Integer
 +
|-
 +
| StartCalendarInterval
 +
| Specify a date or time for your Job to be started. e.g every Monday at 7PM.
 +
| Dictionary of integers or array of dictionary of integers
 +
|}
 +
 
 +
'''Lifetime related Keys'''
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Key
 +
! Description
 +
! Type of Value
 +
|-
 +
| KeepAlive
 +
| Determines whether your job is to be kept continuously running. If this is set to true and your job exits, it will respawn. Keeping the daemon alive as of 'not exiting' is your job
 +
| boolean or dictionary of stuff (well said Apple)
 +
|-
 +
| TimeOut
 +
| Idle time out (in seconds) to pass to the job. If not specified, the default time will be passed to launchd.
 +
| Integer
 +
|-
 +
| ExitTimeOut
 +
| The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity.
 +
| Integer
 +
|-
 +
| ThrottleInterval
 +
| Jobs will be respawned not more than once every 10 seconds. This key overrides the default throttling policy of launchd.
 +
| Integer
 +
|}
 +
 
 +
'''Control and Debug related Keys'''
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Key
 +
! Description
 +
! Type of Value
 +
|-
 +
| RootDirectory
 +
| This key allows you to change the root directory for your job before it launches.
 +
| String
 +
|-
 +
| WorkingDirectory
 +
| This key allows you to change the working directory for your job before it launches.
 +
| String
 +
|-
 +
| StandardInPath
 +
| You can choose a file where the data supplied by stdin will be saved,
 +
| String
 +
|-
 +
| StandardOutPath
 +
| Output from stdout will be saved to that file when using stdio(3).
 +
| String
 +
|-
 +
| StandardOutPath
 +
| Output from stdout will be saved to that file when using stdio(3).
 +
| String
 +
|-
 +
| Debug
 +
| Control wether launchd should adjust its log mask temporarily to LOG_DEBUG or not.
 +
| Boolean
 +
|-
 +
| WaitForDebugger
 +
| Instructs the kernel to wait until a debugger is detached before executing any code in your daemon.
 +
| Boolean
 +
|}
 +
 
 +
'''Other Keys'''
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Key
 +
! Description
 +
! Type of Value
 +
|-
 +
| inetdCompatibility
 +
| The daemon expects to be run as if it were launched from inetd
 +
| Dictionary
 +
|}
 +
 
 +
''To be done: Subrows for Dictionary Keys, maybe add a few more keys''
  
 
== Examples ==
 
== Examples ==

Revision as of 11:55, 6 October 2014

Daemons are programs that run as a background process. These programs may or may not have a long life cycle and exist in a paradigm different to tweaks. They do not require to be injected onto other processes, that means that they exist by themselves.

Several tweaks and programs use them such as f.lux, gremlin, rocketbootstrap, SafariDownloadEnabler, ssh.

How to make a daemon

There's two steps: making a program and making a plist for it.

The program

While idle, the program should waste the least possible resources. Remember that it is working along with many other already existing processes.

Given that memory isn't shared across processes, one cannot call functions or get objects freely between processes. To solve this, one must use some form of IPC (notifications, XPC, sockets) to communicate with the daemon.

The plist

Place your plist, following the reverse DNS notation (com.your.daemon), in layout/Library/LaunchDaemons.

Required Keys

Key Description Type of Value Note
Label Unique identifier for your daemon String ---
Program This key maps to the first argument of execvp(3). If missing, the first Argument of ProgramArguments is used. String Only required in absense of ProgramArguments key
ProgramArguments This key maps to the second argument of execvp(3). If missing, the first Argument of ProgramArguments is used. Array of Strings Only required in absense of Program key

Permission related Keys

Key Description Type of Value
UserName Specifies the user to run the job as String
GroupName Specifies the group to run the job as String

Launch related Keys

Key Description Type of Value
RunAtLoad Controls whether your job is launched at boot time (when launchd launches) or not. Boolean
LaunchOnlyOnce Set this to true if you just want to execute your code once. Boolean
Disabled Tells launchctl that it should not submit this job to launchd Boolean
EnvironmentVariables Allows you to set additional environmental variables for your job. As an example: DYLD_INSERT_LIBRARIES. Dictionary of Strings
WatchPaths launchd will watch the given paths and it will launch your job when one of these paths has been modified. Array of Strings
QueueDirectories Similar to WatchPaths with the difference that watches directories not being empty. Array of Strings
StartInterval This optional key causes the job to be started every N seconds. Integer
StartCalendarInterval Specify a date or time for your Job to be started. e.g every Monday at 7PM. Dictionary of integers or array of dictionary of integers

Lifetime related Keys

Key Description Type of Value
KeepAlive Determines whether your job is to be kept continuously running. If this is set to true and your job exits, it will respawn. Keeping the daemon alive as of 'not exiting' is your job boolean or dictionary of stuff (well said Apple)
TimeOut Idle time out (in seconds) to pass to the job. If not specified, the default time will be passed to launchd. Integer
ExitTimeOut The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity. Integer
ThrottleInterval Jobs will be respawned not more than once every 10 seconds. This key overrides the default throttling policy of launchd. Integer

Control and Debug related Keys

Key Description Type of Value
RootDirectory This key allows you to change the root directory for your job before it launches. String
WorkingDirectory This key allows you to change the working directory for your job before it launches. String
StandardInPath You can choose a file where the data supplied by stdin will be saved, String
StandardOutPath Output from stdout will be saved to that file when using stdio(3). String
StandardOutPath Output from stdout will be saved to that file when using stdio(3). String
Debug Control wether launchd should adjust its log mask temporarily to LOG_DEBUG or not. Boolean
WaitForDebugger Instructs the kernel to wait until a debugger is detached before executing any code in your daemon. Boolean

Other Keys

Key Description Type of Value
inetdCompatibility The daemon expects to be run as if it were launched from inetd Dictionary

To be done: Subrows for Dictionary Keys, maybe add a few more keys

Examples

References