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

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.
SyncCtl_r(): Returns EOK on success. 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()