QNX Neutrino 7.0 documentation update May 2018

New entries
Changed content
Errata

New entries

MsgRegisterEvent(): Register a secure event
MsgUnregisterEvent(): Unregister a secure event
_NTO_TRACE_GET*(), _NTO_TRACE_SET*(): Macros for working with the header of a trace event
procmgr_session_ext(): Provide process manager session support (an extended version of procmgr_session())
pthread_attr_getsuspendstate_np(): Get the thread suspend state attribute
pthread_attr_setsuspendstate_np(): Set the thread suspend state attribute
_TRACE_GET_STRUCT(): Get the flag from the header of a trace event

Changed content

There's no need to set _NTO_CHF_REPLY_LEN or _NTO_CHF_SENDER_LEN; the kernel sets the dstmsglen and srcmsglen members of the _msg_info structure whether or not you set these flags.

clock_gettime()

In order to get the time for a CPU-time clock associated with another process, your process must now have the PROCMGR_AID_XPROCESS_QUERY ability enabled.

clock_settime()

You now get an error of EPERM instead of EINVAL if you try to set the time for a process or thread CPU-time clock.

ClockCycles()

We now require that the hardware underlying ClockCycles() be synchronized across all processors on an SMP system, so you no longer have to use a runmask for threads to prevent them from migrating to other processors between calls to ClockCycles().

ClockTime()

In order to get the time for a CPU-time clock associated with another process, your process must now have the PROCMGR_AID_XPROCESS_QUERY ability enabled.
You now get an error of EPERM instead of EINVAL if you try to set the time for a process or thread CPU-time clock.

confstr()

There's a new _CS_CONFIG_PATH configuration string. Its value is a colon-separated list of directories to search for configuration files.

ConnectAttach(), ConnectFlags(), ConnectServerInfo()

There's a new _NTO_COF_REG_EVENTS flag that the client can set to prevent the delivery of any sigevents that weren't registered as secure events with MsgRegisterEvent().

creat()

For conformance with POSIX, this function now sets errno to ETXTBSY if the file you're trying to create is a pure procedure (shared text) file that's currently being executed.

execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe()

We've added EMFILE to the list of error codes.

fork()

This function now sets errno to EPERM if the calling process's priority is above the permitted range.

InterruptAttach()

We've added more details about synthetic interrupts.

InterruptAttachEvent()

The ability to attach an interrupt event is now governed by PROCMGR_AID_INTERRUPTEVENT or PROCMGR_AID_INTERRUPT.

InterruptHookTrace()

We've added more details about how to use this function.

kill(), killpg()

If a signal terminates a process, the cleanup of the terminated process occurs by default at the priority of the thread that sent the signal. As a QNX Neutrino extension, if you OR the SIG_TERMER_NOINHERIT flag into the signal number, the cleanup occurs at the priority of the thread that received the signal.

MsgDeliverEvent()

This function gives an error of EACCES if:

you try to deliver an unregistered sigevent to a client that has set _NTO_COF_REG_EVENTS on the connection to indicate that it accepts only events that were registered as secure events with MsgRegisterEvent()
or:
the _NTO_COF_NOEVENT flag is set on the channel

MsgError()

If a server received an unblock pulse, it can now call MsgError() with an error argument of -1. In this case, MsgError() sets the client's errno to whatever error the kernel logged when the unblock pulse was sent.

MsgRead(), MsgReadv(), MsgWrite(), MsgWritev()

The offset argument is now of type size_t.

MsgSendPulse(), MsgSendPulsePtr()

In order to send a pulse to a process, the sending process's effective user ID must match the real, effective, and saved user IDs of the receiving process, or the sending process must have the PROCMGR_AID_CONNECTION ability enabled.

open()

For conformance with POSIX, this function now sets errno to ETXTBSY if the file you're trying to open is a pure procedure (shared text) file that's currently being executed and oflag is O_WRONLY or O_RDWR.

posix_spawn(), posix_spawnp()

These functions now return ENAMETOOLONG if either of the following occurs:

The length of the path argument is greater than PATH_MAX.
An action set with posix_spawn_file_actions_addopen() has a path that's longer than PATH_MAX.

procmgr_ability()

