macOS には「決まった時刻にスクリプトを動かす」「ログイン時にプログラムを起動する」「常駐させて動かし続ける」みたいな処理を受け持つ launchd という仕組みが最初から入っている。この launchd に「いつ・何を・どう動かすか」を伝えて操作するためのコマンドが launchctl。設定は plist という XML ファイルに書く。

Linux の cron や systemd に近い役割で、macOS ではその両方を launchd がまとめて引き受けてる。自分で使ってたら、わかりにくい挙動でいくつか詰まった。なので launchd の基本から実際に詰まったところまで、ここに書き残しておく。

この記事の内容は macOS Sequoia 15.7.7 で動作を確認している。

launchctl と launchd とは

launchd は macOS の起動時に最初に立ち上がる、すべてのプロセスの親にあたる管理プロセス。システムの起動処理・常駐サービス(デーモン)の管理・ログインしたときのアプリ起動・定期実行のスケジューリングなどを一手に受け持っている。普段は意識しないが、Mac の中で動いてるバックグラウンド処理の多くはこの launchd が面倒を見ている。

launchctl はその launchd に「このジョブを登録して」「今すぐ動かして」「状態を見せて」と指示を出すためのコマンドラインツール。自分でジョブを足したいときは、やりたいことを plist ファイルに書いて launchctl で launchd へ登録する流れになる。

cron との違いも押さえておくといい。cron は「定期実行」に特化しているが、launchd は定期実行のほかにも「ログイン時に1回だけ実行」「落ちたら再起動して常駐」「特定フォルダが変化したら実行」など、起動のきっかけを幅広く指定できる。ログの出力先や環境変数も plist にまとめて書けるので、cron より記述は少し多い。その分こまかく制御できる。

LaunchAgent か LaunchDaemon か

launchd で動かすジョブには LaunchAgent と LaunchDaemon の 2 種類がある。どちらにするかで「いつ・誰の権限で動くか」が変わる。最初はここでつまずきやすいので先に整理しておく。

種類 動くタイミング 実行権限 向いている用途
LaunchAgent ユーザーがログインしている間 ログインユーザー 個人の定期処理、GUI を伴う処理、通知
LaunchDaemon OS 起動時から(ログイン不要) root(システム) 常駐サービス、全ユーザー共通の処理

個人で「毎日この時刻にスクリプトを回したい」くらいなら、とりあえず LaunchAgent を選んでおけばいい。誰も画面にログインしていなくても動かしたい・root 権限が要る、といったときに LaunchDaemon を考える。置き場所もこの種類で変わる(後述の配置場所を参照)。

plist の基本構造

plist(Property List)は macOS の設定ファイルの形式で、launchd の設定も XML 形式の plist で書く。中身は <key>(項目名)とその値(<string> や <integer> など)のペアを <dict>(辞書)の中に並べていく形。次の例はよく使う項目をひととおり入れたもので、各行にコメントで意味を書いてある。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- ジョブを識別する一意な名前(必須) -->
    <key>Label</key>
    <string>com.example.myjob</string>

    <!-- 実行するコマンドと引数。1要素目が実行ファイル -->
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/my-script.sh</string>
        <string>--option</string>
        <string>value</string>
    </array>

    <!-- 実行スケジュール(毎日9時0分) -->
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>

    <!-- 実行時のカレントディレクトリ -->
    <key>WorkingDirectory</key>
    <string>/usr/local/var/myjob</string>

    <!-- 環境変数を渡す -->
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>

    <!-- 標準出力・標準エラーの書き出し先 -->
    <key>StandardOutPath</key>
    <string>/tmp/myjob.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/myjob.err</string>
</dict>
</plist>

値の型はタグで書き分ける。文字列は <string>、整数は <integer>、真偽値は <true/> / <false/>、複数の値を並べる配列は <array>、入れ子の辞書は <dict> を使う。型を間違える(たとえば数値を <string> で書く)と読み込みに失敗するので、後述の plutil -lint で必ず確認しておく。

plist で使えるキー一覧(取りうる値)

