その他のユーティリティー¶

この節では、ほかの節に分類しにくい各種関数を扱います。

データ型¶

type uv_buf_t¶

バッファーのデータ型です。

char *uv_buf_t.base¶: バッファーの先頭を指すポインターです。

size_t uv_buf_t.len¶: バッファーの総バイト数です。

注記

Windowsでは、このフィールドはULONGです。

typedef void *(*uv_malloc_func)(size_t size)¶: 次の関数の代替関数です: malloc(3)。次の関数を参照してください: uv_replace_allocator()。

typedef void *(*uv_realloc_func)(void *ptr, size_t size)¶: 次の関数の代替関数です: realloc(3)。次の関数を参照してください: uv_replace_allocator()。

typedef void *(*uv_calloc_func)(size_t count, size_t size)¶: 次の関数の代替関数です: calloc(3)。次の関数を参照してください: uv_replace_allocator()。

typedef void (*uv_free_func)(void *ptr)¶: 次の関数の代替関数です: free(3)。次の関数を参照してください: uv_replace_allocator()。

typedef void (*uv_random_cb)(uv_random_t *req, int status, void *buf, size_t buflen)¶: 次の関数へ渡すコールバックです: uv_random()。statusは、エラーの場合は0以外です。bufポインターは、次の関数へ渡したものと同じです: uv_random()。

type uv_file¶: プラットフォーム間で使えるファイルハンドルの表現です。

type uv_os_sock_t¶: プラットフォーム間で使えるソケットハンドルの表現です。

type uv_os_fd_t¶: ファイルディスクリプターの抽象表現です。Unixでは、typedefによって定義したintであり、WindowsではHANDLEです。

type uv_pid_t¶: プラットフォーム間で使えるpid_tの表現です。

バージョン1.16.0で追加。

type uv_timeval_t¶

マイクロ秒分解能の時刻を格納する、2038年問題に対応していないデータ型です。libuv v2.0では、uv_timeval64_tに置き換えます。

typedef struct {
    long tv_sec;
    long tv_usec;
} uv_timeval_t;

type uv_timeval64_t¶

マイクロ秒分解能の時刻を格納する、2038年問題に対応したデータ型です。

typedef struct {
    int64_t tv_sec;
    int32_t tv_usec;
} uv_timeval64_t;

type uv_timespec64_t¶

ナノ秒分解能の時刻を格納する、2038年問題に対応したデータ型です。

typedef struct {
    int64_t tv_sec;
    int32_t tv_nsec;
} uv_timespec64_t;

enum uv_clock_id¶

次の関数のクロック源です: uv_clock_gettime()。

typedef enum {
  UV_CLOCK_MONOTONIC,
  UV_CLOCK_REALTIME
} uv_clock_id;

type uv_rusage_t¶

資源使用量の結果を格納するデータ型です。

typedef struct {
    uv_timeval_t ru_utime; /* user CPU time used */
    uv_timeval_t ru_stime; /* system CPU time used */
    uint64_t ru_maxrss; /* maximum resident set size */
    uint64_t ru_ixrss; /* integral shared memory size (X) */
    uint64_t ru_idrss; /* integral unshared data size (X) */
    uint64_t ru_isrss; /* integral unshared stack size (X) */
    uint64_t ru_minflt; /* page reclaims (soft page faults) (X) */
    uint64_t ru_majflt; /* page faults (hard page faults) */
    uint64_t ru_nswap; /* swaps (X) */
    uint64_t ru_inblock; /* block input operations */
    uint64_t ru_oublock; /* block output operations */
    uint64_t ru_msgsnd; /* IPC messages sent (X) */
    uint64_t ru_msgrcv; /* IPC messages received (X) */
    uint64_t ru_nsignals; /* signals received (X) */
    uint64_t ru_nvcsw; /* voluntary context switches (X) */
    uint64_t ru_nivcsw; /* involuntary context switches (X) */
} uv_rusage_t;

次の印、(X)を付けたメンバーは、Windowsではサポートしていません。Unix系プラットフォームでサポートするフィールドについては、getrusage(2)を参照してください。

最大常駐セットサイズは、多くのプラットフォームがそのまま使う単位であるキロバイトで報告します。

type uv_cpu_info_t¶

CPU情報のデータ型です。

