Función CreateMutexW (synchapi.h)

Artículo
11/20/2024

Crea o abre un objeto de exclusión mutua con nombre o sin nombre.

Para especificar una máscara de acceso para el objeto, use la función CreateMutexEx.

Sintaxis

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

Parámetros

[in, optional] lpMutexAttributes

Puntero a una estructura SECURITY_ATTRIBUTES. Si este parámetro es NULL, los procesos secundarios no pueden heredar el identificador.

El lpSecurityDescriptor miembro de la estructura especifica un descriptor de seguridad para la nueva exclusión mutua. Si lpMutexAttributes es NULL, la exclusión mutua obtiene un descriptor de seguridad predeterminado. Las ACL del descriptor de seguridad predeterminado para una exclusión mutua proceden del token principal o de suplantación del creador. Para obtener más información, vea Seguridad de objetos de sincronización y derechos de acceso.

[in] bInitialOwner

Si este valor es TRUE y el autor de la llamada creó la exclusión mutua, el subproceso que realiza la llamada obtiene la propiedad inicial del objeto de exclusión mutua. De lo contrario, el subproceso que realiza la llamada no obtiene la propiedad de la exclusión mutua. Para determinar si el autor de la llamada creó la exclusión mutua, consulte la sección Valores devueltos.

[in, optional] lpName

Nombre del objeto de exclusión mutua. El nombre está limitado a MAX_PATH caracteres. La comparación de nombres distingue mayúsculas de minúsculas.

Si lpName coincide con el nombre de un objeto de exclusión mutua con nombre existente, esta función solicita el derecho de acceso MUTEX_ALL_ACCESS. En este caso, el parámetro bInitialOwner se omite porque ya lo ha establecido el proceso de creación. Si el parámetro lpMutexAttributes no es NULL, determina si se puede heredar el identificador, pero se omite su miembro de descriptor de seguridad.

Si lpName es null, el objeto de exclusión mutua se crea sin un nombre.

Si lpName coincide con el nombre de un evento existente, semáforo, temporizador de espera, trabajo o objeto de asignación de archivos, se produce un error en la función y la función GetLastError devuelve ERROR_INVALID_HANDLE. Esto ocurre porque estos objetos comparten el mismo espacio de nombres.

El nombre puede tener un prefijo "Global" o "Local" para crear explícitamente el objeto en el espacio de nombres global o de sesión. El resto del nombre puede contener cualquier carácter excepto el carácter de barra diagonal inversa (\). Para obtener más información, vea espacios de nombres de objeto kernel. El cambio rápido de usuario se implementa mediante sesiones de Terminal Services. Los nombres de objeto de kernel deben seguir las directrices descritas para Terminal Services para que las aplicaciones puedan admitir varios usuarios.

El objeto se puede crear en un espacio de nombres privado. Para obtener más información, vea Espacios de nombres de objeto.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador del objeto de exclusión mutua recién creado.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Si la exclusión mutua es una exclusión mutua con nombre y el objeto existía antes de esta llamada de función, el valor devuelto es un identificador del objeto existente y la función GetLastError devuelve ERROR_ALREADY_EXISTS.

Observaciones

El identificador devuelto por CreateMutex tiene el derecho de acceso MUTEX_ALL_ACCESS; se puede usar en cualquier función que requiera un identificador para un objeto de exclusión mutua, siempre que se haya concedido acceso al autor de la llamada. Si se crea una exclusión mutua a partir de un servicio o un subproceso que suplanta a un usuario diferente, puede aplicar un descriptor de seguridad a la exclusión mutua al crearlo o cambiar el descriptor de seguridad predeterminado para el proceso de creación cambiando su DACL predeterminada. Para obtener más información, vea Seguridad de objetos de sincronización y derechos de acceso.