launchd の plist で指定できる主なキーをまとめておく。実際は Label と ProgramArguments(または Program)さえあれば動くので、残りは必要になったら足していけばいい。

必ず/よく使うキー

キー 型 説明
Label 文字列 ジョブの一意な識別子(必須)。ほかと重ならなければどんな文字列でもいいが、慣習では逆ドメイン形式(com.example.myjob)にして plist のファイル名ともそろえる。
ProgramArguments 文字列の配列 実行するコマンドと引数。1 要素目が実行ファイルのパス、2 要素目以降が引数。コマンドは絶対パスで書く。
Program 文字列 実行ファイルのパスだけを指定する簡易版。引数が要らないとき用。ProgramArguments があればそちらが優先される。
RunAtLoad 真偽値 true でロードした瞬間に 1 回実行する。動作確認や起動直後に走らせたい処理に使う。
StartInterval 整数(秒) 指定した秒数ごとに繰り返し実行する。例:3600 で 1 時間ごと。
StartCalendarInterval 辞書 / 配列 cron のように時刻・曜日を指定して実行する。詳細は次節。
StandardOutPath 文字列 標準出力(コマンドの通常の出力)を書き出すファイルパス。
StandardErrorPath 文字列 標準エラー(エラーメッセージ)を書き出すファイルパス。失敗したときの原因を調べるのに使うので入れておくといい。
WorkingDirectory 文字列 スクリプトを実行するときのカレントディレクトリ。相対パスを扱うスクリプトで重要。
EnvironmentVariables 辞書 ジョブに渡す環境変数。launchd 経由では PATH が最小限になりがちなので、必要なら明示する。

起動制御・常駐に使うキー

キー 型 説明
KeepAlive 真偽値 / 辞書 true でプロセスが終了するたびに再起動(常駐用)。辞書で条件を絞れる(後述)。
Disabled 真偽値 true でジョブを無効化。load しても起動しない。
LaunchOnlyOnce 真偽値 true で一度しか実行しない。マシンを再起動しないと安全に起動し直せないジョブ向け。
ThrottleInterval 整数(秒) 連続再起動の最小間隔。デフォルトは 10 秒。短時間で何度も落ちるジョブの暴走を防ぐ。
ExitTimeOut 整数(秒) 停止シグナルを送ってから強制終了するまでの猶予。デフォルト値はシステム側で決まっていて、man に秒数は書かれていない。
ProcessType 文字列 スケジューラ上の優先度。Background / Standard / Adaptive / Interactive のいずれか。重い処理は Background にする。
Nice 整数(-20〜20) プロセスの nice 値(CPU 優先度)。数値が小さいほど優先される。
WatchPaths 文字列の配列 指定したパス(ファイル / フォルダ)に変更があると実行する。
QueueDirectories 文字列の配列 指定ディレクトリにファイルが存在する間、実行を繰り返す。フォルダ監視処理に使う。
StartOnMount 真偽値 true で、ボリュームがマウントされるたびに実行する。
UserName / GroupName 文字列 実行するユーザー / グループ。主に LaunchDaemon で「root 以外で動かしたい」ときに使う。
RootDirectory 文字列 chroot して実行するルートディレクトリ。
AbandonProcessGroup 真偽値 true で、親プロセス終了時に子プロセスを道連れにせず残す。

StartCalendarInterval で時刻を指定する

定期実行でいちばん使うのが StartCalendarInterval。中に時刻や曜日のフィールドを書いておくと、指定したフィールドが一致したときに実行される。書かなかったフィールドはワイルドカード(毎回マッチ)扱い。たとえば Minute だけ書けば「毎時その分」、Hour と Minute を書けば「毎日その時刻」になる。

各フィールドの取りうる値はこう。

フィールド 取りうる値 意味
Minute0〜59分
Hour0〜23時(24時間制)
Day1〜31日(月の中の日付)
Weekday0〜7曜日。0 と 7 が日曜、1=月曜 … 6=土曜
Month1〜12月

複数の時刻に実行したいときは、StartCalendarInterval を辞書ではなく辞書の配列にして並べる。単に「一定間隔ごと」でいいなら StartInterval(秒数)のほうが手軽。

