On success, the return value is a handle to the opened semaphore object. On failure, the function returns NULL_HANDLE. To retrieve extended error information, call the osGetLastError function.

This function opens an existing semaphore object by its name.

Semaphores are synchronization primitives used to manage access to critical sections. A code segment protected by a semaphore-controlled critical section is restricted to execution by no more than a specified number of concurrent tasks.

During semaphore creation, an optional name can be assigned, enabling tasks to obtain a handle to the object via the osOpenSemaphore function. When a semaphore handle is no longer required, it should be closed using osCloseHandle. The semaphore object is deleted only after all tasks that opened the handle have closed it. Further details are available in the system objects management section.

If no osOpen* functions are referenced in the application, the system ignores object names and the name management logic is excluded from the build. This optimization reduces the final binary size. For more information regarding object naming and opening, see the system objects management section.

The returned handle can be used to acquire the semaphore object. For more information regarding semaphore acquisition, please refer to the semaphore objects section.

This function is available only when the OS_USE_SEMAPHORE and OS_OPEN_SEMAPHORE_FUNC configuration constants are set to 1. If this function is not required, set OS_OPEN_SEMAPHORE_FUNC to 0 to reduce the output code size.