Upon success, the function returns a handle to the created flags object. On failure, it returns NULL_HANDLE. Call the osGetLastError function to retrieve extended error information.

This function creates a flags object.

A flags object is a set of bit-flags typically used to signal the occurrence of various events. The number of available bit-flags depends on the architecture's configuration and is calculated as 8 * sizeof(INDEX). The object is considered to be in a signaled state if at least one bit-flag is set; otherwise, it is in a non-signaled state.

During creation, an optional name may be assigned to the flags object, enabling tasks to open it using the osOpenFlags function. When a flags object is no longer required, it should be closed using osCloseHandle. The flags object is deleted only after it has been closed by all tasks that held an open handle. For further information, refer to the system objects management section.

If all osOpen* functions are disabled in the configuration, the system will ignore object names, and the code dedicated to name management will be excluded from the build. This optimization reduces the final size of the output code. For more information regarding naming and object access, refer to the system objects management section.

The flags are initially set to the values provided in the InitialState parameter. The state of the flags can be modified at any time using osSetFlags to set masked bits to 1, or osResetFlags to reset them to 0. When modifying the flag state, the function returns whether the operation resulted in an actual change (i.e., if the previous state differs from the new state). The current state of all flags can be retrieved at any time using the osGetFlags function.

This function is available only when the OS_USE_FLAGS constant is set to 1.