<!-- 毎日 AM 9:30 -->
<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key><integer>9</integer>
    <key>Minute</key><integer>30</integer>
</dict>

<!-- 毎週月曜 AM 10:00(Weekday は 0/7=日曜, 1=月曜 … 6=土曜) -->
<key>StartCalendarInterval</key>
<dict>
    <key>Weekday</key><integer>1</integer>
    <key>Hour</key><integer>10</integer>
    <key>Minute</key><integer>0</integer>
</dict>

<!-- 毎月1日 AM 0:00 -->
<key>StartCalendarInterval</key>
<dict>
    <key>Day</key><integer>1</integer>
    <key>Hour</key><integer>0</integer>
    <key>Minute</key><integer>0</integer>
</dict>

<!-- 1日に複数回(配列で並べる。9時と18時) -->
<key>StartCalendarInterval</key>
<array>
    <dict>
        <key>Hour</key><integer>9</integer>
        <key>Minute</key><integer>0</integer>
    </dict>
    <dict>
        <key>Hour</key><integer>18</integer>
        <key>Minute</key><integer>0</integer>
    </dict>
</array>

<!-- 一定間隔で繰り返す(StartInterval は秒数。3600=1時間ごと) -->
<key>StartInterval</key>
<integer>3600</integer>

注意:Mac がスリープしている時刻に予定があった場合、その回は飛ばされず次に起きたタイミングで実行される(スリープ中の回を飛ばす cron とはここが違う)。スリープ中に何回分も過ぎていたら、起きたときに 1 回だけまとめて走る。ちなみに StartInterval のほうはスリープ中の回が飛ばされる。

常駐させたいなら KeepAlive

「スクリプトを動かし続けたい」「落ちても自動で立ち上げ直したい」という常駐の用途には KeepAlive を使う。true にするとプロセスが終了するたびに launchd が再起動してくれる。条件を絞りたいときは辞書で書く。

<!-- プロセスが落ちたら自動で再起動する(常駐用) -->
<key>KeepAlive</key>
<true/>

<!-- 条件つきの再起動(異常終了したときだけ再起動する) -->
<key>KeepAlive</key>
<dict>
    <key>SuccessfulExit</key>
    <false/>
</dict>

辞書で指定できる主な条件キーは次のとおり。

サブキー 型 意味
SuccessfulExit 真偽値 true なら正常終了(終了コード 0)したときだけ再起動、false なら異常終了したときだけ再起動。
Crashed 真偽値 true でクラッシュ時に再起動する。
NetworkState 真偽値 今の launchd では実装されていない。指定しても効かない。
PathState 辞書 指定したパスが存在する/しない状態に応じて起動を制御する。

plist はどこに置くか

plist を置くディレクトリで、ジョブの種類(LaunchAgent / LaunchDaemon)と、誰の権限でいつから動くかが決まる。個人で使うなら ~/Library/LaunchAgents/ に置くのが基本。

ディレクトリ 種類 対象 実行ユーザー
~/Library/LaunchAgents/ Agent そのユーザーがログイン中 ログインユーザー
/Library/LaunchAgents/ Agent 全ユーザー(要管理者権限) ログインユーザー
/Library/LaunchDaemons/ Daemon システム全体(起動時から) root
/System/Library/... — macOS 組み込み(触らない) —

/System/Library/ 以下は OS 標準のジョブが入ってる場所なので、自分のジョブを置いたり中身を書き換えたりはしない。自作のものは ~/Library/LaunchAgents/ か、root で動かしたいときだけ /Library/LaunchDaemons/ に置く。

はじめてのジョブを動かしてみる

まずは確実に動く最小構成で一度通してみると理解が早い。次の plist を ~/Library/LaunchAgents/com.example.hello.plist として保存する。ロードした瞬間に /bin/echo を 1 回実行して、結果を /tmp/hello.log に書き出すだけのジョブ。