typedef struct uv_cpu_info_s {
    char* model;
    int speed;
    struct uv_cpu_times_s {
        uint64_t user; /* milliseconds */
        uint64_t nice; /* milliseconds */
        uint64_t sys; /* milliseconds */
        uint64_t idle; /* milliseconds */
        uint64_t irq; /* milliseconds */
    } cpu_times;
} uv_cpu_info_t;

type uv_interface_address_t¶

インターフェースアドレスのデータ型です。

typedef struct uv_interface_address_s {
    char* name;
    char phys_addr[6];
    int is_internal;
    union {
        struct sockaddr_in address4;
        struct sockaddr_in6 address6;
    } address;
    union {
        struct sockaddr_in netmask4;
        struct sockaddr_in6 netmask6;
    } netmask;
} uv_interface_address_t;

type uv_passwd_t¶

パスワードファイル情報のデータ型です。

typedef struct uv_passwd_s {
    char* username;
    long uid;
    long gid;
    char* shell;
    char* homedir;
} uv_passwd_t;

type uv_group_t¶

グループファイル情報のデータ型です。

typedef struct uv_group_s {
  char* groupname;
  unsigned long gid;
  char** members;
} uv_group_t;

type uv_utsname_t¶

OSの名前とバージョン情報のデータ型です。

typedef struct uv_utsname_s {
    char sysname[256];
    char release[256];
    char version[256];
    char machine[256];
} uv_utsname_t;

type uv_env_item_t¶

環境変数を格納するデータ型です。

typedef struct uv_env_item_s {
    char* name;
    char* value;
} uv_env_item_t;

type uv_random_t¶: 乱数データ要求の型です。

API¶

uv_handle_type uv_guess_handle(uv_file file)¶

指定したファイルディスクリプターに使うストリームの型を検出します。通常は、初期化中に標準入出力ストリームの型を推定するために使います。

次の関数、isatty(3)と同等の機能を得るには、この関数を使い、次の値かどうかを調べます: UV_TTY。

int uv_replace_allocator(uv_malloc_func malloc_func, uv_realloc_func realloc_func, uv_calloc_func calloc_func, uv_free_func free_func)¶

バージョン1.6.0で追加。

標準ライブラリーの次のメモリー割り当て関数の使用を置き換えます: malloc(3)、calloc(3)、realloc(3)、free(3)。

ほかのlibuv関数を呼び出す前、またはすべての資源を解放し、libuvが割り当て済みのメモリーを参照していない状態で呼び出す必要があります。

成功時は0を返します。いずれかの関数ポインターがNULLなら、UV_EINVALを返します。

警告

アロケーターを何度も変更することに対する保護はありません。変更する場合、以前のアロケーターで割り当てたメモリーが残っていない時点で変更するか、両者に互換性があることを、ユーザーが保証する必要があります。

警告

アロケーターはスレッドセーフである必要があります。

void uv_library_shutdown(void);¶: バージョン1.38.0で追加。

libuvが保持しているグローバルな状態を解放します。通常はアンロード時に自動で解放しますが、手動で後始末するよう指示できます。

警告

次の関数、uv_library_shutdown()は、1回だけ呼び出してください。

警告

イベントループやI/O要求がまだ動作中のときは、uv_library_shutdown()を呼び出さないでください。

警告

次の関数、uv_library_shutdown()を呼び出した後は、libuvの関数を呼び出さないでください。

uv_buf_t uv_buf_init(char *base, unsigned int len)¶: 次の型のコンストラクターです: uv_buf_t。

プラットフォーム間の違いがあるため、uv_buf_t構造体のbaseとlenメンバーの順序に依存できません。uv_buf_tを使い終えた後のbaseの解放は、ユーザーの責任です。返す構造体は値渡しです。

警告

次の値、lenを大きくすることは推奨しません。不必要な失敗につながる可能性があります。具体的には、Windowsでは約511 MBを超える書き込み、各種Unixでは約2 GB（0x7ffff000バイト）を超えるI/Oに失敗することがあります。通常は、データを複数のuv_write呼び出しへ分割する方が適切です（write_cbを最後の呼び出しに付けます）。

char **uv_setup_args(int argc, char **argv)¶

プログラムの引数を保存します。プロセスタイトルの取得・設定や実行ファイルのパス取得に必要です。libuvは、argvが指すメモリーの所有権を取得する場合があります。プログラム起動時に、ちょうど1回呼び出してください。

