CreateSemaphoreA 関数 (winbase.h)
名前付きセマフォ オブジェクトまたは名前のないセマフォ オブジェクトを作成または開きます。
オブジェクトのアクセス マスクを指定するには、 CreateSemaphoreEx 関数を使用します。
構文
HANDLE CreateSemaphoreA(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCSTR lpName
);
パラメーター
[in, optional] lpSemaphoreAttributes
SECURITY_ATTRIBUTES構造体へのポインター。 このパラメーターが NULL の場合、ハンドルは子プロセスによって継承できません。
構造体の lpSecurityDescriptor メンバーは、新しいセマフォのセキュリティ記述子を指定します。 このパラメーターが NULL の場合、セマフォは既定のセキュリティ記述子を取得します。 セマフォの既定のセキュリティ記述子の ACL は、作成者のプライマリ トークンまたは偽装トークンから取得されます。
[in] lInitialCount
セマフォ オブジェクトの初期カウント。 この値は、0 以上で 、lMaximumCount 以下である必要があります。 セマフォの状態は、その数が 0 より大きい場合に通知され、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 ずつ減らされます。 スレッドが完了すると、 ReleaseSemaphore 関数が呼び出され、セマフォ オブジェクトのカウントがインクリメントされます。
複数のプロセスに同じセマフォ オブジェクトのハンドルを含めることができるため、プロセス間同期に オブジェクトを使用できます。 次のオブジェクト共有メカニズムを使用できます。
- CreateSemaphore の lpSemaphoreAttributes パラメーターで継承が有効になっている場合、CreateProcess 関数によって作成された子プロセスは、セマフォ オブジェクトへのハンドルを継承できます。
- プロセスでは、 DuplicateHandle 関数の呼び出しでセマフォ オブジェクト ハンドルを指定して、別のプロセスで使用できる重複するハンドルを作成できます。
- プロセスでは、[OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-opensemaphorew) または CreateSemaphore 関数の呼び出しでセマフォ オブジェクトの名前を指定できます。
例
CreateSemaphore を使用する例については、「セマフォ オブジェクトの使用」を参照してください。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |