launchctl(1)

対象

macOS 26.6.2 (25G83)

構成要素

launchd macOS 26.6.2 system manual

原文

インストール済みmacOSのmanページ

Apple OSS公開版

macOS 26.0（対象macOS版とは別に記録）

名前

launchctl — launchd とのインターフェース

書式

launchctl

subcommand [arguments ...]

説明

launchctl は launchd と連携し、デーモン、エージェント、および XPC サービスを管理、調査します。

サブコマンド

launchctl を使用すると、launchd のデータ構造を詳細に調査できます。基本となる構造は、ドメイン、サービス、およびエンドポイントです。ドメインは、サービス群の実行ポリシーを管理します。サービスは、要求に応じて起動できるよう常に利用可能な仮想プロセスとみなせます。各サービスは複数のエンドポイントを持ち、そのいずれかにメッセージを送ると、サービスがオンデマンドで起動します。ドメインは共有名前空間でこれらのエンドポイントを公開し、Mach ブートストラップのサブセットと同義とみなせます。

launchctl の多くのサブコマンドは、その対象となるドメインまたはサービスを示す指定子を取ります。この指定子には、次のいずれかの形式を使用できます。

system/[service-name]

システムドメイン、またはシステムドメイン内のサービスを対象とします。システムドメインはルート Mach ブートストラップを管理し、特権実行コンテキストとみなされます。システムドメインの読み取りや照会は誰でも行えますが、変更には root 権限が必要です。

user/<uid>/[service-name]

指定した UID のユーザードメイン、またはそのドメイン内のサービスを対象とします。ユーザードメインは、ログイン中のユーザーがいなくても存在する場合があります。iOS にはユーザードメインは存在しません。

login/<asid>/[service-name]

ユーザーログインドメイン、またはそのドメイン内のサービスを対象とします。ユーザーログインドメインは、ユーザーが GUI からログインしたときに作成され、そのログインに関連付けられた監査セッション識別子によって識別されます。ユーザードメインにログインドメインが関連付けられている場合、print サブコマンドはそのログインドメインの ASID を表示します。iOS にはユーザーログインドメインは存在しません。

gui/<uid>/[service-name]

login 指定子の別形式です。ユーザーログインドメインを ASID で指定する代わりに、関連付けられたユーザーに基づいてドメインを対象とするため、一般にはこちらの方が便利です。

Note: GUI ドメインとユーザードメインは多くのリソースを共有します。Mach ブートストラップ名の検索に関しては両者は「フラット」であり、同じ登録名の集合を共有します。ただし、サービスの集合はそれぞれ独立しています。そのため、ユーザードメインの内容を表示すると、そのユーザーの GUI ドメインに存在するサービスによる Mach ブートストラップ名の登録が多数表示されることがありますが、その一覧にサービス自体は表示されません。

pid/<pid>/[service-name]

指定した PID のドメイン、またはそのドメイン内のサービスを対象とします。システム上の各プロセスには、そのプロセスから見え、xpc_connection_create(3) で到達できる XPC サービスで構成される PID ドメインが関連付けられます。

たとえば、UID 501 のユーザーの GUI ドメインに読み込まれた、識別子 com.apple.example のサービスを参照する場合、domain-target は gui/501/、service-name は com.apple.example、service-target は gui/501/com.apple.example です。

サブコマンド

bootstrap | bootout domain-target [service-path service-path2 ...] | service-target

ドメインおよびサービスをブートストラップ、または削除します。サービス引数がある場合は、その定義をドメインにブートストラップし、対応する定義をドメインから削除します。サービスは、一連のパスまたはサービス識別子で指定できます。パスには、XPC サービスバンドル、launchd.plist(5)、またはそのいずれかを集めたディレクトリを指定できます。サービス群のブートストラップまたは削除中にエラーが 1 件以上発生した場合、問題のあるパスが発生したエラーとともに表示されます。

パスもサービスターゲットも指定しない場合、これらのコマンドはドメインターゲットとして指定されたドメインをブートストラップまたは削除できます。一部のドメインは、作成処理の一部として事前定義済みのパスを暗黙にブートストラップします。

enable | disable service-target