例:

argv = uv_setup_args(argc, argv);  /* May return a copy of argv. */

int uv_get_process_title(char *buffer, size_t size)¶: 現在のプロセスのタイトルを取得します。UnixとAIXでは、この関数より前に必ず次の関数を呼び出してください: uv_setup_args。必要なシステムでuv_setup_argsを呼び出していない場合は、UV_ENOBUFSを返します。bufferがNULL、またはsizeが0なら、UV_EINVALを返します。sizeにプロセスタイトルと終端のnul文字が収まらない場合は、UV_ENOBUFSを返します。

注記

BSDでは、初期のプロセスタイトルを取得するためにuv_setup_argsが必要です。uv_setup_argsまたはuv_set_process_titleを呼び出すまでは、返すプロセスタイトルは空文字列です。

バージョン1.18.1での変更: サポートするすべてのプラットフォームでスレッドセーフになりました。

バージョン1.39.0での変更: 次の関数が必要であるにもかかわらず、uv_setup_argsを呼び出していない場合、エラーを返すようになりました。

int uv_set_process_title(const char *title)¶: 現在のプロセスタイトルを設定します。UnixとAIXでは、この関数より前に必ず次の関数を呼び出してください: uv_setup_args。必要なシステムでuv_setup_argsを呼び出していない場合は、UV_ENOBUFSを返します。プロセスタイトル用に固定サイズのバッファーを使うプラットフォームでは、titleの内容をバッファーへコピーし、空き容量を超える場合は切り詰めます。ほかのプラットフォームでは、次のエラーを返します: UV_ENOMEM。これは、titleの内容を複製する十分な領域を確保できない場合です。

バージョン1.18.1での変更: サポートするすべてのプラットフォームでスレッドセーフになりました。

バージョン1.39.0での変更: 次の関数が必要であるにもかかわらず、uv_setup_argsを呼び出していない場合、エラーを返すようになりました。

int uv_resident_set_memory(size_t *rss)¶: 現在のプロセスの常駐セットサイズ（RSS）を取得します。

int uv_uptime(double *uptime)¶: 現在のシステムの稼働時間を取得します。システムによって、整数秒または小数を含む秒数を返します。

int uv_getrusage(uv_rusage_t *rusage)¶: 現在のプロセスの資源使用量を取得します。

注記

Windowsでは、すべてのフィールドを設定するわけではありません。サポートしていないフィールドには0を設定します。詳細は、uv_rusage_tを参照してください。

int uv_getrusage_thread(uv_rusage_t *rusage)¶: 呼び出し元スレッドの資源使用量を取得します。

バージョン1.50.0で追加。

注記

すべてのプラットフォームでサポートしているわけではなく、UV_ENOTSUPを返す場合があります。macOSとWindowsでは、すべてのフィールドを設定するわけではありません。サポートしていないフィールドには0を設定します。詳細は、uv_rusage_tを参照してください。

uv_pid_t uv_os_getpid(void)¶: 現在のプロセスIDを返します。

バージョン1.18.0で追加。

uv_pid_t uv_os_getppid(void)¶: 親プロセスのIDを返します。

バージョン1.16.0で追加。

unsigned int uv_available_parallelism(void)¶

プログラムがデフォルトで使うべき並列度の推定値を返します。常に0以外の値を返します。

Linuxでは、呼び出し元スレッドのCPUアフィニティーマスクを調べ、特定のCPUに固定されているかどうかを判断します。

Windowsでは、論理CPUが64個を超えるシステムで、利用可能な並列度を実際より小さく報告する場合があります。

ほかのプラットフォームでは、OSがオンラインと見なすCPU数を報告します。

バージョン1.44.0で追加。

int uv_cpu_info(uv_cpu_info_t **cpu_infos, int *count)¶

システムのCPU情報を取得します。cpu_infos配列にはcount個の要素があり、次の関数で解放する必要があります: uv_free_cpu_info()。

スレッドや子プロセスに利用できるCPU数を知りたい場合は、次の関数を使ってください: uv_available_parallelism()。

void uv_free_cpu_info(uv_cpu_info_t *cpu_infos, int count)¶: 次の配列、cpu_infosを解放します。これは、次の関数で確保したものです: uv_cpu_info()。