フォルダがなければ mkdir -p ~/Library/LaunchAgents で作っておく。それから nano ~/Library/LaunchAgents/com.example.hello.plist(または VS Code など好きなエディタ)でファイルを作って、次の内容を貼り付けて保存する。特別なツールはいらない。ただのテキストファイルとして書けばいい。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.hello</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/echo</string>
        <string>hello launchd</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/tmp/hello.log</string>
</dict>
</plist>

保存したら、この流れで動くか確かめる。

# 1) フォルダが無ければ作る
mkdir -p ~/Library/LaunchAgents

# 2) 上の最小plistを com.example.hello.plist として保存
#    (Label と同じ名前にするのが慣習)

# 3) 文法チェック(OK が出れば書式は正しい)
plutil -lint ~/Library/LaunchAgents/com.example.hello.plist

# 4) ロード(RunAtLoad が true なのでロード時に1回実行される)
launchctl load ~/Library/LaunchAgents/com.example.hello.plist

# 5) 結果を確認
cat /tmp/hello.log

# 6) 後片付け(登録を解除する)
launchctl unload ~/Library/LaunchAgents/com.example.hello.plist

launchctl load は成功しても何も表示しない(無言で終わる)。エラーが出ていなければ登録はできているので、/tmp/hello.log に行が追記されているか見る。書き込まれていれば成功。ここまで通せたら、あとは ProgramArguments を自分のスクリプトに、RunAtLoad を StartCalendarInterval に置き換えていくだけで定期実行にできる。

基本コマンド(load / unload / list)

plist を置いたら launchctl で launchd に登録(ロード)する。登録を外すのがアンロード。状態の確認や手動での実行もこのコマンドからできる。

# ロード(plistをlaunchdに登録する)
launchctl load ~/Library/LaunchAgents/com.example.myjob.plist

# アンロード(登録を解除する)
launchctl unload ~/Library/LaunchAgents/com.example.myjob.plist

# 登録済みジョブの一覧を見る
launchctl list

# Label でしぼり込む
launchctl list | grep com.example

# スケジュールを待たずに今すぐ実行する
launchctl start com.example.myjob

# 実行中のジョブを止める
launchctl stop com.example.myjob

plist を編集したときは、一度 unload してから load し直さないと変更が反映されないので注意。中身を書き換えただけだと launchd は古い設定のまま動き続ける。

bootstrap / bootout にはドメインを渡す

macOS 10.10 Yosemite 以降は、load / unload に代わる新しいコマンドとして bootstrap / bootout が用意されている。今の macOS ではこっちが推奨で、後述の SSH 経由の操作でも必要になる。

新しいコマンドの肝は「ドメイン」という考え方。launchd はジョブを属する場所(セッション)ごとに分けて管理していて、操作するときはどのドメインかを明示する。よく使うのは次の 2 つ。

  • gui/<uid> … GUI でログイン中のユーザーセッション。LaunchAgent はここ。<uid> は id -u で出てくる数値。
  • system … システム全体。LaunchDaemon はここ。
# bootstrap(load に相当・ドメインを明示する)
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.myjob.plist

# bootout(unload に相当)
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.example.myjob.plist

# ジョブの詳細な状態を見る(終了コード・実行状況など)
launchctl print gui/$(id -u)/com.example.myjob

# 今すぐ実行する(再起動つき)
launchctl kickstart -k gui/$(id -u)/com.example.myjob

kickstart -k はジョブを今すぐ起動するコマンド。-k を付けると、実行中なら一度止めてから起動し直す。動作確認のときに便利。

⚠️ Desktop に置いたスクリプトが動かない

ここからは実際に動かしてハマったところ。まず plist の ProgramArguments に ~/Desktop 配下のスクリプトを指定すると、ロードはエラーなく通るのに、実行される時刻になっても何も起きないことがある。エラーも出ないので原因がわかりにくい。

<!-- ~/Desktop のスクリプトを呼び出す例 -->
<!-- ロードは成功するのに、実行されない/エラーも出ない -->
<key>ProgramArguments</key>
<array>
    <string>/Users/username/Desktop/myscript.sh</string>
</array>