要求されたドメイン内のサービスを有効または無効にします。サービスを無効にすると、再び有効にするまで、指定したドメインには読み込めません。この状態はデバイスを再起動しても維持されます。このサブコマンドが対象にできるのは、システムドメイン、ユーザードメイン、またはユーザーログインドメイン内のサービスだけです。

kickstart [-kp] service-target

設定された起動条件にかかわらず、指定したサービスを直ちに実行するよう launchd に指示します。

-k

サービスがすでに実行中の場合は、サービスを再起動する前に実行中のインスタンスを終了します。

-p

成功すると、新しいプロセスまたはすでに実行中のプロセスの PID を標準出力に表示します。

attach [-ksx] service-target

指定したサービスの実体として現在動作しているプロセスに、システムのデバッガをアタッチします。デフォルトでは、サービスが実行されていない場合、このサブコマンドはサービスが起動するまでブロックします。

-k

サービスがすでに実行中の場合は、その実行中のインスタンスを終了します。

-s

サービスを強制的に起動します。

-x

xpcproxy(3) が exec を実行してサービスプロセスになる前にアタッチします。このフラグは通常、launchd の保守担当者以外には役立ちません。

debug service-target [--program <program path>] [--guard-malloc] [--malloc-stack-logging] [--debug-libraries] [--introspection-libraries] [--NSZombie] [--32] [--stdin] [--stdout] [--stderr] [--environment] [--] [argv0 argv1 argv2 ...]

サービスの次回の実行をデバッグ用に構成します。このサブコマンドでは、サービスのメイン実行ファイルを別のパスにある実行ファイルへ一時的に置き換えたり、libgmalloc(3) を有効にしたり、環境変数や引数ベクトルなどを設定したりできます。追加したデバッグ用プロパティは、その設定でサービスを 1 回実行すると消去されるため、サービスの launchd.plist(5) を編集して再読み込みするよりも便利です。

--program <program-path>

launchd(8) に program-path as the service's executable. を使用するよう指示します。

--guard-malloc

サービスで libgmalloc(3) を有効にします。

--malloc-stack-logging

サービスで malloc(3) のスタックログを有効にします。

--malloc-nano-allocator

サービスで malloc(3) の nano アロケータを有効にします。

--debug-libraries

サービスの DYLD_IMAGE_SUFFIX を「_debug」に設定します。これにより、ライブラリのデバッグ版が存在する場合はそちらが優先されます。詳細は dyld(1) を参照してください。

--introspection-libraries

サービスの DYLD_LIBRARY_PATH 環境変数に /usr/lib/system/introspection を追加します。これにより、ライブラリのイントロスペクション版が存在する場合は、システムがそちらを優先します。

--NSZombie

NSZombie を有効にします。

--32

サービスを適切な 32 ビットアーキテクチャで実行します。64 ビットプラットフォームでのみ使用できます。

--stdin [stdin-path]

サービスの標準入力を stdin-path に設定します。ファイルを指定しない場合は、現在の端末をサービスの標準入力として使用します。stdin-path が存在しない場合は作成されます。

--stdout [stdout-path]

サービスの標準出力を stdout-path に設定します。ファイルを指定しない場合は、現在の端末をサービスの標準出力として使用します。stdout-path が存在しない場合は作成されます。

--stderr [stderr-path]

サービスの標準エラー出力を stderr-path に設定します。ファイルを指定しない場合は、現在の端末をサービスの標準エラー出力として使用します。stderr-path が存在しない場合は作成されます。

--environment VARIABLE0=value VARIABLE1=value ...

指定した環境変数をサービスに設定します。

-- argv0 argv1 ...

-- より後の引数はすべて、サービスの引数ベクトルとして渡されます。

IMPORTANT: これらの引数はサービスのデフォルト引数ベクトルを置き換えるものであり、いかなる形でもマージされません。-- の直後の最初の引数が、サービスの引数ベクトルの先頭（第 0）要素として渡されます。launchd.plist(5) の ProgramArguments キーと同様に、execve(2) の man ページを注意深く読み、理解しておく必要があります。

kill signal-name | signal-number service-target

指定したサービスが実行中の場合、そのサービスに指定したシグナルを送信します。シグナルは番号または名前（SIGTERM、SIGKILL など）で指定できます。

blame service-target

