manpagez: man pages & more
man launchctl(1)
Home | html | info | man
launchctl(1)              BSD General Commands Manual             launchctl(1)


NAME

     launchctl -- Interfaces with launchd


SYNOPSIS

     launchctl [subcommand [arguments ...]]


DESCRIPTION

     launchctl interfaces with launchd to load, unload daemons/agents and gen-
     erally control launchd.  launchctl supports taking subcommands on the
     command line, interactively or even redirected from standard input.
     These commands can be stored in $HOME/.launchd.conf or /etc/launchd.conf
     to be read at the time launchd starts.


SUBCOMMANDS

     load [-wF] [-S sessiontype] [-D domain] paths ...
              Load the specified configuration files or directories of config-
              uration 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.  Note that per-user configuration
              files (LaunchAgents) must be owned by the user loading them. All
              system-wide daemons (LaunchDaemons) must be owned by root. Con-
              figuration files must not be group- or world-writable. These
              restrictions are in place for security reasons, as allowing
              writability to a launchd configuration file allows one to spec-
              ify which executable will be launched.

              Note that allowing non-root write access to the /Sys-
              tem/Library/LaunchDaemons directory WILL render your system
              unbootable.

              -w       Overrides the Disabled key and sets it to false. In
                       previous versions, this option would modify the config-
                       uration file. Now the state of the Disabled key is
                       stored elsewhere on-disk.

              -F       Force the loading of the plist. Ignore the Disabled
                       key.

              -S sessiontype
                       Some jobs only make sense in certain contexts. This
                       flag instructs launchctl to look for jobs in a differ-
                       ent location when using the -D flag, and allows
                       launchctl to restrict which jobs are loaded into which
                       session types. Currently known session types include:
                       Aqua, LoginWindow, Background, StandardIO and System.

              -D domain
                       Look for plist(5) files ending in *.plist in the domain
                       given. Valid domains include "system," "local," "net-
                       work" 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 /Sys-
                       tem/Library/LaunchDaemons.  With a session type passed,
                       it would load from /System/Library/LaunchAgents.

     unload [-w] [-S sessiontype] [-D domain] paths ...
              Unload the specified configuration files or directories of con-
              figuration files.  This will also stop the job if it is running.

              -w       Overrides the Disabled key and sets it to true. In pre-
                       vious versions, this option would modify the configura-
                       tion file. Now the state of the Disabled key is stored
                       elsewhere on-disk.

              -S sessiontype
                       Some jobs only make sense in certain contexts. This
                       flag instructs launchctl to look for jobs in a differ-
                       ent location when using the -D flag, and allows
                       launchctl to restrict which jobs are loaded into which
                       session types. Currently known session types include:
                       Aqua, LoginWindow, Background, StandardIO and System.

              -D domain
                       Look for plist(5) files ending in *.plist in the domain
                       given. Valid domains include "system," "local," "net-
                       work" 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 /Sys-
                       tem/Library/LaunchDaemons.  With a session type passed,
                       it would load from /System/Library/LaunchAgents.

     submit -l label [-p executable] [-o path] [-e path] -- command [args]
              A simple way of submitting a program to run without a configura-
              tion file. This mechanism also tells launchd to keep the program
              alive in the event of failure.

              -l label
                       What unique label to assign this job to launchd.

              -p program
                       What program to really execute, regardless of what fol-
                       lows the -- in the submit sub-command.

              -o path  Where to send the stdout of the program.

              -e path  Where to send the stderr of the program.

     remove job_label
              Remove the job from launchd by label.

     start job_label
              Start the specified job by label. The expected use of this sub-
              command is for debugging and testing so that one can manually
              kick-start an on-demand server.

     stop 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.

     list [-x] [label]
              With no arguments, list all of the jobs loaded into launchd in
              three columns. The first column displays the PID of the job if
              it is running.  The second column displays the last exit status
              of the job. If the number in this column is negative, it repre-
              sents the negative of the signal which killed the job.  Thus,
              "-15" would indicate that the job was terminated with SIGTERM.
              The third column is the job's label.

              Note that you may see some jobs in the list whose labels are in
              the style "0xdeadbeef.anonymous.program".  These are jobs which
              are not managed by launchd, but, at one point, made a request to
              it.  launchd claims no ownership and makes no guarantees regard-
              ing these jobs. They are stored purely for bookkeeping purposes.

              Similarly, you may see labels of the style "0xdead-
              beef.mach_init.program". These are legacy jobs that run under
              mach_init emulation. This mechanism will be removed in future
              versions, and all remaining mach_init jobs should be converted
              over to launchd.

              If [label] is specified, prints information about the requested
              job. If [-x] is specified, the information for the specified job
              is output as an XML property list.

     setenv key value
              Set an environmental variable inside of launchd.

     unsetenv key
              Unset an environmental variable inside of launchd.

     getenv key
              Get an environmental variable inside of launchd.

     export   Export all of the environmental variables of launchd for use in
              a shell eval statement.

     getrusage self | children
              Get the resource utilization statistics for launchd or the chil-
              dren of launchd.

     log [level loglevel] [only | mask loglevels...]
              Get and set the syslog(3) log level mask. The available log lev-
              els are: debug, info, notice, warning, error, critical, alert
              and emergency.

     limit [cpu | filesize | data | stack | core | rss | memlock | maxproc |
              maxfiles] [both [soft | hard]]
              With no arguments, this command prints all the resource limits
              of launchd as found via 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 setrlimit(2).

     shutdown
              Tell launchd to prepare for shutdown by removing all jobs.

     umask [newmask]
              Get or optionally set the umask(2) of launchd.

     bslist [PID | ..] [-j]
              This prints out Mach bootstrap services and their respective
              states. While the namespace appears flat, it is in fact hierar-
              chical, 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").

              If [PID] is specified, print the Mach bootstrap services avail-
              able to that PID. If [..] is specified, print the Mach bootstrap
              services available in the parent of the current bootstrap. Note
              that in Mac OS X v10.6, the per-user Mach bootstrap namespace is
              flat, so you will only see a different set of services in a per-
              user bootstrap if you are in an explicitly-created bootstrap
              subset.

              If [-j] is specified, each service name will be followed by the
              name of the job which registered it.

     bsexec PID command [args]
              This executes the given command in the same Mach bootstrap
              namespace hierachy as the given PID.

     bstree [-j]
              This prints a hierarchical view of the entire Mach bootstrap
              tree. If [-j] is specified, each service name will be followed
              by the name of the job which registered it.  Requires root priv-
              ileges.

     managerpid
              This prints the PID of the launchd which manages the current
              bootstrap.

     manageruid
              This prints the UID of the launchd which manages the current
              bootstrap.

     managername
              This prints the name of the launchd job manager which manages
              the current bootstrap.  See LimitLoadToSessionType in
              launchd.plist(5) for more details.

     help     Print out a quick usage statement.


ENVIRONMENTAL VARIABLES

     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.


FILES

     ~/Library/LaunchAgents         Per-user agents provided by the user.
     /Library/LaunchAgents          Per-user agents provided by the adminis-
                                    trator.
     /Library/LaunchDaemons         System wide daemons provided by the admin-
                                    istrator.
     /System/Library/LaunchAgents   Mac OS X Per-user agents.
     /System/Library/LaunchDaemons  Mac OS X System wide daemons.


SEE ALSO

     launchd.plist(5), launchd.conf(5), launchd(8)

Darwin                            1 May, 2009                           Darwin

Mac OS X 10.6 - Generated Thu Sep 17 20:07:58 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.