[apple/launchd.git] / launchd / src / launchctl.1

.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
Commit	Line	Data
e91b9f68 A	1	.Dd September 30, 2004
	2	.Dt launchctl 1
	3	.Os Darwin
	4	.Sh NAME
	5	.Nm launchctl
	6	.Nd Interfaces with launchd
	7	.Sh SYNOPSIS
	8	.Nm
	9	.Op Ar subcommand Op Ar arguments ...
	10	.Sh DESCRIPTION
	11	.Nm
	12	interfaces with
	13	.Nm launchd
	14	to load, unload daemons/agents and generally control
	15	.Nm launchd .
	16	.Nm
	17	supports taking subcommands on the command line, interactively or even redirected from standard input.
	18	These commands can be stored in
	19	.Nm $HOME/.launchd.conf
	20	or
	21	.Nm /etc/launchd.conf
	22	to be read at the time
	23	.Nm launchd
	24	starts.
	25	.Sh SUBCOMMANDS
	26	.Bl -tag -width -indent
ab36757d	27	.It Xo Ar load Op Fl wF
ed34e3c3 A	28	.Op Fl S Ar sessiontype
ed34e3c3 A	29	.Op Fl D Ar domain
e91b9f68 A	30	.Ar paths ...
	31	.Xc
	32	Load the specified configuration files or directories of configuration files.
ed34e3c3 A	33	Jobs that are not on-demand will be started as soon as possible.
ed34e3c3 A	34	All specified jobs will be loaded before any of them are allowed to start.
e91b9f68 A	35	.Bl -tag -width -indent
	36	.It Fl w
	37	Remove the disabled key and write the configuration files back out to disk.
ab36757d A	38	.It Fl F
ab36757d A	39	Force the loading of the plist. Ignore the Disabled key.
ed34e3c3 A	40	.It Fl S Ar sessiontype
	41	Some jobs only make sense in certain contexts. This flag instructs
	42	.Nm launchctl
	43	to look for jobs in a different location when using the -D flag, and allows
	44	.Nm launchctl
	45	to restrict which jobs are loaded into which session types. Currently known
5b0a4722	46	session types include: Aqua, LoginWindow, Background, StandardIO and System.
ed34e3c3 A	47	.It Fl D Ar domain
	48	Look for
	49	.Xr plist 5 files ending in *.plist in the domain given. Valid domains include
	50	"system," "local," "network" and "all." When providing a session type, an additional
	51	domain is available for use called "user." For example, without a session type given,
	52	"-D system" would load from property list files from /System/Library/LaunchDaemons.
	53	With a session type passed, it would load from /System/Library/LaunchAgents.
e91b9f68 A	54	.El
e91b9f68 A	55	.It Xo Ar unload Op Fl w
5b0a4722 A	56	.Op Fl S Ar sessiontype
5b0a4722 A	57	.Op Fl D Ar domain
e91b9f68 A	58	.Ar paths ...
	59	.Xc
	60	Unload the specified configuration files or directories of configuration files.
ed34e3c3	61	This will also stop the job if it is running.
e91b9f68 A	62	.Bl -tag -width -indent
	63	.It Fl w
	64	Add the disabled key and write the configuration files back out to disk.
5b0a4722 A	65	.It Fl S Ar sessiontype
	66	Some jobs only make sense in certain contexts. This flag instructs
	67	.Nm launchctl
	68	to look for jobs in a different location when using the -D flag, and allows
	69	.Nm launchctl
	70	to restrict which jobs are loaded into which session types. Currently known
	71	session types include: Aqua, LoginWindow, Background, StandardIO and System.
	72	.It Fl D Ar domain
	73	Look for
	74	.Xr plist 5 files ending in *.plist in the domain given. Valid domains include
	75	"system," "local," "network" and "all." When providing a session type, an additional
	76	domain is available for use called "user." For example, without a session type given,
	77	"-D system" would load from property list files from /System/Library/LaunchDaemons.
	78	With a session type passed, it would load from /System/Library/LaunchAgents.
e91b9f68	79	.El
ed34e3c3 A	80	.It Xo Ar submit Fl l Ar label
	81	.Op Fl p Ar executable
	82	.Op Fl o Ar path
	83	.Op Fl e Ar path
	84	.Ar -- command
	85	.Op Ar args
	86	.Xc
	87	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.
	88	.Bl -tag -width -indent
	89	.It Fl l Ar label
	90	What unique label to assign this job to launchd.
	91	.It Fl p Ar program
	92	What program to really execute, regardless of what follows the -- in the submit sub-command.
	93	.It Fl o Ar path
	94	Where to send the stdout of the program.
	95	.It Fl e Ar path
	96	Where to send the stderr of the program.
	97	.El
	98	.It Ar remove Ar job_label