サービスが実行中の場合、launchd がそのサービスを起動した理由を、人が読める文字列で表示します。サービスが実行される理由は複数あり得ますが、このサブコマンドが表示するのは最も直接的な理由だけであることに注意してください。そのため、タイマーの発火によってサービスが実行された場合、サービスの各種エンドポイントに待機中のメッセージがあったかどうかに関係なく、このサブコマンドはタイマーの発火を理由として表示します。このサブコマンドはデバッグとプロファイリングだけを目的としており、本番環境でその出力に依存してはいけません。

print domain-target | service-target

指定したサービスまたはドメインに関する情報を表示します。ドメインの出力には、ドメインの各種プロパティに加え、ドメイン内のサービスとエンドポイント、およびそれぞれに関係する状態の一覧が含まれます。サービスの出力には、ディスク上の出所、現在の状態、実行コンテキスト、直近の終了ステータスなど、サービスの各種プロパティが含まれます。

IMPORTANT: この出力は、いかなる意味でも API ではありません（NOT）。出力される構造や情報には、どのような理由（ANY）であっても依存してはいけません（NOT）。これらはリリースごとに予告なく変更される可能性があります。

print-cache

launchd のサービスキャッシュの内容を表示します。

print-disabled domain-target

指定したドメインで無効になっているサービスの一覧を表示します。

plist [segment,section] Mach-O

対象の Mach-O の __TEXT,__info_plist セグメント／セクション、または指定したセグメント／セクションに埋め込まれているプロパティリストを表示します。

procinfo pid

指定した PID の実行コンテキストに関する情報を表示します。この情報には、Mach のタスク特殊ポートと例外ポート、監査セッションコンテキストが含まれます。また、DEVELOPMENT 版 launchd に対して実行した場合は、ポートが Mach ブートストラップ名前空間でどの名前として公開されているかも、launchd がその名前を認識していれば表示されます。このサブコマンドは診断だけを目的としており、本番環境でその出力に依存してはいけません。このコマンドには root 権限が必要です。

hostinfo

ホスト例外ポートを含む、システムのホスト特殊ポートに関する情報を表示します。このサブコマンドには root 権限が必要です。

resolveport owner-pid port-name

PID と、そのプロセスのポート名前空間にある Mach ポート権の名前を指定すると、そのポートを launchd が認識しているエンドポイント名に解決します。このサブコマンドには root 権限が必要です。

examine [tool arg0 arg1 @PID ...]

プロファイリングツールで調査できるように、launchd 自身に fork(2) を実行させ、この新しいインスタンスの PID を標準出力に表示します。このスナップショットが不要になったら、利用者が終了させる必要があります。

多くのプロファイリングツールは、launchd が提供する機能に依存しているため、そのデーモンを安全に調査できません。このサブコマンドは、独立して調査できる launchd の実質的なスナップショットを作成します。Darwin プラットフォームでは、fork(2) は fork(2) を呼び出したスレッドだけが新しい子プロセスに複製されるよう実装されています。そのため、このサブコマンドはメインイベントループ以外のスレッドの調査には役立ちません。

このサブコマンドには、launchd のスナップショットに対して使用するツールの呼び出しを任意で指定できます。通常ならツールの呼び出しで調査対象プロセスの PID を指定する箇所に、代わりに引数「@PID」を指定すると、launchctl は後でツールを実行する際に、その引数を launchd スナップショットの PID に置き換えます。この形式で使用した場合、調査ツールが終了すると launchctl がスナップショットのインスタンスを自動的に終了します。

このサブコマンドは DEVELOPMENT 版の launchd に対してのみ使用できます。

config system | user parameter value

launchd(8) ドメインの永続的な設定情報を設定します。設定できるのはシステムドメインとユーザードメインだけです。永続ストレージの場所は実装の詳細であり、そのストレージへの変更は必ずこのサブコマンドを介して行うべきです（only）。このサブコマンドによる変更を有効にするには再起動が必要です。

サポートされる設定パラメータは次のとおりです。

umask

対象ドメイン内のサービスの umask(2) を、value で指定した値に設定します。この値は strtoul(3) によって 8 進数として解析されるため、先頭に「0」を付ける必要はありません。

path

