CreateSemaphoreExW 関数 (synchapi.h)

名前付きまたは名前のないセマフォ オブジェクトを作成または開き、オブジェクトへのハンドルを返します。

構文

HANDLE CreateSemaphoreExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCWSTR               lpName,
                 DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

パラメーター

[in, optional] lpSemaphoreAttributes

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

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

[in] lInitialCount

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

[in] lMaximumCount

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

[in, optional] lpName

セマフォ オブジェクトの名前を指定する null で終わる文字列へのポインター。 名前は MAX_PATH 文字に制限されます。 名前の比較では大文字と小文字が区別されます。

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

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

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

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

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

dwFlags

このパラメーターは予約されており、0 である必要があります。

[in] dwDesiredAccess

セマフォ オブジェクトのアクセス マスク。 アクセス権の一覧については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。

戻り値

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

関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

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

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

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

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

要件

関連項目

CloseHandle

セマフォ オブジェクト

同期関数