CreateMutexExA 関数 (synchapi.h)

名前付きまたは名前のないミューテックス オブジェクトを作成または開き、オブジェクトへのハンドルを返します。

構文

HANDLE CreateMutexExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

パラメーター

[in, optional] lpMutexAttributes

SECURITY_ATTRIBUTES構造体へのポインター。 このパラメーターが NULL の場合、ミューテックス ハンドルは子プロセスによって継承できません。

構造体の lpSecurityDescriptor メンバーは、新しいミューテックスのセキュリティ記述子を指定します。 lpMutexAttributes が NULL の場合、ミューテックスは既定のセキュリティ記述子を取得します。 ミューテックスの既定のセキュリティ記述子の ACL は、作成者のプライマリ トークンまたは偽装トークンから取得されます。 詳細については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。

[in, optional] lpName

ミューテックス オブジェクトの名前。 名前は MAX_PATH 文字に制限されます。 名前の比較では大文字と小文字が区別されます。

lpName が NULL の場合、ミューテックス オブジェクトは名前なしで作成されます。

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

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

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

[in] dwFlags

このパラメーターには、0 または次の値を指定できます。

[in] dwDesiredAccess

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

戻り値

関数が成功した場合、戻り値は新しく作成されたミューテックス オブジェクトへのハンドルです。

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

ミューテックスが名前付きミューテックスであり、この関数呼び出しの前にオブジェクトが存在する場合、戻り値は既存のオブジェクトへのハンドルであり、 GetLastError 関数は ERROR_ALREADY_EXISTSを返します。

注釈

名前付きミューテックスを使用してアプリケーションを 1 つのインスタンスに制限している場合、悪意のあるユーザーは、実行する前にこのミューテックスを作成し、アプリケーションの起動を防ぐことができます。 このような状況を回避するには、ランダムに名前が付けられたミューテックスを作成し、承認されたユーザーのみが取得できるように名前を格納します。 または、この目的で ファイルを使用することもできます。 アプリケーションをユーザーごとに 1 つのインスタンスに制限するには、ユーザーのプロファイル ディレクトリにロックされたファイルを作成します。

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

ミューテックス オブジェクトの状態は、どのスレッドも所有していない場合に通知されます。 作成スレッドは dwFlags パラメーターを使用して、ミューテックスの即時所有権を要求できます。 それ以外の場合、スレッドは待機関数のいずれかを使用して所有権を要求する必要があります。 ミューテックスの状態が通知されると、1 つの待機スレッドに所有権が付与され、ミューテックスの状態が非署名に変わり、待機関数が返されます。 特定の時点でミューテックスを所有できるスレッドは 1 つだけです。 所有スレッドは ReleaseMutex 関数を使用してその所有権を解放します。

ミューテックスを所有するスレッドは、実行をブロックすることなく、繰り返し待機関数呼び出しで同じミューテックスを指定できます。 通常は、同じミューテックスを繰り返し待機しませんが、このメカニズムにより、既に所有しているミューテックスを待機している間にスレッド自体がデッドロックするのを防ぐことができます。 ただし、その所有権を解放するには、ミューテックスが待機を満たすたびに、スレッドが ReleaseMutex を 1 回呼び出す必要があります。

2 つ以上のプロセスで CreateMutex を 呼び出して、同じ名前付きミューテックスを作成できます。 最初のプロセスは実際にミューテックスを作成し、十分なアクセス権を持つ後続のプロセスは単に既存のミューテックスへのハンドルを開きます。 これにより、複数のプロセスが同じミューテックスのハンドルを取得しながら、作成プロセスが最初に開始されるようにする責任をユーザーが軽減できます。 この手法を使用する場合は、 CREATE_MUTEX_INITIAL_OWNER フラグを使用しないでください。そうしないと、最初の所有権を持つプロセスを特定するのが難しい場合があります。

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

• CreateProcess 関数によって作成された子プロセスは、CreateMutex の lpMutexAttributes パラメーターで継承が有効になっている場合、ミューテックス オブジェクトへのハンドルを継承できます。 このメカニズムは、名前付きミューテックスと名前なしミューテックスの両方で機能します。
• プロセスでは、 DuplicateHandle 関数の呼び出しでミューテックス オブジェクトへのハンドルを指定して、別のプロセスで使用できる重複するハンドルを作成できます。 このメカニズムは、名前付きミューテックスと名前なしミューテックスの両方で機能します。
• プロセスでは、名前付きミューテックスを [OpenMutex](./nf-synchapi-openmutexw.md) または CreateMutex 関数の呼び出しで指定して、ミューテックス オブジェクトへのハンドルを取得できます。

要件

関連項目

CloseHandle

ミューテックス オブジェクト

同期関数