Функция CreateMutexW (synchapi.h)

Статья
08/26/2023

Создает или открывает именованный или неименованный объект мьютекса.

Чтобы указать маску доступа для объекта, используйте функцию CreateMutexEx .

Синтаксис

HANDLE CreateMutexW(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in]           BOOL                  bInitialOwner,
  [in, optional] LPCWSTR               lpName
);

Параметры

[in, optional] lpMutexAttributes

Указатель на структуру SECURITY_ATTRIBUTES . Если этот параметр имеет значение NULL, дескриптор не может быть унаследован дочерними процессами.

Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового мьютекса. Если lpMutexAttributes имеет значение NULL, мьютекс получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для мьютекса поступают из основного маркера или токена олицетворения создателя. Дополнительные сведения см. в разделе Безопасность объектов синхронизации и права доступа.

[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 по умолчанию. Дополнительные сведения см. в разделе Безопасность объектов синхронизации и права доступа.

Если вы используете именованный мьютекс, чтобы ограничить приложение одним экземпляром, злоумышленник может создать этот мьютекс, прежде чем это сделать, и предотвратить запуск приложения. Чтобы избежать этой ситуации, создайте мьютекс со случайным именем и сохраните имя, чтобы его можно было получить только авторизованным пользователем. Кроме того, для этой цели можно использовать файл. Чтобы ограничить приложение одним экземпляром на пользователя, создайте заблокированный файл в каталоге профиля пользователя.

Любой поток вызывающего процесса может указать дескриптор объекта мьютекса в вызове одной из функций ожидания. Функции ожидания с одним объектом возвращаются при сигнале о состоянии указанного объекта. Функциям ожидания с несколькими объектами можно указать возвращать либо при получении сигнала о каком-либо из них, либо при сигнале всех указанных объектов. При возврате функции ожидания поток ожидания освобождается для продолжения выполнения.

Состояние объекта мьютекса сообщается, если он не принадлежит ни одному потоку. При создании потока можно использовать флаг bInitialOwner , чтобы запросить немедленное владение мьютексом. В противном случае поток должен использовать одну из функций ожидания для запроса владения. Когда состояние мьютекса сигнализируется, одному ожидая потоку предоставляется право владения, состояние мьютекса меняется на незначаемое, а функция ожидания возвращается. Только один поток может владеть мьютексом в любой момент времени. Поток-владелец использует функцию ReleaseMutex для освобождения своего владения.

Поток, владеющий мьютексом, может указать один и тот же мьютекс в повторяющихся вызовах функции ожидания, не блокируя его выполнение. Как правило, вы не будете ждать несколько раз одного и того же мьютекса, но этот механизм предотвращает взаимоблокировку потока при ожидании мьютекса, которым он уже владеет. Тем не менее, чтобы освободить владение, поток должен вызывать ReleaseMutex один раз, чтобы каждый раз, когда мьютекс удовлетворял ожидание.

Два или более процессов могут вызывать CreateMutex для создания одного и того же именованного мьютекса. Первый процесс фактически создает мьютекс, а последующие процессы с достаточными правами доступа просто открывают дескриптор существующего мьютекса. Это позволяет нескольким процессам получать дескриптор одного и того же мьютекса, освобождая при этом пользователя от ответственности за то, чтобы процесс создания был запущен первым. При использовании этого метода необходимо задать для флага bInitialOwnerзначение FALSE; В противном случае может быть трудно определить, какой процесс имеет начальную собственность.

Несколько процессов могут иметь дескриптор одного и того же объекта мьютекса, что позволяет использовать объект для синхронизации между процессами. Доступны следующие механизмы совместного использования объектов:

Дочерний процесс, созданный функцией CreateProcess, может наследовать дескриптор объекта мьютекса, если параметр lpMutexAttributes наследования с поддержкой CreateMutex . Этот механизм работает как для именованных, так и для неименованных мьютексов.
Процесс может указать дескриптор для объекта мьютекса в вызове функции DuplicateHandle , чтобы создать повторяющийся дескриптор, который может использоваться другим процессом. Этот механизм работает как для именованных, так и для неименованных мьютексов.
Процесс может указать именованный мьютекс в вызове функции [OpenMutex](./nf-synchapi-openmutexw.md) или CreateMutex для получения дескриптора объекта мьютекса.

Используйте функцию CloseHandle , чтобы закрыть дескриптор. Система автоматически закрывает дескриптор при завершении процесса. Объект мьютекса уничтожается при закрытии последнего дескриптора.

Примеры

Пример использования CreateMutex см. в разделе Использование объектов мьютекса.

Примечание

Заголовок synchapi.h определяет CreateMutex как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	synchapi.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Библиотека	Kernel32.lib
DLL	Kernel32.dll