blob: 5db4713fd206620c154edd74aede6408d6919029 [file] [log] [blame]
// 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 tools
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[]