Note that the PROCMGR_AID_PRIORITY ability also controls whether or not priority inheritance can boost a process's threads above the maximum allowed for unprivileged processes.
The PROCMGR_AID_IO ability now has a level for its subrange. A level of 0 lets you call ThreadCtl(_NTO_TCTL_IO, 0); a level of 1 lets you call ThreadCtl(_NTO_TCTL_IO_PRIV, 0).
The subrange for the PROCMGR_AID_XPROCESS_QUERY ability is now effective user IDs instead of process IDs.
The following abilities are new:
- PROCMGR_AID_ABLE_PRIV
- PROCMGR_AID_HIGH_RESOLUTION_TIMER
- PROCMGR_AID_INTERRUPTEVENT
- PROCMGR_AID_XPROCESS_ABLE
- PROCMGR_AID_XPROCESS_DEBUG
- PROCMGR_AID_XPROCESS_MEM_READ
In order to create a timer that sends a pulse to a process belonging to a different user, your process must now have the PROCMGR_AID_CONNECTION ability enabled.

pthread_attr_init()

The default thread attributes now include the following:

When threads are created, they aren't put into a suspended state (PTHREAD_CREATE_NOT_SUSPENDED).

pthread_barrierattr_setpshared(), pthread_condattr_setpshared(), pthread_mutexattr_setpshared(), pthread_rwlockattr_setpshared()

If you started procnto with the -s option, you should set the process-shared attribute to PTHREAD_PROCESS_SHARED for any barriers, condition variables, mutexes and read-write locks that are shared between processes.

pthread_exit()

Any event that you registered for the thread with the _NTO_TCTL_ADD_EXIT_EVENT ThreadCtl() command is delivered when the thread is terminated.

pthread_kill(), sigaction(), signal(), SignalAction(), SignalKill(), SignalKillSigval(), sigqueue()

pthread_mutex_lock()

This function now gives an error of EINVAL if you're using safe shared mutexes, and you tried to lock a priority-impacting mutex whose owner isn't known to the kernel and that the locking thread claims is from a different process.

read()

The maximum value for nbytes is now SSIZE_MAX.

resmgr_msgread(), resmgr_msgreadv(), resmgr_msgwrite(), resmgr_msgwritev()

The size and offset arguments are now of type size_t.

resmgr_msgreplyv()

The iov argument is now defined as const struct iovec *.

rsrcdbmgr_devno_detach()

Note that the process that's detaching the device number must be the process that attached it; otherwise this function sets errno to EINVAL.

SchedCtl()

There's a new SCHED_CONFIGURE command that lets you tune the behavior of the thread scheduler.

setegid(), setgid(), setregid()

A process can set its real or effective group ID to any of its real, effective, or saved set-group IDs or to any ID identified by the PROCMGR_AID_SETGID ability.

seteuid(), setuid(), setreuid()

A process can set its real or effective user ID to any of its real, effective, or saved set-user IDs or to any ID identified by the PROCMGR_AID_SETUID ability.

setrlimit()

There's a new RLIMIT_SIGEVENT_NP resource that limits the maximum number of registered sigevents that a process can have.

shutdown_system(), shutdown_system_with_reason()

These functions now try to call board-specific preshutdown and shutdown functions that you can provide in an optional DLL.

struct sigaction

We've documented the SA_NOCLDWAIT, SA_NODEFER, and SA_RESETHAND flags.

sigevent

This structure has a new sigev_handle member that holds the handle associated with a secure event.

SyncCondvarWait(), SyncCondvarWait_r()

Don't use a recursive mutex with condition variables.

SyncMutexEvent()

In order to use this function with a SIGEV_PULSE sigevent that's going to a channel that was created by a different process whose real, effective, or saved user ID doesn't match your process's effective user ID, your process must have the PROCMGR_AID_CONNECTION ability enabled.

SyncMutexLock()

sysconf()

We've documented _SC_MQ_OPEN_MAX and _SC_MQ_PRIO_MAX.

ThreadCreate()

The following thread flags are new:

PTHREAD_CREATE_NOT_SUSPENDED and PTHREAD_CREATE_SUSPENDED

ThreadCtl()

