Función CreateSemaphoreW (synchapi.h)

Artículo
11/20/2024

Crea o abre un objeto de semáforo con nombre o sin nombre.

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

Sintaxis

HANDLE CreateSemaphoreW(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCWSTR               lpName
);

Parámetros

[in, optional] lpSemaphoreAttributes

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 el nuevo semáforo. Si este parámetro es NULL, el semáforo obtiene un descriptor de seguridad predeterminado. Las ACL del descriptor de seguridad predeterminado para un semáforo proceden del token principal o de suplantación del creador.

[in] lInitialCount

Recuento inicial del objeto de semáforo. Este valor debe ser mayor o igual que cero y menor o igual que lMaximumCount. El estado de un semáforo se señala cuando su recuento es mayor que cero y no asignado cuando es cero. El recuento se reduce en uno cada vez que una función de espera libera un subproceso que estaba esperando el semáforo. El recuento aumenta en una cantidad especificada llamando a la función releaseSemaphore de .

[in] lMaximumCount

Recuento máximo del objeto de semáforo. Este valor debe ser mayor que cero.

[in, optional] lpName

Nombre del objeto de semáforo. 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 semáforo con nombre existente, esta función solicita el derecho de acceso SEMAPHORE_ALL_ACCESS. En este caso, los parámetros lInitialCount y lMaximumCount se omiten porque ya se han establecido mediante el proceso de creación. Si el parámetro lpSemaphoreAttributes 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 semáforo se crea sin un nombre.

Si lpName coincide con el nombre de un evento existente, una exclusión mutua, un temporizador de espera, un trabajo o un objeto de asignación de archivos, se produce un error en la función, 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 semáforo. Si el objeto de semáforo con nombre existía antes de la llamada a la función, la función devuelve un identificador al objeto existente y GetLastError devuelve ERROR_ALREADY_EXISTS.

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

Observaciones

El identificador devuelto por CreateSemaphore tiene el derecho de acceso SEMAPHORE_ALL_ACCESS; se puede usar en cualquier función que requiera un identificador para un objeto de semáforo, siempre que se haya concedido acceso al autor de la llamada. Si se crea un semáforo a partir de un servicio o un subproceso que suplanta a un usuario diferente, puede aplicar un descriptor de seguridad al semáforo 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.

El estado de un objeto de semáforo se señala cuando su recuento es mayor que cero y no se asigna cuando su recuento es igual a cero. El parámetro lInitialCount especifica el recuento inicial. El recuento nunca puede ser menor que cero o mayor que el valor especificado en el parámetro lMaximumCount.

Cualquier subproceso del proceso de llamada puede especificar el identificador del objeto de semáforo 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. Cada vez que un subproceso completa una espera para un objeto de semáforo, el recuento del objeto de semáforo se disminuye en uno. Cuando el subproceso ha finalizado, llama a la función releaseSemaphore , que incrementa el recuento del objeto de semáforo.

Varios procesos pueden tener identificadores del mismo objeto de semáforo, 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 semáforo si el lpSemaphoreAttributes parámetro de CreateSemaphore herencia habilitada.
Un proceso puede especificar el identificador de objeto de semáforo en una llamada a la función DuplicateHandle para crear un identificador duplicado que otro proceso pueda usar.
Un proceso puede especificar el nombre de un objeto de semáforo en una llamada a la función OpenSemaphore o CreateSemaphore.

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

Ejemplos

Para obtener un ejemplo que usa CreateSemaphore, vea Using Semaphore Objects.

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)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll