ZX_Clock_create

摘要

建立新的時鐘物件。

宣告

#include <zircon/syscalls.h>

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

權限

無。

說明

建立新的 zircon 時鐘物件。如需時鐘物件總覽，請參閱「時鐘」一節。

選項

下列選項適用於時鐘物件：

  • ZX_CLOCK_OPT_BOOT：如果已設定，則會建立時鐘物件，其參照項目為啟動時間軸。
  • 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 旗標。建立後，使用者仍然可以在建立時指定音調和連續屬性的限制、控點權限，以及時鐘的停止時間。

引數

設定時鐘時，您可以指定一個額外的建立時間引數，即備用時間。如要進一步瞭解截止時間，請參閱「時鐘」。

如要設定備援時間，使用者必須透過 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;
}

使用者不必提供引數結構。如果不需要明確的備用方案，使用者可以省略選項參數中的版本位元，並只將 args 傳遞為 nullptr。

傳回值

成功時，會透過 out 句柄傳回 ZX_OK 和新的時鐘物件。新建立的鬧鐘物件句柄會指派 ZX_RIGHT_READ、ZX_RIGHT_WRITE 和 ZX_RIGHT_SIGNAL 權限。

錯誤

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

另請參閱