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

Статья
11/20/2024

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

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

Синтаксис

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

Параметры

[in, optional] lpMutexAttributes

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

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

[in] bInitialOwner

Если это значение TRUE и вызывающий объект создал мьютекс, вызывающий поток получает начальное владение объектом мьютекса. В противном случае вызывающий поток не получает права владения мьютексом. Чтобы определить, создал ли вызывающий объект мьютекс, см. раздел "Возвращаемые значения".

[in, optional] lpName

Имя объекта мьютекса. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.

Если lpName соответствует имени существующего именованного объекта мьютекса, эта функция запрашивает право доступа MUTEX_ALL_ACCESS. В этом случае параметр bInitialOwner игнорируется, так как он уже был задан процессом создания. Если параметр lpMutexAttributes не NULL, он определяет, можно ли наследовать дескриптор безопасности, но его член дескриптора безопасности игнорируется.

Если lpNameNULL, объект мьютекса создается без имени.

Если lpName соответствует имени существующего события, семафора, ожидающего таймера, задания или объекта сопоставления файлов, функция завершается ошибкой, а функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.

Объект можно создать в частном пространстве имен. Дополнительные сведения см. в пространствах имен объектов.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение является дескриптором созданного объекта мьютекса.

Если функция завершается ошибкой, возвращаемое значение равно 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см. в разделе Using Mutex Objects.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	synchapi.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
библиотеки	Kernel32.lib
DLL	Kernel32.dll