ZX_Clock_create

摘要

建立新的時鐘物件。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_clock_create(uint64_t options,
                            const void* args,
                            zx_handle_t* out);

權限

無。

說明

建立新的 Zircon 時鐘物件。如需時鐘物件總覽，請參閱「Clocks」。

選項

以下是針對時鐘物件定義的選項：

  • ZX_CLOCK_OPT_MONOTONIC：設定後，系統會建立時鐘物件，保證絕不會向後執行。單聲道時鐘必須一律向前移動。
  • ZX_CLOCK_OPT_CONTINUOUS：設定後，系統會建立一個保證永不向前或向後跳轉的時鐘。連續時鐘只能透過頻率調整維持才能保留，根據定義，也是單調的。嘗試使用指定的 ZX_CLOCK_OPT_CONTINUOUS 選項建立時鐘物件時，如果沒有指定 ZX_CLOCK_OPT_MONOTONIC 選項就會發生錯誤，並會顯示 ZX_ERR_INVALID_ARGS 信號。
  • ZX_CLOCK_OPT_AUTO_START：設定後，系統會為使用者建立自動啟動的時鐘。不必呼叫 zx_clock_update() 也能啟動時鐘。時鐘一開始會是時鐘單調的本機副本，這表示內部從時鐘單調轉換成新建立的合成時鐘是身分函式。不過，建立的時鐘不必使用 ZX_CLOCK_OPT_MONOTONIC 或 ZX_CLOCK_OPT_CONTINUOUS 旗標來建立。建立後，使用者仍可在建立時間指定的單調和連續屬性、處理權限以及時鐘的回溯時間限制內更新時鐘。

引數

設定時鐘時，您可以指定一個額外的建立時間引數，即 Backstop 時間。如要進一步瞭解反停靠站時間，請參閱衣服。

如要設定回溯時間，使用者必須透過 args 參數將 zx_clock_create_args_v1_t 結構傳遞至 zx_clock_create 呼叫。此外，options 位元必須在其中設定 ZX_CLOCK_ARGS_VERSION(1)。

舉例來說，如果使用者想建立回溯時間 5500 的單色時鐘，則可以執行以下動作：

#include <zircon/syscalls.h>
#include <zircon/syscalls/clock.h>

zx_handle_t MakeAClock() {
  zx_clock_create_args_v1_t args;
  zx_handle_t the_clock;
  zx_status_t status;

  args.backstop_time = 5500;
  status = zx_clock_create(ZX_CLOCK_ARGS_VERSION(1) | ZX_CLOCK_OPT_MONOTONIC, &args, &the_clock);
  if (status != ZX_OK) {
    // Log the error
    return ZX_HANDLE_INVALID;
  }

  return the_clock;
}

使用者不必提供引數結構。如果不需要明確的 Backstop，使用者即可從選項參數省略版本位元，直接為引數傳遞 nullptr。

傳回值

成功時，請透過 out 處理常式傳回 ZX_OK 和新的時鐘物件。對新建立的時鐘物件具備的 ZX_RIGHT_READ、ZX_RIGHT_WRITE 和 ZX_RIGHT_SIGNAL 權限將具備指派給這些物件的處理程序。

錯誤

  • ZX_ERR_INVALID_ARGS：指定的選項標記無效、已傳遞錯誤的引數結構版本或指標、在未指定 ZX_CLOCK_OPT_MONOTONIC 的情況下指定 ZX_CLOCK_OPT_CONTINUOUS，或自動啟動時鐘的初始回溯時間晚於目前時鐘的單調時間。
  • ZX_ERR_NO_MEMORY 因記憶體不足而失敗。

另請參閱