CreateMutexA 関数 (synchapi.h)

[アーティクル]
03/08/2023

名前付きまたは名前のないミューテックスオブジェクトを作成または開きます。

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

構文

HANDLE CreateMutexA(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in]           BOOL                  bInitialOwner,
  [in, optional] LPCSTR                lpName
);

パラメーター

[in, optional] lpMutexAttributes

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

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

[in] bInitialOwner

この値が TRUE で 、呼び出し元がミューテックスを作成した場合、呼び出し元のスレッドはミューテックスオブジェクトの初期所有権を取得します。それ以外の場合、呼び出し元のスレッドはミューテックスの所有権を取得しません。呼び出し元がミューテックスを作成したかどうかを確認するには、「戻り値」セクションを参照してください。

[in, optional] lpName

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

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

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

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

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

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

戻り値

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

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

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

注釈

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

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

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

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

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

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

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

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

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

例

CreateMutex の例については、「ミューテックスオブジェクトの使用」を参照してください。

注意

synchapi.h ヘッダーは、CreateMutex をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

CreateMutexA 関数 (synchapi.h)

構文

パラメーター

戻り値

注釈

例

要件

関連項目

フィードバック

フィードバック

その他のリソース