Si usa una exclusión mutua con nombre para limitar la aplicación a una sola instancia, un usuario malintencionado puede crear esta exclusión mutua antes de hacerlo e impedir que la aplicación se inicie. Para evitar esta situación, cree una exclusión mutua con nombre aleatorio y almacene el nombre para que un usuario autorizado solo pueda obtenerlo. Como alternativa, puede usar un archivo para este propósito. Para limitar la aplicación a una instancia por usuario, cree un archivo bloqueado en el directorio de perfil del usuario.

Cualquier subproceso del proceso de llamada puede especificar el identificador de objeto de exclusión mutua en una llamada a una de las funciones de espera de . Las funciones de espera de un solo objeto devuelven cuando se señala el estado del objeto especificado. Se pueden indicar a las funciones de espera de varios objetos que devuelvan cuando se indique cualquiera o cuando se señalen todos los objetos especificados. Cuando se devuelve una función de espera, se libera el subproceso en espera para continuar su ejecución.

El estado de un objeto de exclusión mutua se señala cuando no es propiedad de ningún subproceso. El subproceso de creación puede usar la marca de bInitialOwner para solicitar la propiedad inmediata de la exclusión mutua. De lo contrario, un subproceso debe usar una de las funciones de espera para solicitar la propiedad. Cuando se señala el estado de la exclusión mutua, se concede propiedad a un subproceso en espera, el estado de la exclusión mutua cambia a no asignado y la función wait devuelve. Solo un subproceso puede poseer una exclusión mutua en un momento dado. El subproceso propietario usa la función releaseMutex de para liberar su propiedad.

El subproceso propietario de una exclusión mutua puede especificar la misma exclusión mutua en llamadas a funciones de espera repetidas sin bloquear su ejecución. Normalmente, no esperaría repetidamente a la misma exclusión mutua, pero este mecanismo impide que un subproceso se interbloquee mientras espera una exclusión mutua que ya posee. Sin embargo, para liberar su propiedad, el subproceso debe llamar a ReleaseMutex una vez por cada vez que la exclusión mutua satisface una espera.

Dos o más procesos pueden llamar a CreateMutex para crear la misma exclusión mutua con nombre. El primer proceso crea realmente la exclusión mutua y los procesos posteriores con derechos de acceso suficientes simplemente abren un identificador a la exclusión mutua existente. Esto permite que varios procesos obtengan identificadores de la misma exclusión mutua, a la vez que alivian al usuario de la responsabilidad de garantizar que el proceso de creación se inicie primero. Al usar esta técnica, debe establecer la marca bInitialOwner en FALSE; de lo contrario, puede ser difícil ser cierto qué proceso tiene propiedad inicial.

Varios procesos pueden tener identificadores del mismo objeto de exclusión mutua, lo que permite el uso del objeto para la sincronización entre procesos. Están disponibles los siguientes mecanismos de uso compartido de objetos:

Un proceso secundario creado por la función createProcess puede heredar un identificador a un objeto de exclusión mutua si el lpMutexAttributes parámetro de herencia habilitada CreateMutex. Este mecanismo funciona para las exclusión mutuas con nombre y sin nombre.
Un proceso puede especificar el identificador de un objeto de exclusión mutua en una llamada a la función DuplicateHandle para crear un identificador duplicado que otro proceso pueda usar. Este mecanismo funciona para las exclusión mutuas con nombre y sin nombre.
Un proceso puede especificar una exclusión mutua con nombre en una llamada a la función [OpenMutex](./nf-synchapi-openmutexw.md) o función CreateMutex para recuperar un identificador al objeto de exclusión mutua.

Use la función CloseHandle para cerrar el identificador. El sistema cierra el identificador automáticamente cuando finaliza el proceso. El objeto de exclusión mutua se destruye cuando se ha cerrado su último identificador.

Ejemplos

Para obtener un ejemplo que usa CreateMutex, vea Using Mutex Objects.

Nota

El encabezado synchapi.h define CreateMutex como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	synchapi.h (incluya Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll