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, X11 and tty.
  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 .Ar paths ...
  57 .Xc
  58 Unload the specified configuration files or directories of configuration files.
  59 This will also stop the job if it is running.
  60 .Bl -tag -width -indent
  61 .It Fl w
  62 Add the disabled key and write the configuration files back out to disk.
  63 .El
  64 .It Xo Ar submit Fl l Ar label
  65 .Op Fl p Ar executable
  66 .Op Fl o Ar path
  67 .Op Fl e Ar path
  68 .Ar -- command
  69 .Op Ar args
  70 .Xc
  71 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.
  72 .Bl -tag -width -indent
  73 .It Fl l Ar label
  74 What unique label to assign this job to launchd.
  75 .It Fl p Ar program
  76 What program to really execute, regardless of what follows the -- in the submit sub-command.
  77 .It Fl o Ar path
  78 Where to send the stdout of the program.
  79 .It Fl e Ar path
  80 Where to send the stderr of the program.
  81 .El
  82 .It Ar remove Ar job_label
  83 Remove the jobs from launchd by label.
  84 .It Ar start Ar job_label
  85 Start the specified jobs by label. The expected use of this subcommand is for
  86 debugging and testing so that one can manually kick-start an on-demand server.
  87 .It Ar stop Ar job_label
  88 Stop the specified jobs by label. If a job is on-demand, launchd may immediately
  89 restart the job if launchd finds any criteria that is satisfied.
  90 Non-demand based jobs will always be restarted. Use of this subcommand is discouraged.
  91 Jobs should ideally idle timeout by themselves.
  92 .It Ar list
  93 List all of the jobs loaded into
  94 .Nm launchd .
  95 .It Ar setenv Ar key Ar value
  96 Set an environmental variable inside of
  97 .Nm launchd .
  98 .It Ar unsetenv Ar key
  99 Unset an environmental variable inside of
 100 .Nm launchd .
 101 .It Ar getenv Ar key
 102 Get an environmental variable inside of
 103 .Nm launchd .
 104 .It Ar export
 105 Export all of the environmental variables of
 106 .Nm launchd
 107 for use in a shell eval statement.
 108 .It Ar getrusage self | children
 109 Get the resource utilization statistics for
 110 .Nm launchd
 111 or the children of
 112 .Nm launchd .
 113 .It Xo Ar log
 114 .Op Ar level loglevel
 115 .Op Ar only | mask loglevels...
 116 .Xc
 117 Get and set the
 118 .Xr syslog 3
 119 log level mask. The available log levels are: debug, info, notice, warning, error, critical, alert and emergency.
 120 .It Xo Ar limit
 121 .Op Ar cpu | filesize | data | stack | core | rss | memlock | maxproc | maxfiles
 122 .Op Ar both Op Ar soft | hard
 123 .Xc
 124 With no arguments, this command prints all the resource limits of
 125 .Nm launchd
 126 as found via
 127 .Xr getrlimit 2 .
 128 When a given resource is specified, it prints the limits for that resource.
 129 With a third argument, it sets both the hard and soft limits to that value.
 130 With four arguments, the third and forth argument represent the soft and hard limits respectively.
 131 See
 132 .Xr setrlimit 2 .
 133 .It Ar stdout path
 134 Set the standard out file descriptor to the given path.
 135 .Nm launchd
 136 .It Ar stderr path
 137 Set the standard error file descriptor to the given path.
 138 .Nm launchd
 139 .It Ar shutdown
 140 Tell
 141 .Nm launchd
 142 to prepare for shutdown by removing all jobs.
 143 .It Ar reloadttys
 144 Tell
 145 .Nm launchd
 146 to reread /etc/ttys. This option may go away in a future release.
 147 .It Ar umask Op Ar newmask
 148 Get or optionally set the
 149 .Xr umask 2
 150 of
 151 .Nm launchd .
 152 .It Ar bslist Op Ar PID
 153 This prints out Mach bootstrap services and their respective states. While the
 154 namespace appears flat, it is in fact hierarchical, thus allowing for certain
 155 services to be only available to a subset of processes. The three states a
 156 service can be in are active ("A"), in-active ("I") and on-demand ("D").
 157 .It Ar bsexec Ar PID command Op Ar args
 158 This executes the given command in the same Mach bootstrap namespace hierachy
 159 as the given PID.
 160 .It Ar help
 161 Print out a quick usage statement.
 162 .El
 163 .Sh ENVIRONMENTAL VARIABLES
 164 .Bl -tag -width -indent
 165 .It Pa LAUNCHD_SOCKET
 166 This variable informs launchctl how to find the correct launchd to talk to. If it is missing, launchctl will use a built-in default.
 167 .El
 168 .Sh FILES
 169 .Bl -tag -width "/System/Library/LaunchDaemons" -compact
 170 .It Pa ~/Library/LaunchAgents
 171 Per-user agents provided by the user.
 172 .It Pa /Library/LaunchAgents
 173 Per-user agents provided by the administrator.
 174 .It Pa /Library/LaunchDaemons
 175 System wide daemons provided by the administrator.
 176 .It Pa /System/Library/LaunchAgents
 177 Mac OS X Per-user agents.
 178 .It Pa /System/Library/LaunchDaemons
 179 Mac OS X System wide daemons.
 180 .El
 181 .Sh SEE ALSO
 182 .Xr launchd.plist 5 ,
 183 .Xr launchd.conf 5 ,
 184 .Xr launchd 8