原因は macOS Catalina(10.15)以降の TCC(Transparency, Consent, and Control)によるサンドボックス保護。~/Desktop・~/Documents・~/Downloads はアクセスに明示的な許可が要る保護対象のフォルダになっていて、GUI セッションの外で動く launchd はそのままだとここを読めない。なので Operation not permitted になるか、何も出ずに静かに失敗する。

「システム設定 → プライバシーとセキュリティ → フルディスクアクセス」に launchctl や launchd を足しても解決しない。確実なのは、plist が指すスクリプト本体を保護対象外のディレクトリ(~/bin など)に移すこと。

# 避けるべき場所(TCC の保護対象)
~/Desktop/myscript.sh
~/Documents/myscript.sh
~/Downloads/myscript.sh

# スクリプトを保護対象外へ移す
mkdir -p ~/bin
mv ~/Desktop/myscript.sh ~/bin/myscript.sh
chmod +x ~/bin/myscript.sh

# plist 側のパスも書き換える
<key>ProgramArguments</key>
<array>
    <string>/Users/username/bin/myscript.sh</string>
</array>

ダメなのは実行ファイルの置き場所だけ

ここがいちばんわかりにくいところ。「Desktop が絡むと何もかも動かない」と思いがちだけど、実際にダメなのは launchd が直接起動する実行ファイル(plist の ProgramArguments が指すスクリプト本体)が保護フォルダにある場合だけ。スクリプトが 処理対象として読み書きするデータファイル が ~/Desktop 配下にあること自体は問題ない。

理由は止まる場所が違うから。前者は launchd がスクリプトを起動する「入口」で保護に阻まれて、プロセスが起動すらできない。後者はスクリプト本体が保護外にあるので起動は成功する。そのあと起動したプロセスが(LaunchAgent ならユーザーのログインセッション内・ユーザー権限で動くので)Desktop のファイルを読み書きするのは通る。

構成 結果 理由
plist が指す実行ファイル本体が ~/Desktop 配下 ✗ 起動できない launchd が保護フォルダの実行ファイルを起動する入口で阻まれる(無言で失敗)
実行ファイルは保護外(~/bin 等)・処理対象データが ~/Desktop 配下 ✓ 動く 起動は保護外なので成功し、その後のデータ読み書きはユーザー権限(LaunchAgent)で通る
# OK な構成:実行ファイルは保護外、処理対象データは Desktop 配下でもよい
~/bin/backup.sh            # ← launchd が起動するスクリプト本体(保護外に置く)

