ELF 執行者

ELF 執行元件是負責啟動執行程式的執行元件。這是內建的執行元件，所有元件皆可使用。

使用 ELF Runner

如要使用 ELF 執行元件，元件的資訊清單必須包含 program 區塊，其中包含：

{
    program: {
        runner: "elf",
        binary: "bin/foo",
    }
}
  • runner 欄位，其值設為字串 elf。
  • binary 欄位，其值設為元件套件中的二進位輸出名稱。

欄位

此外，ELF 執行元件會接受一組選用欄位，用於設定 ELF 元件的執行階段環境。

引數

您可以使用 args 欄位，將引數 (即大多數程式設計語言中的 argv) 傳遞至元件的程序。這個欄位可接受字串向量 (請參閱下方範例)。引數集會按照資訊清單中宣告的順序傳遞。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        args: ["--verbose", "--debug"]
    }
}

轉送 stdout 和 stderr 串流

ELF 元件的 stdout 和 stderr 串流可以轉送至 LogSink 服務。根據預設，ELF 執行元件只會在元件可使用 LogSink 時轉送這些串流。如果元件將診斷訊息列印到這兩個串流中，您應將串流轉送至 LogSink 服務。

如要啟用這項功能，請在資訊清單檔案中加入以下內容：

{
    include: [ "syslog/client.shard.cml" ],
}

加入這個區塊後，所有寫入 stdout 的內容都會記錄為 INFO 訊息，而所有寫入 stderr 的內容都會記錄為 WARN 訊息。訊息會以換行符號分割，並解碼為 UTF-8 字串。無效的位元組序列會轉換為 U+FFFD 替換字元，通常看起來像 �。

無論是否包含 syslog 區塊，這項功能都可以透過明確的標記停用：

    program: {
        runner: "elf",
        binary: "bin/foo",
        forward_stdout_to: "none",
        forward_stderr_to: "none",
    }

生命週期

元件有生命週期。如果您在元件資訊清單中加入 lifecycle 屬性，由 ELF 執行元件執行的元件就能與生命週期整合。目前 stop 是生命週期通訊協定中唯一的方法。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        lifecycle: { stop_event: "notify" },
    }
}

程式應將句柄帶入生命週期管道，並在該管道上提供生命週期通訊協定。元件應在收到並處理 stop 呼叫後退出。

ELF Runner 會監控為元件程式二進位檔啟動的程序。如果這個程序結束，ELF 執行元件會終止元件的執行內容，包括元件的工作和所有子程序。

安全性

有幾個特殊權限欄位受到許可清單的限制。只有列入這個許可清單的元件才能使用這些欄位。對於所有欄位，政策會套用至元件中的第一個程序。第一個程序是 ELF 執行元件為 program 區塊中宣告的二進位檔所建立的程序。所有欄位都是布林值，預設為 false。

主程序處理程序嚴重

main_process_critical 欄位可用於將元件的首個程序標示為「對元件管理員的工作至關重要」，如果程序以非零的程式碼退出，就會導致元件管理員 (以及所有元件) 終止。這會強制系統觸發硬重啟。

Ambient VMO 執行

ambient_mark_vmo_exec 欄位可用於讓元件的第一次程序使用 zx_vmo_replace_as_executable，其中 ZX_HANDLE_INVALID 做為第二個引數，而非以 ZX_RSRC_SYSTEM_VMEX_BASE 為底的有效 ZX_RSRC_KIND_SYSTEM。

建立原始處理程序

job_policy_create_raw_processes 欄位可用於讓元件使用 zx_process_create 建立程序。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        job_policy_create_raw_processes: "true"
    }
}

是否為共用程序

在呼叫 zx_process_create 時，您可以使用 is_shared_process 欄位傳遞 ZX_PROCESS_SHARED 標記。只有在元件也將 job_policy_create_raw_processes 設為 true 時，才能使用這個標記。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        job_policy_create_raw_processes: "true",
        is_shared_process: "true"
    }
}

有可用例外狀況管道的作業

job_with_available_exception_channel 欄位可用於確保元件是建立為職缺的直接子項，該職缺將提供可用於接收的例外狀況管道。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        job_with_available_exception_channel: "true"
    }
}

環境變數

您可以使用 environ 屬性為 ELF 元件設定環境變數。這個欄位必須是字串向量，其中每個字串都包含以等號分隔的變數和值。例如，下列範例程式碼會將變數 FAVORITE_ANIMAL 和 FAVORITE_COLOR 宣告為 cat 和 red。

{
    program: {
        runner: "elf",
        binary: "bin/echo",
        environ: [
            "FAVORITE_ANIMAL=cat",
            "FAVORITE_COLOR=red",
        ]
    }
}

其他資訊

如需瞭解如何建立程序的詳細說明，請參閱「Zircon 程式載入和動態連結」。