CreateSemaphoreW 関数 (synchapi.h)

[アーティクル]
11/20/2024

名前付きセマフォオブジェクトまたは名前のないセマフォオブジェクトを作成または開きます。

オブジェクトのアクセスマスクを指定するには、CreateSemaphoreEx 関数を使用します。

構文

HANDLE CreateSemaphoreW(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCWSTR               lpName
);

パラメーター

[in, optional] lpSemaphoreAttributes

SECURITY_ATTRIBUTES 構造体へのポインター。このパラメーターが NULL場合、子プロセスでハンドルを継承することはできません。

構造体の lpSecurityDescriptor メンバーは、新しいセマフォのセキュリティ記述子を指定します。このパラメーターが NULL場合、セマフォは既定のセキュリティ記述子を取得します。セマフォの既定のセキュリティ記述子の ACL は、作成者のプライマリトークンまたは偽装トークンから取得されます。

[in] lInitialCount

セマフォオブジェクトの初期カウント。この値は、0 以上で、lMaximumCount以下である必要があります。セマフォの状態は、そのカウントが 0 より大きい場合に通知され、ゼロの場合は非署名されます。待機関数がセマフォを待機していたスレッドを解放するたびに、カウントが 1 ずつ減少します。 ReleaseSemaphore 関数を呼び出すことによって、カウントが指定した量増加します。

[in] lMaximumCount

セマフォオブジェクトの最大カウント。この値は 0 より大きくする必要があります。

[in, optional] lpName

セマフォオブジェクトの名前。名前は MAX_PATH 文字に制限されています。名前の比較では大文字と小文字が区別されます。

lpName が既存の名前付きセマフォオブジェクトの名前と一致する場合、この関数は SEMAPHORE_ALL_ACCESS アクセス権を要求します。この場合、lInitialCount パラメーターと lMaximumCount パラメーターは、作成プロセスによって既に設定されているため、無視されます。 lpSemaphoreAttributes パラメーターが NULLされていない場合、ハンドルを継承できるかどうかを判断しますが、そのセキュリティ記述子メンバーは無視されます。

lpName NULL場合、セマフォオブジェクトは名前なしで作成されます。

lpName が既存のイベント、ミューテックス、待機可能タイマー、ジョブ、またはファイルマッピングオブジェクトの名前と一致する場合、関数は失敗し、GetLastError 関数は ERROR_INVALID_HANDLEを返します。これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。

名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。詳細については、「カーネルオブジェクト名前空間を参照してください。高速ユーザー切り替えは、ターミナルサービスセッションを使用して実装されます。カーネルオブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナルサービスに関して概説されているガイドラインに従う必要があります。

オブジェクトはプライベート名前空間に作成できます。詳細については、「オブジェクト名前空間の」を参照してください。

戻り値

関数が成功した場合、戻り値はセマフォオブジェクトへのハンドルです。関数呼び出しの前に名前付きセマフォオブジェクトが存在する場合、関数は既存のオブジェクトへのハンドルを返し、GetLastError は ERROR_ALREADY_EXISTSを返します。

関数が失敗した場合、戻り値は NULL。拡張エラー情報を取得するには、GetLastError呼び出します。

備考

CreateSemaphore によって返されるハンドルには、SEMAPHORE_ALL_ACCESS アクセス権があります。呼び出し元にアクセス権が付与されている場合は、セマフォオブジェクトへのハンドルを必要とする任意の関数で使用できます。セマフォがサービスまたは別のユーザーを偽装しているスレッドから作成された場合は、セマフォを作成するときにセマフォにセキュリティ記述子を適用するか、既定の DACL を変更して作成プロセスの既定のセキュリティ記述子を変更できます。詳細については、「同期オブジェクトのセキュリティとアクセス権のをする」を参照してください。

セマフォオブジェクトの状態は、カウントが 0 より大きい場合に通知され、カウントが 0 に等しい場合は非割り当てになります。 lInitialCount パラメーターは、初期カウントを指定します。カウントを 0 より小さくしたり、lMaximumCount パラメーターで指定された値より大きくしたりすることはできません。

呼び出し元プロセスの任意のスレッドは、待機関数の 1への呼び出しでセマフォオブジェクトハンドルを指定できます。指定したオブジェクトの状態が通知されると、単一オブジェクト待機関数が返されます。複数オブジェクト待機関数は、いずれか 1 つ、または指定されたすべてのオブジェクトが通知されたときに返すように指示できます。待機関数が戻ると、待機中のスレッドが解放され、実行が続行されます。スレッドがセマフォオブジェクトの待機を完了するたびに、セマフォオブジェクトの数が 1 ずつ減らされます。スレッドが完了すると、ReleaseSemaphore 関数が呼び出され、セマフォオブジェクトの数がインクリメントされます。

複数のプロセスが同じセマフォオブジェクトのハンドルを持つ可能性があり、プロセス間同期にオブジェクトを使用できます。次のオブジェクト共有メカニズムを使用できます。

CreateProcess 関数によって作成された子プロセスは、createSemaphore の lpSemaphoreAttributes パラメーターが継承を有効にしている場合 、セマフォオブジェクト ハンドルを継承できます。
プロセスでは、DuplicateHandle 関数の呼び出しでセマフォオブジェクトハンドルを指定して、別のプロセスで使用できる重複ハンドルを作成できます。
プロセスでは、OpenSemaphore または CreateSemaphore 関数の呼び出しでセマフォオブジェクトの名前指定できます。

CloseHandle 関数を使用してハンドルを閉じます。プロセスが終了すると、システムはハンドルを自動的に閉じます。セマフォオブジェクトは、最後のハンドルが閉じられたときに破棄されます。

例

CreateSemaphore使用する例については、「セマフォオブジェクトの使用を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	synchapi.h (Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

CreateSemaphoreW 関数 (synchapi.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース