// Copyright 2014 The Crashpad Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

:doctype: manpage

= on_demand_service_tool(1)

== Name

on_demand_service_tool - Load and unload on-demand Mach services registered with
launchd(8)

== Synopsis

[verse]
*on_demand_service_tool* *-L* *-l* 'LABEL' ['OPTION…'] 'COMMAND' ['ARG…']
*on_demand_service_tool* *-U* *-l* 'LABEL'

== Description

On-demand services may be registered with launchd(8) by using the *--load* form.
One or more service names may be registered with the bootstrap server by
specifying *--mach-service*. When a Mach message is sent to any of these
services, launchd(8) will invoke 'COMMAND' along with any arguments specified
('ARG…'). 'COMMAND' must be an absolute pathname.

The *--unload* form unregisters jobs registered with launchd(8).

== Options

*-L*, *--load*::
Registers a job with launchd(8). *--label*='LABEL' and 'COMMAND' are required.
This operation may also be referred to as “load” or “submit”.

*-U*, *--unload*::
Unregisters a job with launchd(8). *--label*='LABEL' is required. This operation
may also be referred to as “unload” or “remove”.

*-l*, *--label*='LABEL'::
'LABEL' is used as the job label to identify the job to launchd(8). 'LABEL' must
be unique within a launchd(8) context.

*-m*, *--mach-service*='SERVICE'::
In conjunction with *--load*, registers 'SERVICE' with the bootstrap server.
Clients will be able to obtain a send right by looking up the 'SERVICE' name
with the bootstrap server. When a message is sent to such a Mach port,
launchd(8) will invoke 'COMMAND' along with any arguments specified ('ARG…') if
it is not running. This forms the “on-demand” nature referenced by this tool’s
name. This option may appear zero, one, or more times. 'SERVICE' must be unique
within a bootstrap context.

*--help*::
Display help and exit.

*--version*::
Output version information and exit.

== Examples

Registers an on-demand server that will execute man_link:catch_exception_tool[1]
when a Mach message is sent to a Mach port obtained from the bootstrap server by
looking up the name +svc+:
[subs="quotes"]
----
$ *on_demand_service_tool --load --label=catch_exception \
      --mach-service=svc \
      $(which catch_exception_tool) --mach-service=svc \
      --file=/tmp/out --persistent --timeout=0*
----

Unregisters the on-demand server installed above:
[subs="quotes"]
----
$ *on_demand_service_tool --unload --label=catch_exception*
----

== Exit Status

*0*::
Success.

*1*::
Failure, with a message printed to the standard error stream.

== See Also

man_link:catch_exception_tool[1],
man_link:exception_port_tool[1],
launchctl(1)

include::../../doc/support/man_footer.ad[]