対象ドメイン内のすべてのサービスについて、PATH 環境変数を文字列 value に設定します。文字列 value は、environ(7) で説明されている PATH 環境変数の形式に従う必要があります。サービスが独自の PATH を指定している場合は、サービス固有の環境変数が優先されることに注意してください。

NOTE: この機能を使用して、ドメイン内のすべてのサービスに汎用の環境変数を設定することはできません。セキュリティ上の理由から、意図的に PATH 環境変数だけが対象とされており、それ以外は設定できません。

reboot [system|userspace|halt|logout|apps]

ユーザー空間の終了処理を開始するよう launchd に指示します。引数を指定しない場合、または system 引数を指定した場合、ユーザー空間が完全に終了した時点で launchd が reboot(2) システムコールを実行します。halt 引数を指定した場合は、ユーザー空間が完全に終了した時点で launchd が reboot(2) システムコールを RB_HALT フラグ付きで実行し、再起動を開始せずにシステムを停止します。

userspace 引数を指定した場合、ユーザー空間の終了後に launchd が自身を再 exec し、ユーザー空間を再び起動します。これは、カーネルのデータ構造やハードウェアを再初期化する必要がない状況で、システムをすばやく再起動するのに役立ちます。

logout 引数を指定すると、launchd は Apple メニューから開始するログアウトと同様の方法で、呼び出し元の GUI ログインセッションを終了します。主な違いは、このサブコマンドから開始したログアウトでは、アプリがモーダルダイアログを表示してログアウトを無期限に妨げる機会を与えないため、処理が大幅に速いことです。そのため、このオプションの使用にはデータ破損のリスクがあります。実行中のアプリに未保存のデータがないと分かっている場合にのみ使用してください。

apps 引数を指定すると、launchd は呼び出し元の GUI ログインセッションで実行中のアプリのうち、ディスク上の launchd.plist(5) から起動されたものではないアプリをすべて終了します。Finder、Dock、SystemUIServer などのアプリには影響しません。アプリは logout 引数の場合と同じ方法で終了され、同じ注意事項がすべて適用されます。

error [posix|mach|bootstrap] code

指定したエラー code を人が読める文字列で表示します。デフォルトでは、launchctl は指定されたコードがどのエラードメインに属するかを推測します。呼び出し元は、指定したコードをどのサブシステムのエラーとして解釈するか、ドメイン（posix、mach、bootstrap のいずれか）を任意で指定できます。

variant

システムで現在有効な launchd のバリアントを表示します。バリアントには RELEASE、DEVELOPMENT、DEBUG があります。

version

launchd のバージョン文字列を表示します。

旧式のサブコマンド

旧式のサブコマンドは、root として実行されているかどうかに基づいて対象ドメインを選択します。root として実行した場合は、システムドメインを対象とします。

load | unload [-wF] [-S sessiontype] [-D searchpath] paths ...

推奨される代替サブコマンド: bootstrap | bootout | enable | disable

指定した設定ファイル、または設定ファイルを収めたディレクトリを読み込みます。オンデマンドではないジョブは、可能な限り早く起動されます。指定したすべてのジョブが読み込まれるまで、どのジョブも起動を許可されません。ユーザー単位の設定ファイル（LaunchAgents）は、/Library/LaunchAgents にある場合は root が、$HOME/Library/LaunchAgents にある場合はそれを読み込むユーザーが所有していなければなりません。システム全体のデーモン（LaunchDaemons）は、すべて root が所有していなければなりません。設定ファイルは、グループおよびその他のユーザーによる書き込みを許可してはいけません。この制限はセキュリティ上の理由によるものです。launchd の設定ファイルへの書き込みを許すと、起動する実行ファイルを指定できてしまうためです。

/System/Library/LaunchDaemons ディレクトリへの root 以外の書き込みアクセスを許可すると、システムは必ず起動不能になることに注意してください。

-w

Disabled キーを上書きし、load サブコマンドでは false、unload サブコマンドでは true にそれぞれ設定します。以前のバージョンでは、このオプションは設定ファイルを変更していました。現在、Disabled キーの状態はディスク上の別の場所に保存されており、launchd 以外のプロセスがその場所を直接操作することはできません。

-F

plist を強制的に読み込む、または読み込み解除します。Disabled キーは無視されます。

-S sessiontype