# backup.sh の中身(処理対象のデータは ~/Desktop でも動く)
#!/bin/bash
ls ~/Desktop/*.csv >> /tmp/backup.log   # Desktop のファイルを読む処理は通る

# plist が指すのは「スクリプト本体」。ここが保護外なら起動できる
<key>ProgramArguments</key>
<array>
    <string>/Users/username/bin/backup.sh</string>
</array>

補足:後者でも TCC が厳しい環境やフルディスクアクセスを許可していない場合は、データ側のアクセスが Operation not permitted で拒否されることがある。そのときは「システム設定 → プライバシーとセキュリティ → フルディスクアクセス」で、スクリプトを動かす実体(ターミナルや /bin/bash など)を許可すると通るようになる。ちなみに LaunchDaemon(root 実行)はユーザーの Desktop への権限がないので、この構成でもデータ側で弾かれやすい。

⚠️ SSH 越しだと load がうまくいかない

SSH 経由の操作でもハマった。SSH でリモートログインした状態で launchctl load を実行すると、手元のターミナルとは違う結果になることがある。

$ launchctl load ~/Library/LaunchAgents/com.example.myjob.plist
# → "Could not find domain for this service"
# → "Bootstrap failed: 5: Input/output error"
# → 何も起きない(無言で失敗)

これには前述のドメインが関係してる。GUI ログインのセッションは gui/<uid>、SSH のセッションは user/<uid> という別のドメインで、LaunchAgent は GUI セッション側に属している。SSH のドメインからは GUI 側のジョブをそのまま操作できないので、対象が見つからずエラーになる。

SSH から操作するときは、bootstrap / bootout / print に gui/<uid> を明示して渡す。手元のターミナルで使ってた load をそのまま SSH 越しに打つとハマる。SSH のときは新しいコマンド+ドメイン指定に切り替える、と覚えておけばいい。

# 自分の UID を確認する
id -u   # → 例: 501

# bootstrap / bootout は gui/<uid> ドメインを明示する
launchctl bootstrap gui/501 ~/Library/LaunchAgents/com.example.myjob.plist
launchctl bootout gui/501 ~/Library/LaunchAgents/com.example.myjob.plist

# 状態確認
launchctl print gui/501/com.example.myjob

# 今すぐ実行
launchctl kickstart -k gui/501/com.example.myjob

# それでも動かないとき:GUI セッションが存在するか確認する
who   # ログイン中のセッション一覧(console 行があれば GUI ログイン中)

それでも動かないときは、そもそも GUI セッションがない(誰も画面にログインしていない)のかもしれない。その場合は素直に LaunchDaemon(/Library/LaunchDaemons/ に置いて sudo launchctl bootstrap system ...)として root 権限で動かすほうが確実。

動かないときの調べ方

想定どおり動かないときはまず plutil -lint で plist の文法を確認して、次に launchctl list の終了コードを見る。もっと追うなら launchctl print で詳細を、log コマンドで launchd まわりのログを見る。

# plist の文法チェック(まずこれ)
plutil -lint ~/Library/LaunchAgents/com.example.myjob.plist
# → OK: /Users/.../com.example.myjob.plist: OK

# 登録状態と終了コードを見る
launchctl list | grep com.example
# → -    78    com.example.myjob   ← 78 = エラーあり
# → -    0     com.example.myjob   ← 0  = 正常終了
# → 501  -     com.example.myjob   ← 数字 = 実行中の PID

# ジョブの詳細(最後の終了コード・パスなど)
launchctl print gui/$(id -u)/com.example.myjob

# launchd 関連のログをリアルタイムで見る
log stream --predicate 'subsystem == "com.apple.launchd"' --level debug

# 過去ログをさかのぼる(スクリプト名で絞り込み)
log show --predicate 'processImagePath contains "myscript"' --last 1h

launchctl list の出力は左から「PID・最後の終了コード・Label」の順。終了コードの主なものはこんな感じ。

終了コード 意味
0正常終了
1一般的なエラー
78設定エラー(plist の記述ミスが多い)
127コマンド・スクリプトが見つからない(パスの誤り)

TCC・Desktop 問題などの権限エラーは終了コードではなく、エラー出力の Operation not permitted というメッセージで出る(前述)。

つまずきやすいところ

  • plist を書き換えただけでは反映されない。unload → load(または bootout → bootstrap)でロードし直す。
  • 「ロード成功」と出ても、スクリプト本体が保護フォルダ(Desktop など)にあると静かに失敗する。エラーが出ないぶん気づきにくい。
  • plist 内のパスでは ~ が展開されない。~/bin/x.sh ではなく /Users/ユーザー名/bin/x.sh のように絶対パスで書く。
  • コマンドやスクリプトは絶対パスで書く。launchd 経由では PATH が最小限なので、python のような名前だけの指定は見つからないことがある。
  • SSH からは gui/<uid> を明示しないと操作できない。ローカルで動いたコマンドをそのまま持ち込むとハマる。
  • StartCalendarInterval はフィールドを書かないと「毎回」扱いになる。Minute を書き忘れると毎分実行になってしまうので注意。

正式な仕様は man ページで

各キーの仕様やこの記事で触れていないオプションを確かめたいときは、macOS に入っている man ページが一次情報として確実。ターミナルで次を実行すれば、その環境の launchd に合った正確な内容が読める。

man launchctl       # launchctl コマンドのリファレンス
man launchd.plist   # plist で指定できるキーの正式な仕様(型・取りうる値)
man launchd         # launchd 本体の説明

特に man launchd.plist には、この記事の「plist で使えるキー一覧」で挙げた各キーの型・取りうる値・デフォルトの挙動がきちんと書かれている。記事と挙動が食い違うときは、手元の環境の man ページを優先してほしい。