The following commands are new:
- _NTO_TCTL_ADD_EXIT_EVENT
- _NTO_TCTL_DEL_EXIT_EVENT
In order for you to use the _NTO_TCTL_IO command, you must have the PROCMGR_AID_IO ability enabled with a subrange of 0; in order to use _NTO_TCTL_IO_PRIV, you must have the PROCMGR_AID_IO ability enabled with a subrange of 1.
If you want to use the RDMSR and WRMSR instructions on x86 and x86_64 targets, you must first successfully get I/O privileges with the _NTO_TCTL_IO_PRIV command.
We've expanded the descriptions of _NTO_TCTL_IO and _NTO_TCTL_IO_PRIV.

ThreadDestroy()

Any event that you registered for the thread with the _NTO_TCTL_ADD_EXIT_EVENT ThreadCtl() command is delivered when the thread is terminated.

timer_create(), TimerCreate()

You can now create a timer for a thread CPU-time clock ID. The timeout that you set for this type of timer represents the thread's execution budget.
In order to create a timer that sends a pulse to a process belonging to a different user, your process must now have the PROCMGR_AID_CONNECTION ability enabled.

timer_settime(), timer_timeout(), TimerSettime(), TimerTimeout()

In order to set the timer tolerance to a value between 0 and the clock period, you need to have the PROCMGR_AID_HIGH_RESOLUTION_TIMER ability enabled.

TimerInfo()

If the timer's tolerance is greater than 0 and less than one tick, the flags member of the _timer_info structure now includes the _NTO_TI_HIGH_RESOLUTION bit.

TraceEvent()

The system state information that's logged when you issue an _NTO_TRACE_START command is overwritten when the kernel reuses the buffer; if you're logging events in ring mode, you can make sure you capture the process names by issuing an _NTO_TRACE_START command followed by _NTO_TRACE_STOP after you've finished tracing.
Note that you must issue a _NTO_TRACE_STOP for each _NTO_TRACE_START or _NTO_TRACE_STARTNOSTATE command.
_NTO_TRACE_SETLINEARMODE and _NTO_TRACE_SETRINGMODE cause the trace buffers to be cleared, so you should use these commands before you start tracing.
The linkliststart argument to the _NTO_TRACE_ALLOCBUFFER command is now of type paddr_t *.

uname()

If you're running a safety version of the kernel, the release member of the utsname structure now includes an uppercase “S”.

wordexp(), wordfree()

Because of security concerns, the versions of wordexp() and wordfree() in libc.a are stubs that do nothing, and libc.so doesn't include them at all. We recommend that you not use these functions.

write()

The maximum value for nbytes is now SSIZE_MAX.

Errata

closedir(): This function doesn't give an error of EBADF.
InterruptHookIdle2(): You need to obtain I/O privileges before calling this function. Note that the cmd member of the _idle_hook structure isn't a bit field.
pathmgr_link(): We've corrected the description of this function. You rarely need to call this function directly.
procmgr_event_notify(), procmgr_event_notify_delete(), procmgr_event_trigger(): If an error occurs, these functions return -1 and set errno.
pthread_mutex_lock(), pthread_mutex_timedlock(), pthread_mutex_trylock(), pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust(): The QNX Neutrino implementation of robust mutexes doesn't detect the termination of threads that are holding a robust mutex. The detection of orphan mutexes is restricted to the case where the owner process exits.
pututline(): This function doesn't return anything.
readdir(), readdir_r(): These functions don't give an error of EBADF.
SchedCtl(): We've corrected the descriptions of the SCHED_APS_SEC_FLEXIBLE and SCHED_APS_SEC_BASIC security options.
SignalAction_r(): We've corrected the synopsis for SignalAction_r().
strsignal(): As a QNX Neutrino extension, this function returns a pointer to an empty string if signo isn't a valid signal number or is the number of a QNX Neutrino signal.
thread_pool_control(), thread_pool_limits(): It's now all right to have several threads calling these functions with the same thread pool handle.
trace_logf(), trace_nlogf(), trace_vnlogf(),: It isn't safe to call these functions from a signal handler if the formatting codes or parameters include floating-point elements.
valloc(): You should include <malloc.h>, not <stdarg.h>.