int uv_cpumask_size(void)¶: プロセス・スレッドのアフィニティーに使うマスクの最大サイズを返します。現在のプラットフォームがアフィニティーをサポートしていない場合は、UV_ENOTSUPを返します。

バージョン1.45.0で追加。

int uv_interface_addresses(uv_interface_address_t **addresses, int *count)¶: システムのネットワークインターフェースのアドレス情報を取得します。count個の要素を持つ配列を確保し、addressesで返します。ユーザーが次の関数を呼び出して解放する必要があります: uv_free_interface_addresses()。

void uv_free_interface_addresses(uv_interface_address_t *addresses, int count)¶: 次の型の配列を解放します: uv_interface_address_t。これは、次の関数が返したものです: uv_interface_addresses()。

void uv_loadavg(double avg[3])¶: 負荷平均を取得します。次を参照してください: https://en.wikipedia.org/wiki/Load_(computing)

注記

Windowsでは[0,0,0]を返します（実装していないため）。

int uv_ip4_addr(const char *ip, int port, struct sockaddr_in *addr)¶: IPv4アドレスを含む文字列をバイナリー構造体へ変換します。

int uv_ip6_addr(const char *ip, int port, struct sockaddr_in6 *addr)¶: IPv6アドレスを含む文字列をバイナリー構造体へ変換します。

int uv_ip4_name(const struct sockaddr_in *src, char *dst, size_t size)¶: IPv4アドレスを含むバイナリー構造体を文字列へ変換します。

int uv_ip6_name(const struct sockaddr_in6 *src, char *dst, size_t size)¶: IPv6アドレスを含むバイナリー構造体を文字列へ変換します。

int uv_ip_name(const struct sockaddr *src, char *dst, size_t size)¶: IPv4またはIPv6アドレスを含むバイナリー構造体を文字列へ変換します。

int uv_inet_ntop(int af, const void *src, char *dst, size_t size)¶

int uv_inet_pton(int af, const char *src, void *dst)¶: プラットフォーム間で使える、IPv6対応の次の関数の実装です: inet_ntop(3)およびinet_pton(3)。成功時は0を返します。エラー時は、対象のdstポインターは変更しません。

UV_IF_NAMESIZE¶: IPv6インターフェース識別子の名前の最大長です。UnixではIFNAMSIZ、LinuxとWindowsではIF_NAMESIZEとして定義しています。

バージョン1.16.0で追加。

int uv_if_indextoname(unsigned int ifindex, char *buffer, size_t *size)¶

IPv6に対応した次の関数の実装です: if_indextoname(3)。呼び出し時、*sizeは、結果の格納先となるbufferの長さを示します。成功時は0を返し、bufferにインターフェース名を格納します。*sizeは、bufferの文字列長を示し、終端NULバイトを*sizeに含めません。エラー時は負の値を返します。bufferに結果が収まらない場合は、UV_ENOBUFSを返し、*sizeは、終端NULバイトを含めた必要なバイト数を示します（*sizeに含めます）。

Unixでは、返したインターフェース名を、スコープ付きIPv6アドレスの識別子として直接使えます。例: fe80::abc:def1:2345%en0。

Windowsでは数値のインターフェース識別子を使うため、返したインターフェース名を識別子としては使えません。例: fe80::abc:def1:2345%5。

プラットフォーム間で互換性のある方法で識別子を取得するには、uv_if_indextoiid()を使います。

例:

char ifname[UV_IF_NAMESIZE];
size_t size = sizeof(ifname);
uv_if_indextoname(sin6->sin6_scope_id, ifname, &size);

バージョン1.16.0で追加。

int uv_if_indextoiid(unsigned int ifindex, char *buffer, size_t *size)¶

IPv6のスコープ付きアドレスで使えるネットワークインターフェース識別子を取得します。Windowsでは、数値のifindexを文字列として返します。ほかのすべてのプラットフォームでは、uv_if_indextoname()を呼び出します。結果はbufferに書き込み、*sizeはbufferの長さを示します。bufferに結果が収まらない場合は、UV_ENOBUFSを返し、*sizeは、結果の格納に必要なサイズを、終端NULバイト込みで示します。

詳細は、uv_if_indextonameを参照してください。

バージョン1.16.0で追加。

int uv_exepath(char *buffer, size_t *size)¶

実行ファイルのパスを取得します。この関数より前に必ず次の関数を呼び出してください: uv_setup_args。

