launchd/src/launchctl.1

   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
  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
  32 Load the specified configuration files or directories of configuration files.
  33 Jobs that are not on-demand will be started as soon as possible.
  34 All specified jobs will be loaded before any of them are allowed to start.
  35 .Bl -tag -width -indent
  36 .It Fl w
  37 Remove the disabled key and write the configuration files back out to disk.
  38 .It Fl F
  39 Force the loading of the plist. Ignore the Disabled key.
  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
  46 session types include: Aqua, LoginWindow, Background, StandardIO and System.
  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.
  54 .El
  55 .It Xo Ar unload Op Fl w
  56 .Op Fl S Ar sessiontype
  57 .Op Fl D Ar domain
  58 .Ar paths ...
  59 .Xc
  60 Unload the specified configuration files or directories of configuration files.
  61 This will also stop the job if it is running.
  62 .Bl -tag -width -indent
  63 .It Fl w
  64 Add the disabled key and write the configuration files back out to disk.
  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.
  79 .El
  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
  99 Remove the job from launchd by label.
 100 .It Ar start Ar job_label
 101 Start the specified job by label. The expected use of this subcommand is for
 102 debugging and testing so that one can manually kick-start an on-demand server.
 103 .It Ar stop Ar job_label
 104 Stop the specified job by label. If a job is on-demand, launchd may immediately
 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.
 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 .
 149 .It Ar shutdown
 150 Tell
 151 .Nm launchd
 152 to prepare for shutdown by removing all jobs.
 153 .It Ar umask Op Ar newmask
 154 Get or optionally set the
 155 .Xr umask 2
 156 of
 157 .Nm launchd .
 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
 162 service can be in are active ("A"), inactive ("I") and on-demand ("D").
 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.
 166 .It Ar help
 167 Print out a quick usage statement.
 168 .El
 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
 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