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

This function opens an existing mutex object by its name.

Mutexes are synchronization primitives used to manage access to critical sections. Code protected by a mutex-controlled critical section is guaranteed to be executed by no more than one task at any given time.

During mutex creation, an optional name can be specified, allowing tasks to obtain a handle to the object via the osOpenMutex function. When a mutex handle is no longer required, it should be closed using osCloseHandle. The mutex 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 request ownership of the mutex object. For more information regarding mutex ownership, please refer to the mutex objects section.

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