一部のジョブは、特定のコンテキストでのみ意味を持ちます。このフラグは、-D フラグの使用時に別の場所でジョブを探すよう launchctl に指示し、どのセッションタイプにどのジョブを読み込むかを launchctl が制限できるようにします。セッションが関係するのは、ユーザー単位の launchd コンテキストだけです。該当するセッションは Aqua（デフォルト）、Background、LoginWindow です。Background エージェントは、GUI ログインとは無関係に読み込めます。Aqua エージェントは、ユーザーが GUI からログインした場合にのみ読み込まれます。LoginWindow エージェントは LoginWindow UI の表示中に読み込まれ、現在は root として実行されます。

-D searchpath

指定した検索パスにあるすべての plist(5) ファイルを読み込む、または読み込み解除します。このオプションは、指定した検索パスに応じて多数の個別パスに展開されるものと考えられます。有効な検索パスには「system」、「local」、「all」があります。セッションタイプを指定する場合は、「user」という追加の検索パスも使用できます。たとえば、セッションタイプを指定せずに「-D system」を指定すると、/System/Library/LaunchDaemons にあるすべてのプロパティリストファイルを読み込むか、読み込み解除します。セッションタイプも渡した場合は、/System/Library/LaunchAgents から読み込みます。launchctl はネットワーク検索パスを使用しなくなったことに注意してください。

以前のバージョンの launchd では、これらの検索パスを「ドメイン」と呼んでいたため、-D という名前になっています。現在、「ドメイン」という語はまったく別の概念に使われています。

NOTE: 以前の実装に存在したバグと、それらのバグを前提とする長年のクライアント側の期待があるため、load および unload サブコマンドが 0 以外の終了コードを返すのは、使用方法が不適切な場合だけです。それ以外では常に 0 を返します。

submit -l label [-p executable] [-o stdout-path] [-e stderr-path] -- command [arg0] [arg1] [...]

設定ファイルを使わず、実行するプログラムを簡単に登録する方法です。この仕組みは、プログラムが失敗した場合にそのプログラムを稼働状態に保つよう launchd にも指示します。

-l label

launchd 内でこのジョブに割り当てる一意なラベルです。

-p program

submit サブコマンドの -- より後に何が指定されていても、実際に実行するプログラムです。

-o stdout-path

プログラムの標準出力の送信先です。

-e stderr-path

プログラムの標準エラー出力の送信先です。

remove label

ラベルを指定して launchd からジョブを削除します。このサブコマンドは直ちに戻り、ジョブが停止するまでブロックしません。

start label

ラベルを指定してジョブを起動します。このサブコマンドは、オンデマンドサーバーを手動で起動できるようにする、デバッグおよびテストでの使用を想定しています。

stop label

ラベルを指定してジョブを停止します。ジョブがオンデマンドの場合、launchd が満たされている起動条件を検出すると、直ちにジョブを再起動することがあります。

list [-x] [label]

推奨される代替サブコマンド: print

引数を指定しない場合、launchd に読み込まれているすべてのジョブを 3 列で一覧表示します。第 1 列には、ジョブが実行中であればその PID が表示されます。第 2 列には、ジョブの直近の終了ステータスが表示されます。この列の数値が負の場合、ジョブを停止させたシグナル番号の負数を表します。したがって「-15」は、ジョブが SIGTERM によって終了したことを示します。第 3 列はジョブのラベルです。[label] を指定すると、要求したジョブに関する情報を表示します。

-x

このフラグは現在サポートされていません。

setenv key value

呼び出し元のコンテキストで、今後 launchd が起動するすべてのプロセスに設定する環境変数を指定します。

unsetenv key

呼び出し元のコンテキストで、今後 launchd が起動するどのプロセスにも設定しない環境変数を指定します。

getenv key

呼び出し元のコンテキストに起動されるすべてのプロセスに対して launchd が設定する環境変数の値を表示します。

export

シェルの eval 文で使用できるように、launchd のすべての環境変数をエクスポートします。

getrusage self | children

launchd、または launchd の子プロセスのリソース使用統計を取得します。このサブコマンドは実装されていません。

limit [cpu | filesize | data | stack | core | rss | memlock | maxproc | maxfiles] [both [soft | hard]]

