.Dd September 30, 2004
.Dt launchctl 1
.Os Darwin
.Sh NAME
.Nm launchctl
.Nd Interfaces with launchd
.Sh SYNOPSIS
.Nm
.Op Ar subcommand Op Ar arguments ...
.Sh DESCRIPTION
.Nm
interfaces with
.Nm launchd
to load, unload daemons/agents and generally control
.Nm launchd .
.Nm
supports taking subcommands on the command line, interactively or even redirected from standard input.
These commands can be stored in
.Nm $HOME/.launchd.conf
or
.Nm /etc/launchd.conf
to be read at the time
.Nm launchd
starts.
.Sh SUBCOMMANDS
.Bl -tag -width -indent
.It Xo Ar load Op Fl wF
.Op Fl S Ar sessiontype
.Op Fl D Ar domain
.Ar paths ...
.Xc
Load the specified configuration files or directories of configuration files.
Jobs that are not on-demand will be started as soon as possible.
All specified jobs will be loaded before any of them are allowed to start.
.Bl -tag -width -indent
.It Fl w
Remove the disabled key and write the configuration files back out to disk.
.It Fl F
Force the loading of the plist. Ignore the Disabled key.
.It Fl S Ar sessiontype
Some jobs only make sense in certain contexts. This flag instructs
.Nm launchctl
to look for jobs in a different location when using the -D flag, and allows
.Nm launchctl
to restrict which jobs are loaded into which session types. Currently known
session types include: Aqua, LoginWindow, Background, StandardIO and System.
.It Fl D Ar domain
Look for
.Xr plist 5 files ending in *.plist in the domain given. Valid domains include
"system," "local," "network" and "all." When providing a session type, an additional
domain is available for use called "user." For example, without a session type given,
"-D system" would load from property list files from /System/Library/LaunchDaemons.
With a session type passed, it would load from /System/Library/LaunchAgents.
.El
.It Xo Ar unload Op Fl w
.Op Fl S Ar sessiontype
.Op Fl D Ar domain
.Ar paths ...
.Xc
Unload the specified configuration files or directories of configuration files.
This will also stop the job if it is running.
.Bl -tag -width -indent
.It Fl w
Add the disabled key and write the configuration files back out to disk.
.It Fl S Ar sessiontype
Some jobs only make sense in certain contexts. This flag instructs
.Nm launchctl
to look for jobs in a different location when using the -D flag, and allows
.Nm launchctl
to restrict which jobs are loaded into which session types. Currently known
session types include: Aqua, LoginWindow, Background, StandardIO and System.
.It Fl D Ar domain
Look for
.Xr plist 5 files ending in *.plist in the domain given. Valid domains include
"system," "local," "network" and "all." When providing a session type, an additional
domain is available for use called "user." For example, without a session type given,
"-D system" would load from property list files from /System/Library/LaunchDaemons.
With a session type passed, it would load from /System/Library/LaunchAgents.
.El
.It Xo Ar submit Fl l Ar label
.Op Fl p Ar executable
.Op Fl o Ar path
.Op Fl e Ar path
.Ar -- command
.Op Ar args
.Xc
A simple way of submitting a program to run without a configuration file. This mechanism also tells launchd to keep the program alive in the event of failure.
.Bl -tag -width -indent
.It Fl l Ar label
What unique label to assign this job to launchd.
.It Fl p Ar program
What program to really execute, regardless of what follows the -- in the submit sub-command.
.It Fl o Ar path
Where to send the stdout of the program.
.It Fl e Ar path
Where to send the stderr of the program.
.El
.It Ar remove Ar job_label
Remove the job from launchd by label.
.It Ar start Ar job_label
Start the specified job by label. The expected use of this subcommand is for
debugging and testing so that one can manually kick-start an on-demand server.
.It Ar stop Ar job_label
Stop the specified job by label. If a job is on-demand, launchd may immediately
restart the job if launchd finds any criteria that is satisfied.
Non-demand based jobs will always be restarted. Use of this subcommand is discouraged.
Jobs should ideally idle timeout by themselves.
.It Ar list
List all of the jobs loaded into
.Nm launchd .
.It Ar setenv Ar key Ar value
Set an environmental variable inside of
.Nm launchd .
.It Ar unsetenv Ar key
Unset an environmental variable inside of
.Nm launchd .
.It Ar getenv Ar key
Get an environmental variable inside of
.Nm launchd .
.It Ar export
Export all of the environmental variables of
.Nm launchd
for use in a shell eval statement.
.It Ar getrusage self | children
Get the resource utilization statistics for
.Nm launchd
or the children of
.Nm launchd .
.It Xo Ar log
.Op Ar level loglevel
.Op Ar only | mask loglevels...
.Xc
Get and set the
.Xr syslog 3
log level mask. The available log levels are: debug, info, notice, warning, error, critical, alert and emergency.
.It Xo Ar limit
.Op Ar cpu | filesize | data | stack | core | rss | memlock | maxproc | maxfiles
.Op Ar both Op Ar soft | hard
.Xc
With no arguments, this command prints all the resource limits of
.Nm launchd
as found via
.Xr getrlimit 2 .
When a given resource is specified, it prints the limits for that resource.
With a third argument, it sets both the hard and soft limits to that value.
With four arguments, the third and forth argument represent the soft and hard limits respectively.
See
.Xr setrlimit 2 .
.It Ar shutdown
Tell
.Nm launchd
to prepare for shutdown by removing all jobs.
.It Ar umask Op Ar newmask
Get or optionally set the
.Xr umask 2
of
.Nm launchd .
.It Ar bslist Op Ar PID
This prints out Mach bootstrap services and their respective states. While the
namespace appears flat, it is in fact hierarchical, thus allowing for certain
services to be only available to a subset of processes. The three states a
service can be in are active ("A"), inactive ("I") and on-demand ("D").
.It Ar bsexec Ar PID command Op Ar args
This executes the given command in the same Mach bootstrap namespace hierachy
as the given PID.
.It Ar help
Print out a quick usage statement.
.El
.Sh ENVIRONMENTAL VARIABLES
.Bl -tag -width -indent
.It Pa LAUNCHD_SOCKET
This variable informs launchctl how to find the correct launchd to talk to. If it is missing, launchctl will use a built-in default.
.El
.Sh FILES
.Bl -tag -width "/System/Library/LaunchDaemons" -compact
.It Pa ~/Library/LaunchAgents
Per-user agents provided by the user.
.It Pa /Library/LaunchAgents
Per-user agents provided by the administrator.
.It Pa /Library/LaunchDaemons
System wide daemons provided by the administrator.
.It Pa /System/Library/LaunchAgents
Mac OS X Per-user agents.
.It Pa /System/Library/LaunchDaemons
Mac OS X System wide daemons.
.El
.Sh SEE ALSO
.Xr launchd.plist 5 ,
.Xr launchd.conf 5 ,
.Xr launchd 8