ThreadCtl(), ThreadCtl_r()

Control a thread

Synopsis:

#include <sys/neutrino.h>

int ThreadCtl( int cmd, 
               void * data );

int ThreadCtl_r( int cmd, 
                 void * data );

Arguments:

cmd

The command you want to execute; see below.

data

A pointer to data associated with the specific command; see below.

Library:

libc

Description:

These kernel calls allow you to make QNX-specific changes to a thread.

The ThreadCtl() and ThreadCtl_r() functions are identical except in the way they indicate errors. See the Returns section for details.

The following calls are defined:

ThreadCtl(_NTO_TCTL_ALIGN_FAULT, data)

Control the misaligned access response. The data argument is a pointer to an int whose value indicates how you want to respnd:

• Greater than 0 -- make a misaligned access fault with a SIGBUS, if the architecture permits it.
• Less than 0 -- make the kernel attempt to emulate an instruction with a misaligned access. If the attempt fails, it also faults with a SIGBUS.
• 0 -- don't change the alignment-fault handling for the thread.

The function sets data to a positive or negative number, indicating the previous state of the the alignment-fault handling.

ThreadCtl(_NTO_TCTL_IO, 0)

Request I/O privity; let the thread execute the I/O opcodes in, ins, out, outs, cli, sti on architectures where it has the appropriate privilege, and let it attach IRQ handlers. You need root permissions to use this command. If a thread attempts to use these opcodes without successfully executing this call, the thread faults with a SIGSEGV when the opcode is attempted.

---

Threads created by the calling thread inherit the _NTO_TCTL_IO status.

---

ThreadCtl(_NTO_TCTL_RUNMASK, (int)runmask)

Set processor affinity for the calling thread in a multiprocessor system. Each set bit in runmask represents a processor that the thread can run on.

By default, a thread's runmask is set to all ones, which allows it to run on any available processor. A value of 0x01 would, for example, force the thread to only run on the first processor.

You can use _NTO_TCTL_RUNMASK to optimize the runtime performance of your system by, for example, relegating nonrealtime threads to a specific processor. In general, this shouldn't be necessary, since the QNX realtime scheduler always preempts a lower-priority thread immediately when a higher priority thread becomes ready.

The main effect of processor locking is the effectiveness of the CPU cache, since threads can be prevented from migrating.

---

Threads created by the calling thread don't inherit the _NTO_TCTL_RUNMASK status.

---

ThreadCtl(_NTO_TCTL_THREADS_CONT, 0)

Unfreeze all threads in the current process that were frozen using the _NTO_TCTL_THREADS_HOLD command.

ThreadCtl(_NTO_TCTL_THREADS_HOLD, 0)

Freeze all threads in the current process except the calling thread.

---

Threads created by the calling thread aren't frozen.

---

The data pointer is reserved for passing extra data for new commands that may be introduced in the future.

Blocking states

These calls don't block.

Returns:

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

ThreadCtl()

If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.

ThreadCtl_r()

EOK is returned on success. This function does NOT set errno. If an error occurs, any value in the Errors section may be returned.

Errors:

EPERM

The process doesn't have superuser capabilities.

Classification:

QNX 6

See also:

InterruptDisable(), InterruptEnable(), InterruptMask(), InterruptUnmask()