引数を指定しない場合、このコマンドは getrlimit(2) で取得した launchd のすべてのリソース制限を表示します。リソースを指定した場合は、そのリソースの制限を表示します。第 3 引数を指定した場合は、ハード制限とソフト制限の両方をその値に設定します。4 個の引数を指定した場合、第 3 引数と第 4 引数は、それぞれソフト制限とハード制限を表します。setrlimit(2) を参照してください。

shutdown

すべてのジョブを削除してシャットダウンの準備をするよう launchd に指示します。このサブコマンドは実装されていません。

umask [newmask]

launchd の umask(2) を取得し、任意で設定します。このサブコマンドは実装されていません。

bslist [PID | ..] [-j]

このサブコマンドは実装されておらず、より豊富な情報を提供する print サブコマンドに置き換えられています。

bsexec PID command [args]

指定したコマンドを、対象 PID の実行コンテキストに可能な限り近いコンテキストで実行します。引き継がれる属性には、Mach ブートストラップ名前空間、例外サーバー、およびセキュリティ監査セッションが含まれます。プロセスの資格情報（UID、GID など）は変更せず、対象プロセスの環境変数も引き継ぎません。影響するのは、Mach ブートストラップコンテキストと、それに直接関係する属性だけです。

asuser UID command [args]

指定したコマンドを、対象ユーザーのブートストラップの実行コンテキストに可能な限り近いコンテキストで実行します。引き継がれる属性には、Mach ブートストラップ名前空間、例外サーバー、およびセキュリティ監査セッションが含まれます。プロセスの資格情報（UID、GID など）は変更せず、ユーザー固有の環境変数も引き継ぎません。影響するのは、Mach ブートストラップコンテキストと、それに直接関係する属性だけです。

bstree

このサブコマンドは実装されておらず、より豊富な情報を提供する print サブコマンドに置き換えられています。

managerpid

現在のブートストラップを管理する launchd の PID を表示します。以前の実装では、複数の launchd プロセスがそれぞれ独自の Mach ブートストラップのサブセットを管理することがありました。現在の実装では、すべてのブートストラップを 1 つのプロセスが管理するため、このサブコマンドは常に「1」を表示します。

manageruid

呼び出し元の launchd コンテキストに関連付けられた UID を表示します。

managername

現在の launchd コンテキストを管理する launchd ジョブマネージャーの名前を表示します。詳細については、launchd.plist(5) の LimitLoadToSessionType を参照してください。

help

簡潔な使用方法を表示します。

注意事項

「旧式」のサブコマンド（主に list）が生成する出力は、以前の OS X リリースでの出力と一致するはずです。ただし、新しいサブコマンドの出力は特定の形式に準拠しておらず、リリース間で安定したままである保証はありません。これらのコマンドは、人間である開発者やシステム管理者が使用するためのものであり、プログラムやスクリプトによる自動化を目的としていません。その出力は API を構成するものではなく、出力を解析しようとするプログラムに対して前方互換性は一切保証されません。

非推奨および削除された機能

launchctl には対話モードがなくなり、標準入力からのコマンドも受け付けなくなりました。ブート初期に実行するサブコマンドの取得元として /etc/launchd.conf ファイルが参照されることもなくなりました。この機能はセキュリティ上の配慮から削除されました。ユーザーセッションを設定する前に $HOME/.launchd.conf が参照されると文書化されていましたが、この機能が実装されたことはありません。

launchd は通信に Unix ドメインソケットを使用しなくなったため、LAUNCHD_SOCKET 環境変数はもはや意味を持たず、設定されません。

launchd はネットワークから設定ファイルを読み込まなくなりました。

ファイル

~/Library/LaunchAgents

ユーザーが提供する、ユーザー単位のエージェント。

/Library/LaunchAgents

管理者が提供する、ユーザー単位のエージェント。

/Library/LaunchDaemons

管理者が提供する、システム全体のデーモン。

/System/Library/LaunchAgents

OS X のユーザー単位のエージェント。

/System/Library/LaunchDaemons

OS X のシステム全体のデーモン。

終了ステータス

サブコマンドが成功した場合、launchctl はステータス 0 で終了します。それ以外の場合は、error サブコマンドに渡して人が読める形式に変換できるエラーコードで終了します。

関連項目

launchd.plist(5)、launchd(8)、audit(8)、setaudit_addr(2)