setuid実行ファイルでは注意してください。一部のプラットフォームでは、実行ファイルのパスはユーザーが制御する任意の文字列です。ほかのプラットフォームでは、ユーザーが制御できる可能性のある環境変数を参照します。

int uv_cwd(char *buffer, size_t *size)¶: 現在の作業ディレクトリーを取得し、bufferに格納します。現在の作業ディレクトリーがbufferに収まらない場合は、UV_ENOBUFSを返し、sizeに、終端NULを含む必要な長さを設定します。

バージョン1.1.0での変更: Unixでは、パスの末尾にスラッシュが付かなくなりました。

バージョン1.9.0での変更: 次のエラーの場合、返す長さに終端NULバイトを含めるようになりました: UV_ENOBUFS。成功時はバッファーをヌル終端します。

int uv_chdir(const char *dir)¶: 現在の作業ディレクトリーを変更します。

int uv_os_homedir(char *buffer, size_t *size)¶: 現在のユーザーのホームディレクトリーを取得します。Windowsでは、uv_os_homedir()はまず環境変数USERPROFILEを、GetEnvironmentVariableW()で調べます。USERPROFILEを設定していない場合は、GetUserProfileDirectoryW()を呼び出します。ほかのすべてのOSでは、uv_os_homedir()はまず環境変数HOMEを、getenv(3)で調べます。HOMEを設定していない場合は、getpwuid_r(3)を呼び出します。ユーザーのホームディレクトリーはbufferに格納します。uv_os_homedir()の呼び出し時、sizeはbufferの最大サイズを示します。成功時は、sizeにbufferの文字列長を設定します。UV_ENOBUFSによる失敗時は、sizeにbufferの必要な長さをNULバイト込みで設定します。

警告

uv_os_homedir()はスレッドセーフではありません。

バージョン1.6.0で追加。

int uv_os_tmpdir(char *buffer, size_t *size)¶: 一時ディレクトリーを取得します。Windowsでは、uv_os_tmpdir()はGetTempPathW()を使います。ほかのすべてのOSでは、uv_os_tmpdir()は、環境変数を次の順序で調べ、最初に見つかったものを使います: TMPDIR、TMP、TEMP、TEMPDIR。どれも見つからない場合は、“/tmp”、Androidでは“/data/local/tmp”を使います。一時ディレクトリーはbufferに格納します。uv_os_tmpdir()の呼び出し時、sizeはbufferの最大サイズを示します。成功時は、sizeにbufferの文字列長を設定します（終端NULは含めません）。UV_ENOBUFSによる失敗時は、sizeにbufferの必要な長さをNULバイト込みで設定します。

警告

uv_os_tmpdir()はスレッドセーフではありません。

バージョン1.9.0で追加。

int uv_os_get_passwd(uv_passwd_t *pwd)¶: 現在の実効uid（実uidではありません）のパスワードファイルエントリーの一部を取得します。取得するデータは、ユーザー名、euid、gid、シェル、ホームディレクトリーです。Windows以外では、すべてのデータをgetpwuid_r(3)から取得します。Windowsではuidとgidに-1を設定し、意味を持ちません。シェルはNULLです。この関数の成功後、pwdに確保したメモリーを、次の関数で解放する必要があります: uv_os_free_passwd()。

バージョン1.9.0で追加。

int uv_os_get_passwd2(uv_passwd_t *pwd, uv_uid_t uid)¶: 指定したuidのパスワードファイルエントリーの一部を取得します。取得するデータは、ユーザー名、euid、gid、シェル、ホームディレクトリーです。Windows以外では、すべてのデータをgetpwuid_r(3)から取得します。Windowsではuidとgidに-1を設定し、意味を持ちません。シェルはNULLです。この関数の成功後、pwdに確保したメモリーを、次の関数で解放する必要があります: uv_os_free_passwd()。

バージョン1.45.0で追加。

int uv_os_get_group(uv_group_t *group, uv_uid_t gid)¶: 指定したuidのグループファイルエントリーの一部を取得します。取得するデータは、グループ名、gid、メンバーです。Windows以外では、すべてのデータをgetgrgid_r(3)から取得します。Windowsではuidとgidに-1を設定し、意味を持ちません。この関数の成功後、groupに確保したメモリーを、次の関数で解放する必要があります: uv_os_free_group()。

