overby.me
this repo has no description
1.Dd 1 May, 2009
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
12interfaces with
13.Nm launchd
14to load, unload daemons/agents and generally control
15.Nm launchd .
16.Nm
17supports taking subcommands on the command line, interactively or even redirected from standard input.
18These commands can be stored in
19.Nm $HOME/.launchd.conf
20or
21.Nm /etc/launchd.conf
22to be read at the time
23.Nm launchd
24starts.
25.Sh SUBCOMMANDS
26.Bl -tag -width -indent
27.It Xo Ar load Op Fl wF
28.Op Fl S Ar sessiontype
29.Op Fl D Ar domain
30.Ar paths ...
31.Xc
32Load the specified configuration files or directories of configuration files.
33Jobs that are not on-demand will be started as soon as possible.
34All specified jobs will be loaded before any of them are allowed to start.
35Note that per-user configuration files (LaunchAgents) must be owned by the user
36loading them. All system-wide daemons (LaunchDaemons) must be owned by root. Configuration files
37must not be group- or world-writable. These restrictions are in place for security reasons,
38as allowing writability to a launchd configuration file allows one to specify which executable
39will be launched.
40.Pp
41Note that allowing non-root write access to the /System/Library/LaunchDaemons directory WILL render your system unbootable.
42.Bl -tag -width -indent
43.It Fl w
44Overrides the Disabled key and sets it to false. In previous versions, this option
45would modify the configuration file. Now the state of the Disabled key is stored
46elsewhere on-disk.
47.It Fl F
48Force the loading of the plist. Ignore the Disabled key.
49.It Fl S Ar sessiontype
50Some jobs only make sense in certain contexts. This flag instructs
51.Nm launchctl
52to look for jobs in a different location when using the -D flag, and allows
53.Nm launchctl
54to restrict which jobs are loaded into which session types. Currently known
55session types include: Aqua, LoginWindow, Background, StandardIO and System.
56.It Fl D Ar domain
57Look for
58.Xr plist 5 files ending in *.plist in the domain given. Valid domains include
59"system," "local," "network" and "all." When providing a session type, an additional
60domain is available for use called "user." For example, without a session type given,
61"-D system" would load from property list files from /System/Library/LaunchDaemons.
62With a session type passed, it would load from /System/Library/LaunchAgents.
63.El
64.It Xo Ar unload Op Fl w
65.Op Fl S Ar sessiontype
66.Op Fl D Ar domain
67.Ar paths ...
68.Xc
69Unload the specified configuration files or directories of configuration files.
70This will also stop the job if it is running.
71.Bl -tag -width -indent
72.It Fl w
73Overrides the Disabled key and sets it to true. In previous versions, this option
74would modify the configuration file. Now the state of the Disabled key is stored
75elsewhere on-disk.
76.It Fl S Ar sessiontype
77Some jobs only make sense in certain contexts. This flag instructs
78.Nm launchctl
79to look for jobs in a different location when using the -D flag, and allows
80.Nm launchctl
81to restrict which jobs are loaded into which session types. Currently known
82session types include: Aqua, LoginWindow, Background, StandardIO and System.
83.It Fl D Ar domain
84Look for
85.Xr plist 5 files ending in *.plist in the domain given. Valid domains include
86"system," "local," "network" and "all." When providing a session type, an additional
87domain is available for use called "user." For example, without a session type given,
88"-D system" would load from property list files from /System/Library/LaunchDaemons.
89With a session type passed, it would load from /System/Library/LaunchAgents.
90.El
91.It Xo Ar submit Fl l Ar label
92.Op Fl p Ar executable
93.Op Fl o Ar path
94.Op Fl e Ar path
95.Ar -- command
96.Op Ar args
97.Xc
98A 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.
99.Bl -tag -width -indent
100.It Fl l Ar label
101What unique label to assign this job to launchd.
102.It Fl p Ar program
103What program to really execute, regardless of what follows the -- in the submit sub-command.
104.It Fl o Ar path
105Where to send the stdout of the program.
106.It Fl e Ar path
107Where to send the stderr of the program.
108.El
109.It Ar remove Ar job_label
110Remove the job from launchd by label.
111.It Ar start Ar job_label
112Start the specified job by label. The expected use of this subcommand is for
113debugging and testing so that one can manually kick-start an on-demand server.
114.It Ar stop Ar job_label
115Stop the specified job by label. If a job is on-demand, launchd may immediately
116restart the job if launchd finds any criteria that is satisfied.
117Non-demand based jobs will always be restarted. Use of this subcommand is discouraged.
118Jobs should ideally idle timeout by themselves.
119.It Xo Ar list
120.Op Ar -x
121.Op Ar label
122.Xc
123With no arguments, list all of the jobs loaded into
124.Nm launchd
125in three columns. The first column displays the PID of the job if it is running.
126The second column displays the last exit status of the job. If the number in this
127column is negative, it represents the negative of the signal which killed the job.
128Thus, "-15" would indicate that the job was terminated with SIGTERM. The third column
129is the job's label.
130.Pp
131Note that you may see some jobs in the list whose labels are in the style "0xdeadbeef.anonymous.program".
132These are jobs which are not managed by
133.Nm launchd ,
134but, at one point, made a request to it.
135.Nm launchd
136claims no ownership and makes no guarantees regarding these jobs. They are stored purely for
137bookkeeping purposes.
138.Pp
139Similarly, you may see labels of the style "0xdeadbeef.mach_init.program". These are legacy jobs that run
140under mach_init emulation. This mechanism will be removed in future versions, and all remaining mach_init
141jobs should be converted over to
142.Nm launchd .
143.Pp
144If
145.Op Ar label
146is specified, prints information about the requested job. If
147.Op Ar -x
148is specified, the information for the specified job is output as an XML property list.
149.It Ar setenv Ar key Ar value
150Set an environmental variable inside of
151.Nm launchd .
152.It Ar unsetenv Ar key
153Unset an environmental variable inside of
154.Nm launchd .
155.It Ar getenv Ar key
156Get an environmental variable inside of
157.Nm launchd .
158.It Ar export
159Export all of the environmental variables of
160.Nm launchd
161for use in a shell eval statement.
162.It Ar getrusage self | children
163Get the resource utilization statistics for
164.Nm launchd
165or the children of
166.Nm launchd .
167.It Xo Ar log
168.Op Ar level loglevel
169.Op Ar only | mask loglevels...
170.Xc
171Get and set the
172.Xr syslog 3
173log level mask. The available log levels are: debug, info, notice, warning, error, critical, alert and emergency.
174.It Xo Ar limit
175.Op Ar cpu | filesize | data | stack | core | rss | memlock | maxproc | maxfiles
176.Op Ar both Op Ar soft | hard
177.Xc
178With no arguments, this command prints all the resource limits of
179.Nm launchd
180as found via
181.Xr getrlimit 2 .
182When a given resource is specified, it prints the limits for that resource.
183With a third argument, it sets both the hard and soft limits to that value.
184With four arguments, the third and forth argument represent the soft and hard limits respectively.
185See
186.Xr setrlimit 2 .
187.It Ar shutdown
188Tell
189.Nm launchd
190to prepare for shutdown by removing all jobs.
191.It Ar umask Op Ar newmask
192Get or optionally set the
193.Xr umask 2
194of
195.Nm launchd .
196.It Xo Ar bslist
197.Op Ar PID | ..
198.Op Ar -j
199.Xc
200This prints out Mach bootstrap services and their respective states. While the
201namespace appears flat, it is in fact hierarchical, thus allowing for certain
202services to be only available to a subset of processes. The three states a
203service can be in are active ("A"), inactive ("I") and on-demand ("D").
204.Pp
205If
206.Op Ar PID
207is specified, print the Mach bootstrap services available to that PID. If
208.Op Ar ..
209is specified, print the Mach bootstrap services available in the parent of the
210current bootstrap. Note that in Mac OS X v10.6, the per-user Mach bootstrap namespace
211is flat, so you will only see a different set of services in a per-user bootstrap
212if you are in an explicitly-created bootstrap subset.
213.Pp
214If
215.Op Ar -j
216is specified, each service name will be followed by the name of the job which registered
217it.
218.It Ar bsexec Ar PID command Op Ar args
219This executes the given command in the same Mach bootstrap namespace hierachy
220as the given PID.
221.It Ar bstree Op Ar -j
222This prints a hierarchical view of the entire Mach bootstrap tree. If
223.Op Ar -j
224is specified, each service name will be followed by the name of the job which registered it.
225Requires root
226privileges.
227.It Ar managerpid
228This prints the PID of the launchd which manages the current bootstrap.
229.It Ar manageruid
230This prints the UID of the launchd which manages the current bootstrap.
231.It Ar managername
232This prints the name of the launchd job manager which manages the current bootstrap.
233See LimitLoadToSessionType in
234.Xr launchd.plist 5
235for more details.
236.It Ar help
237Print out a quick usage statement.
238.El
239.Sh ENVIRONMENTAL VARIABLES
240.Bl -tag -width -indent
241.It Pa LAUNCHD_SOCKET
242This variable informs launchctl how to find the correct launchd to talk to. If it is missing, launchctl will use a built-in default.
243.El
244.Sh FILES
245.Bl -tag -width "/System/Library/LaunchDaemons" -compact
246.It Pa ~/Library/LaunchAgents
247Per-user agents provided by the user.
248.It Pa /Library/LaunchAgents
249Per-user agents provided by the administrator.
250.It Pa /Library/LaunchDaemons
251System wide daemons provided by the administrator.
252.It Pa /System/Library/LaunchAgents
253Mac OS X Per-user agents.
254.It Pa /System/Library/LaunchDaemons
255Mac OS X System wide daemons.
256.El
257.Sh SEE ALSO
258.Xr launchd.plist 5 ,
259.Xr launchd.conf 5 ,
260.Xr launchd 8