SyncCtl(), SyncCtl

Perform an operation on a synchronization object

Note: Don't use the SyncCtl() or SyncCtl_r() kernel call directly; instead, call one of the following:

Instead of this `cmd`:	Call:
_NTO_SCTL_GETPRIOCEILING	pthread_mutex_getprioceiling()
_NTO_SCTL_SETPRIOCEILING	pthread_mutex_setprioceiling()
_NTO_SCTL_SETEVENT	SyncMutexEvent()
_NTO_SCTL_MUTEX_WAKEUP	pthread_mutex_wakeup_np()

Synopsis:

#include <sys/neutrino.h>

int SyncCtl( int cmd,
             sync_t * sync,
             void * data );

int SyncCtl_r( int cmd,
               sync_t * sync,
               void * data );

Arguments:

cmd

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.
Note: You can't use _NTO_SCTL_SETEVENT with a robust mutex (see pthread_mutexattr_setrobust()). The two mechanisms achieve the same goal in different ways.
_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.

sync

A pointer to the synchronization object that you want to manipulate.

data

A pointer to data associated with the command, or a place where the function can store the requested information, depending on the operation.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

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.

Note:

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().

After you set a mutex's priority ceiling, you should not try to lock that mutex from any process that has a priority that's greater than the mutex's priority ceiling. If you attempt this, the mutex locking will fail.

Returns:

The only difference between these functions is the way they indicate errors:

SyncCtl(): If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
If _NTO_SCTL_SETPRIOCEILING was set and the function succeeded, the return value is the previous ceiling priority of the sync mutex.
SyncCtl_r(): On success, this function returns EOK unless _NTO_SCTL_SETPRIOCEILING was set, in which case it returns the previous ceiling priority of the sync mutex.
This function does NOT set errno. If an error occurs, the function returns the negative of a value from the Errors section.

Errors:

EAGAIN

All kernel synchronization event objects are in use.

EFAULT

A fault occurred when the kernel tried to access sync or data.

EINVAL

One of the following occurred:

The synchronization object pointed to by sync doesn't exist.
The ceiling priority value pointed to by data is out of range.
You tried to use _NTO_SCTL_SETEVENT with a robust mutex.

ENOSYS

The SyncCtl() and SyncCtl_r() functions aren't currently supported.

EPERM

The calling process doesn't have the required permission; see procmgr_ability().

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes

SyncCtl(), SyncCtl_r()