バージョン1.45.0で追加。

void uv_os_free_group(uv_passwd_t *pwd)¶: 次の関数で確保したメモリーを解放します: uv_os_get_group()。

バージョン1.45.0で追加。

void uv_os_free_passwd(uv_passwd_t *pwd)¶: 次のメモリー、pwdを解放します。これは、次の関数で確保したものです: uv_os_get_passwd()。

バージョン1.9.0で追加。

uint64_t uv_get_free_memory(void)¶: カーネルが報告する、システムで利用できる空きメモリーの量をバイト単位で取得します。不明の場合は0を返します。

uint64_t uv_get_total_memory(void)¶: システムの物理メモリーの総量をバイト単位で取得します。不明の場合は0を返します。

uint64_t uv_get_constrained_memory(void)¶: OSが課す制限に基づき、プロセスが利用できるメモリーの総量をバイト単位で取得します。制限がない場合や不明な場合は、0を返します。制限の仕組みがあるものの、制限を設定していない場合は、UINT64_MAXを返します。この値が、次の関数の値より小さい場合や大きい場合も珍しくありません: uv_get_total_memory()。

注記

現在、この関数が0以外を返すのは、cgroupsがある場合にそれを参照するLinuxと、RLIMIT_MEMLIMITを参照するz/OSだけです。

バージョン1.29.0で追加。

uint64_t uv_get_available_memory(void)¶: プロセスがまだ利用できる空きメモリーの量をバイト単位で取得します。次の関数、uv_get_free_memory()とは異なり、OSが課す制限を考慮します。制限がない場合や不明な場合は、次の関数と同じ量を返します: uv_get_free_memory()。

注記

現在、この関数がuv_get_free_memory()の報告値と異なる値を返すのは、cgroupsがある場合にそれを参照するLinuxだけです。

バージョン1.45.0で追加。

uint64_t uv_hrtime(void)¶: 現在の高分解能タイムスタンプをナノ秒単位で返します。過去の任意の時点からの相対値です。時刻とは関係がないため、時計のドリフトの影響を受けません。主な用途は、区間の性能測定です。

注記

すべてのプラットフォームがナノ秒分解能をサポートするわけではありませんが、この値の単位は常にナノ秒です。

int uv_clock_gettime(uv_clock_id clock_id, uv_timespec64_t *ts)¶

高分解能の実時間または単調クロック源から、現在のシステム時刻を取得します。

実時間クロックはUNIXエポック（1970-01-01）から数え、時刻調整の影響を受けるため、過去へ戻ることがあります。

単調クロックは過去の任意の時点から数え、過去へ戻ることはありません。

バージョン1.45.0で追加。

void uv_print_all_handles(uv_loop_t *loop, FILE *stream)¶

指定したloopに関連するすべてのハンドルを、指定したstreamへ出力します。

例:

uv_print_all_handles(uv_default_loop(), stderr);
/*
[--I] signal   0x1a25ea8
[-AI] async    0x1a25cf0
[R--] idle     0x1a7a8c8
*/

形式は、[flags] handle-type handle-addressです。flagsの意味は次のとおりです:

Rは、参照されているハンドルに表示します。
Aは、アクティブなハンドルに表示します。
Iは、内部ハンドルに表示します。

警告

この関数は、その場限りのデバッグ用であり、API・ABIの安定性は保証していません。

バージョン1.8.0で追加。

void uv_print_active_handles(uv_loop_t *loop, FILE *stream)¶: 次の関数、uv_print_all_handles()と同じですが、アクティブなハンドルだけを出力します。

警告

この関数は、その場限りのデバッグ用であり、API・ABIの安定性は保証していません。

バージョン1.8.0で追加。

int uv_os_environ(uv_env_item_t **envitems, int *count)¶: すべての環境変数を取得します。メモリーを確保するため、次の関数を呼び出して解放する必要があります: uv_os_free_environ()。

警告

この関数はスレッドセーフではありません。

バージョン1.31.0で追加。

void uv_os_free_environ(uv_env_item_t *envitems, int count);¶: 次の関数が環境変数用に確保したメモリーを解放します: uv_os_environ()。

バージョン1.31.0で追加。