5b0a4722	99	Remove the job from launchd by label.
ed34e3c3	100	.It Ar start Ar job_label
5b0a4722	101	Start the specified job by label. The expected use of this subcommand is for
ed34e3c3 A	102	debugging and testing so that one can manually kick-start an on-demand server.
ed34e3c3 A	103	.It Ar stop Ar job_label
5b0a4722	104	Stop the specified job by label. If a job is on-demand, launchd may immediately
ed34e3c3 A	105	restart the job if launchd finds any criteria that is satisfied.
	106	Non-demand based jobs will always be restarted. Use of this subcommand is discouraged.
	107	Jobs should ideally idle timeout by themselves.
e91b9f68 A	108	.It Ar list
	109	List all of the jobs loaded into
	110	.Nm launchd .
	111	.It Ar setenv Ar key Ar value
	112	Set an environmental variable inside of
	113	.Nm launchd .
	114	.It Ar unsetenv Ar key
	115	Unset an environmental variable inside of
	116	.Nm launchd .
	117	.It Ar getenv Ar key
	118	Get an environmental variable inside of
	119	.Nm launchd .
	120	.It Ar export
	121	Export all of the environmental variables of
	122	.Nm launchd
	123	for use in a shell eval statement.
	124	.It Ar getrusage self \| children
	125	Get the resource utilization statistics for
	126	.Nm launchd
	127	or the children of
	128	.Nm launchd .
	129	.It Xo Ar log
	130	.Op Ar level loglevel
	131	.Op Ar only \| mask loglevels...
	132	.Xc
	133	Get and set the
	134	.Xr syslog 3
	135	log level mask. The available log levels are: debug, info, notice, warning, error, critical, alert and emergency.
	136	.It Xo Ar limit
	137	.Op Ar cpu \| filesize \| data \| stack \| core \| rss \| memlock \| maxproc \| maxfiles
	138	.Op Ar both Op Ar soft \| hard
	139	.Xc
	140	With no arguments, this command prints all the resource limits of
	141	.Nm launchd
	142	as found via
	143	.Xr getrlimit 2 .
	144	When a given resource is specified, it prints the limits for that resource.
	145	With a third argument, it sets both the hard and soft limits to that value.
	146	With four arguments, the third and forth argument represent the soft and hard limits respectively.
	147	See
	148	.Xr setrlimit 2 .
e91b9f68 A	149	.It Ar shutdown
	150	Tell
	151	.Nm launchd
	152	to prepare for shutdown by removing all jobs.
e91b9f68 A	153	.It Ar umask Op Ar newmask
	154	Get or optionally set the
	155	.Xr umask 2
	156	of
	157	.Nm launchd .
ed34e3c3 A	158	.It Ar bslist Op Ar PID
	159	This prints out Mach bootstrap services and their respective states. While the
	160	namespace appears flat, it is in fact hierarchical, thus allowing for certain
	161	services to be only available to a subset of processes. The three states a
5b0a4722	162	service can be in are active ("A"), inactive ("I") and on-demand ("D").
ed34e3c3 A	163	.It Ar bsexec Ar PID command Op Ar args
	164	This executes the given command in the same Mach bootstrap namespace hierachy
	165	as the given PID.
e91b9f68 A	166	.It Ar help
	167	Print out a quick usage statement.
	168	.El
ab36757d A	169	.Sh ENVIRONMENTAL VARIABLES
	170	.Bl -tag -width -indent
	171	.It Pa LAUNCHD_SOCKET
	172	This variable informs launchctl how to find the correct launchd to talk to. If it is missing, launchctl will use a built-in default.
	173	.El
e91b9f68 A	174	.Sh FILES
	175	.Bl -tag -width "/System/Library/LaunchDaemons" -compact
	176	.It Pa ~/Library/LaunchAgents
	177	Per-user agents provided by the user.
	178	.It Pa /Library/LaunchAgents
	179	Per-user agents provided by the administrator.
	180	.It Pa /Library/LaunchDaemons
	181	System wide daemons provided by the administrator.
	182	.It Pa /System/Library/LaunchAgents
	183	Mac OS X Per-user agents.
	184	.It Pa /System/Library/LaunchDaemons
	185	Mac OS X System wide daemons.
	186	.El
	187	.Sh SEE ALSO
	188	.Xr launchd.plist 5 ,
	189	.Xr launchd.conf 5 ,
	190	.Xr launchd 8