Perform an operation on a synchronization object
Don't use the SyncCtl() or SyncCtl_r() kernel call directly; instead, call one of the following:
#include <sys/neutrino.h> int SyncCtl( int cmd, sync_t * sync, void * data ); int SyncCtl_r( int cmd, sync_t * sync, void * data );
- The operation type; one of:
- _NTO_SCTL_GETPRIOCEILING — get the ceiling priority of the mutex pointed to by sync and put it in the variable pointed to by data.
- _NTO_SCTL_SETPRIOCEILING — return the original ceiling priority. Set the ceiling priority of the mutex pointed to by sync to the value pointed to by data.
- _NTO_SCTL_SETEVENT — attach an event, pointed to by data, to the mutex pointed to by sync.
- _NTO_SCTL_MUTEX_WAKEUP — wake up threads that are blocked on a mutex. The data argument points to a structure that specifies the process and thread IDs.
- A pointer to the synchronization object that you want to manipulate.
- A pointer to data associated with the command, or a place where the function can store the requested information, depending on the operation.
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The SyncCtl() and SyncCtl_r() kernel calls let you:
- set or get a ceiling priority for a mutex
- attach an event to a mutex so you'll be notified when the mutex changes to the DEAD state
- wake up threads that are blocked on a mutex
These functions are similar, except for the way they indicate errors. See the Returns section for details.
In order to change the priority ceiling to a value above the maximum permitted for unprivileged processes, your process must have the PROCMGR_AID_PRIORITY ability enabled. For more information, see procmgr_ability().
The only difference between these functions is the way they indicate errors:
- If an error occurs, the function returns -1 and sets errno . Any other value returned indicates success.
- Returns EOK on success. This function does NOT set errno. If an error occurs, the function returns any value listed in the Errors section.
- All kernel synchronization event objects are in use.
- A fault occurred when the kernel tried to access sync or data.
- The synchronization object pointed to by sync doesn't exist, or the ceiling priority value pointed to by data is out of range.
- The SyncCtl() and SyncCtl_r() functions aren't currently supported.
- The calling process doesn't have the required permission; see procmgr_ability().
Last modified: 2014-06-24