int uv_os_getenv(const char *name, char *buffer, size_t *size)¶: 次の名前で指定した環境変数を取得します: name。値をbufferへコピーし、sizeに値の文字列長を設定します。呼び出し時は、sizeにbufferで利用できる領域の大きさを終端NUL込みで設定してください。環境変数がbufferに収まらない場合は、UV_ENOBUFSを返し、sizeに値の格納に必要な領域の大きさを設定します。一致する環境変数がない場合は、UV_ENOENTを返します。

警告

この関数はスレッドセーフではありません。

バージョン1.12.0で追加。

int uv_os_setenv(const char *name, const char *value)¶: 次の名前で指定した環境変数を作成または更新します: name。設定する値は、valueです。

警告

この関数はスレッドセーフではありません。

バージョン1.12.0で追加。

int uv_os_unsetenv(const char *name)¶: 次の名前で指定した環境変数を削除します: name。該当する環境変数がなければ、成功として戻ります。

警告

この関数はスレッドセーフではありません。

バージョン1.12.0で追加。

int uv_os_gethostname(char *buffer, size_t *size)¶: ホスト名をヌル終端文字列としてbufferへ返し、sizeにホスト名の文字列長を設定します。呼び出し時は、sizeにbufferで利用できる領域の大きさを終端NUL込みで設定してください。ホスト名がbufferに収まらない場合は、UV_ENOBUFSを返し、sizeに値の格納に必要な領域の大きさを設定します。

バージョン1.12.0で追加。

バージョン1.26.0での変更: UV_MAXHOSTNAMESIZEが利用可能になりました。これは、bufferにホスト名と終端のnul文字を格納するために必要な最大サイズを示します。

int uv_os_getpriority(uv_pid_t pid, int *priority)¶: 次のIDで指定したプロセスのスケジューリング優先度を取得します: pid。返すpriorityの値は、-20（高優先度）から19（低優先度）です。

注記

Windowsでは、返す優先度はUV_PRIORITY定数のいずれかと一致します。

バージョン1.23.0で追加。

int uv_os_setpriority(uv_pid_t pid, int priority)¶: 次のIDで指定したプロセスのスケジューリング優先度を設定します: pid。priorityの範囲は、-20（高優先度）から19（低優先度）です。便宜上、次の定数も用意しています: UV_PRIORITY_LOW、UV_PRIORITY_BELOW_NORMAL、UV_PRIORITY_NORMAL、UV_PRIORITY_ABOVE_NORMAL、UV_PRIORITY_HIGH、UV_PRIORITY_HIGHEST。

注記

Windowsでは、SetPriorityClass()を使います。priority引数はWindowsの優先度クラスへ対応付けます。プロセスの優先度を取得すると、結果はUV_PRIORITY定数のいずれかと一致し、設定したpriorityの値と厳密に一致するとは限りません。

注記

Windowsでは、PRIORITY_HIGHESTの設定は昇格したユーザーだけに有効です。ほかのユーザーでは、通知せずPRIORITY_HIGHへ引き下げます。

注記

IBM i PASEでは、プロセスの最高優先度は-10です。UV_PRIORITY_HIGHESTは-10、UV_PRIORITY_HIGHは-7、UV_PRIORITY_ABOVE_NORMALは-4、UV_PRIORITY_NORMALは0、UV_PRIORITY_BELOW_NORMALは15、UV_PRIORITY_LOWは39です。

注記

IBM i PASEでは、*JOBCTL特殊権限がなければ、優先度を変更できません（引き下げる場合も同じです）。

バージョン1.23.0で追加。

int uv_os_uname(uv_utsname_t *buffer)¶: システム情報をbufferへ取得します。取得するデータは、OSの名前、リリース、バージョン、マシンです。Windows以外では、uv_os_uname()はuname(2)の薄いラッパーです。成功時は0、それ以外では0以外のエラー値を返します。

バージョン1.25.0で追加。

int uv_gettimeofday(uv_timeval64_t *tv)¶: プラットフォーム間で使える次の関数の実装です: gettimeofday(2)。gettimeofday()のタイムゾーン引数は、廃止されたものと見なすため、サポートしていません。

バージョン1.28.0で追加。

int uv_random(uv_loop_t *loop, uv_random_t *req, void *buf, size_t buflen, unsigned int flags, uv_random_cb cb)¶

システムのCSPRNGから取得した、暗号学的に強い乱数バイトで、bufをちょうどbuflenバイト埋めます。flagsは将来の拡張用に予約しており、現在は0である必要があります。

