SyncCtl(), SyncCtl_r()

Updated: April 19, 2023

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:

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