SyncCtl(), SyncCtl_r()
Perform an operation on a synchronization object
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.
- _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.
- 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.
- In order to attach to a mutex an event that sends a pulse, your process must have the PROCMGR_AID_CONNECTION 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 any value listed in 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
- The synchronization object pointed to by sync doesn't exist, or the ceiling priority value pointed to by data is out of range.
- 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:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |