Functional Specification

This page tries to capture some ideas for how various components of launchd will function.

Methods

1. Methods are strings containing sh(1) scripts.
2. Anything following a '--' is passed to the method "as is" by launchadm. Example:

launchadm com.example.my_job start -- --foo=bar --baz --whatever

1. The environment is sanitized prior to running the script
2. Specific launchd variables are added to the environment, prefixed by LAUNCHD_. Example:

LAUNCHD_JOB_PID=1982

Properties

1. Properties are declared in the DefaultProperties dictionary in the manifest.
2. Properties are user-defined and have no meaning to launchd, with the exception of properties that start with __launchd.
3. Properties are stored in a form that allows event-driven waiting using kevent() or epoll() or similar.

Events

1. Events are simply changes in property files that can be detected by clients who monitor the filesystem.
2. No direct coordination between launchd and event waiters is performed.

Conditions

Conditions can be used for:

• dependency ordering between jobs
• starting and stopping jobs based on an "enable" property being changed
• running things during the initial system boot
• running things prior to power events (halt or sleep)
• running things during system shutdown
• restarting a service automatically as long as certain conditions hold (e.g. the network is up)

1. Jobs may specify conditions that affect when the job is started or stopped.
2. A condition takes the form of:

property operator value

1. Operators include the equality (==) and inequality (!=) operations.
2. Multiple conditions may be joined in an expression using && or || operators. Example:

foo == "bar" && baz != "bam"

Labels

1. Labels are specified using Reverse Domain Notation.
2. Valid characters in a label are dots, dashes, underscores, percent sign, and alphanumerics.
3. Invalid characters may be specified by converting them to UTF-8 and using percent-encoding.
4. Valid labels must conform to the following Ruby-compatible regular expression: ```/\A[A-Za-z0-9][A-Za-z0-9%_.-]+\z/
5. The shortname of a label is everything after the final dot.
6. In command line tools (but not manifests), jobs may be referred to via a shortname. If multiple shortnames match, the command will fail and print a message asking the user to resolve the ambiguity.