短い読み取りはありません。利用できる乱数バイトがbuflen未満なら、0以外のエラー値を返すか、コールバックへ渡します。

同期版は、エントロピーが不足すると無期限にブロックする場合があります。非同期版も、システムのエントロピーが少ない場合、完了しない可能性があります。

エントロピー源:

Windows: RtlGenRandom <https://docs.microsoft.com/en-us/windows/desktop/api/ntsecapi/nf-ntsecapi-rtlgenrandom>_。
Linux、Android: getrandom(2)が利用できる場合はそれを使います。それ以外は、urandom(4)（先に/dev/randomを1回読み取ります）、またはKERN_RANDOM sysctl(2)を使います。
FreeBSD: getrandom(2) <https://www.freebsd.org/cgi/man.cgi?query=getrandom&sektion=2>_、または/dev/urandom（先に/dev/randomを1回読み取ります）。
NetBSD: KERN_ARND sysctl(7) <https://man.netbsd.org/sysctl.7>_
macOS、OpenBSD: getentropy(2) <https://man.openbsd.org/getentropy.2>_が利用できる場合はそれを使います。それ以外は、/dev/urandom（先に/dev/randomを1回読み取ります）。
AIX: /dev/random。
IBM i: /dev/urandom。
その他のUnix: /dev/urandom（先に/dev/randomを1回読み取ります）。

戻り値:: 成功時は0、失敗時は0未満のエラーコードです。エラー後のbufの内容は未定義です。

注記

同期版では、loopとreqパラメーターは使わず、NULLを指定できます。

バージョン1.33.0で追加。

void uv_sleep(unsigned int msec)¶: 呼び出し元スレッドを、msecミリ秒スリープさせます。

バージョン1.34.0で追加。

#include <uv.h>
#include <stdio.h>
int main() {
    printf("Sleeping for 1 second...\n");
    uv_sleep(1000);
    printf("Awake!\n");
    return 0;
}

文字列操作関数¶

これらの文字列ユーティリティーは、Windowsを扱うために内部で必要となるものです。libuv APIが完全でない部分でも、クライアントがこのデータを一様に扱えるよう、公開しています。

size_t uv_utf16_length_as_wtf8(const uint16_t *utf16, ssize_t utf16_len)¶: UTF-16（またはUCS-2）のutf16値をWTF-8へ変換した後の長さを取得します。utf16がNUL終端なら、utf16_lenに-1を指定できます。それ以外は長さの指定が必要です。

バージョン1.47.0で追加。

int uv_utf16_to_wtf8(const uint16_t *utf16, ssize_t utf16_len, char **wtf8_ptr, size_t *wtf8_len_ptr)¶: 次の値に格納したUTF-16（またはUCS-2）データ、utf16を、*wtf8_ptrのWTF-8データへ変換します。utf16_lenは、utf16の長さを文字数で示します。utf16がNUL終端なら、utf16_lenに-1を指定できます。それ以外は長さの指定が必要です。wtf8_ptrがNULLなら結果を計算しませんが、長さ（uv_utf16_length_as_wtf8と同じ）をwtf8_len_ptrに格納します。*wtf8_ptrがNULLなら変換用の領域を確保し、wtf8_ptrで返します。長さはwtf8_len_ptrで返します。それ以外は、*wtf8_ptrの長さをwtf8_len_ptrで渡してください。wtf8_ptrには、結果の後ろのNUL用に余分な領域が必要です。結果を切り詰めた場合は、UV_ENOBUFSを返し、wtf8_len_ptrは、結果全体を格納するために必要なwtf8_ptrの長さを示します。

バージョン1.47.0で追加。

ssize_t uv_wtf8_length_as_utf16(const char *wtf8)¶: NUL終端されたWTF-8のwtf8値をUTF-16（またはUCS-2）へ変換した後の長さを、終端NULを含めた文字数で取得します。

バージョン1.47.0で追加。

void uv_wtf8_to_utf16(const char *utf8, uint16_t *utf16, size_t utf16_len)¶: 次の値に格納したNUL終端のWTF-8データ、wtf8を、utf16のUTF-16（またはUCS-2）データへ変換します。utf16_lenは文字数であり、終端NULの領域を含める必要があります。

バージョン1.47.0で追加。