procnto*

Updated: October 28, 2024

Microkernel and process manager (QNX Neutrino)

Note: The safety and standard versions of procnto use different default values for some of the command-line options. If you're using the QNX OS for Safety, see the entry for procnto included in Installing and Using the QNX OS for Safety.

Syntax:

procnto* [-a d|e|s] [-bl] [-c clockcycles_offset_max] [-d umask]
         [-F number] [-fa] [-fl] [-h] [-H size] [-mmemmgr_configuration]
         [-n] [-P priority[s]] [-p] [-q string] [-S bytes_after[,bytes_before]]
         [-s] [-T timeout] [-t] [-U] [-u umask] [-v] [-x]

Runs on:

QNX Neutrino

Options:

Note:
  • Some options accept a tilde (~) that clears the boolean value.
  • On all currently supported hardware, misaligned accesses are supported in hardware, so you typically don't need to use the -ad and -ae options.
-ad
Disable alignment fault emulation. The procnto manager doesn't attempt to make misaligned memory accesses work; they'll cause a SIGBUS signal for the offending thread. The -ad option isn't supported on any currently supported platform.
-ae
Enable alignment fault emulation. The procnto manager attempts to make misaligned memory accesses work, although they'll be slow. This isn't guaranteed to work; offending threads may still get a SIGBUS signal.

In QNX Neutrino 6.6 and later on ARMv7 processors, specifying this option allows misaligned accesses to be performed in hardware. On these targets, ThreadCtl(_NTO_TCTL_ALIGN_FAULT, ...) no longer changes the alignment-fault behavior on a per-thread basis.

-as
Use the system default for alignment faults. The default is -ae for all supported platforms.
-bl, -b~l
(QNX Neutrino 7.0.4 or later) The -bl ("el") option specifies that calls to procmgr_ability() that specify locked abilities do not fail. It prevents processes from failing because abilities are being controlled outside of a process (e.g., using a security policy).

For backwards compatibility, specify -b~l to handle these kinds of calls to procmgr_ability() as they were in pre-7.0.4 versions (the default).

In a future release, the -bl option will be the default behavior.

-c clockcycles_offset_max
(QNX Neutrino 7.0.4 or later) The maximum offset (difference) tolerated in the clock cycles of the system's CPUs.

At startup, procnto samples ClockCycles() on each CPU, as simultaneously as possible. The kernel looks at the sample values and determines the maximum offset amongst them. This maximum offset, based on measured samples, may be changed to 0:

  • If the maximum offset is less than 1 microsecond (in equivalent ClockCycles() cycles), procnto considers this to be due to overhead in the cache-coherency protocol, and sets the maximum offset to 0. If verbosity is 1 or more, procnto displays the message “All ClockCycles offsets within tolerance.”
  • If the measured maximum offset is greater than 1 microsecond and the startup has explicitly told us that ClockCycles() is synchronized across all CPUs (QTIME_FLAG_GLOBAL_CLOCKCYCLES is set in the flags for the qtime section of the system page), the kernel sets the maximum offset to be 0.
The kernel then compares the maximum offset to the -c value (which defaults to 0xFFFF'FFFF'FFFF'FFFF); if the maximum offset is greater than this value, procnto displays a message like the following, and then deliberately crashes and produces a kernel dump:
Max ClockCycles offset measured_maximum_offset greater than clockcycles_offset_max
-d umask
(QNX Neutrino 6.6 or later) Use the given file-creation mask (umask) when creating the /proc/pid/cmdline and /proc/pid/ctl files. If you don't specify this option, procnto uses a mask of 0022. Access to these files is governed by a combination of POSIX permissions and process-manager abilities. For more information, see Controlling processes via the /proc filesystem in the “Processes” chapter of the QNX Neutrino Programmer's Guide.
-F number
The maximum number of file descriptors that can be open at the same time. The minimum allowable value is 100. The default value is 1000, but might be constrained by the RLIMIT_NOFILE system resource.
Note: Sockets, named semaphores, and message queues all use file descriptors. Connection IDs (coids) for side channels and server connection IDs (scoids) are returned from a different space than file descriptors, so they don't count towards the limit set by the procnto -F option or RLIMIT_NOFILE.

To determine the current limit, use the ksh builtin command, ulimit, or call getrlimit() (see the QNX Neutrino C Library Reference).

-fa, -~fa
(QNX Neutrino 7.0.3 or later) Preallocate (-fa) or don't preallocate (-~fa) an FPU context structure for every new thread. The default is not to preallocate a context (-~fa).
-fl, -~fl
(QNX Neutrino 7.0.3 or later) Specify the FPU context switch policy:
  • -fl — use the lazy scheme: a thread that starts to run on some processor can incur a fault when making an FPU operation, at which point the FPU register set is loaded. Note that this isn't limited to the first time the thread runs on that processor, but may occur throughout the life of the thread.
  • -~fl — use the eager scheme: when a thread that has an FPU context is scheduled, immediately load the context into the FPU and enable the FPU.

The default is the lazy scheme.

-h, -~h
Disable (-h) or enable (-~h) CPU halting in idle thread. Some CPU and supporting chipsets can lock up if the CPU halts when idle; you'll notice the need for the -h option right away because your system will lock up after booting. The default is to enable CPU halting. Be aware of any errata for your hardware and contact us if you need help working around them.
-H size
Set the initial heap size for procnto. If more memory is required, it's dynamically obtained; however, by setting a properly calculated value, you can speed up boot time and reduce the amount of physical memory fragmentation.

The size parameter indicates the number of bytes to grow the heap in advance. You can postfix this value with a multiplier character, such as “k” (kilobyte) or “m” (megabyte). For example:

1m == 1024k == 0x100000

If the number is less than 1024 and it isn't postfixed by a multiplier character, it's assumed to be in kilobytes. The default value is 512 KB, and the minimum size permitted is 1 KB.

-m memmgr_configuration
Control the behavior of the memory manager. The memmgr_configuration string is a sequence of characters that enable (or if preceded with a ~ character, disable) memory-manager aspects. See Memory configuration,” below.
Note: If you specify more than one -m option, procnto ignores all but the last one, even for characters that differ between the option strings. For example, if you include -mL -m~x on your command line, then procnto ignores the L configuration option and uses only the ~x one.

The same is true if you use the same configuration option more than once within the same -m option. For instance, if you specify -mLxbr~x, then procnto applies the ~x option (the last usage) but not the earlier x option.

-n, -~n
(QNX Neutrino 7.0.4 or later) Use (-n) or don't use (-~n) nonlazy stack allocation. If nonlazy stack allocation is in effect, memory for the stack is reserved when a thread is allocated. Otherwise physical memory for a thread's stack is allocated on demand. The default is -~n.
Note: If nonlazy stack allocation is in effect, you can't use pthread_attr_setstacklazy() to specify a lazy stack. If you want a thread to have a lazy stack, use mmap() with MAP_LAZY to allocate an area for the stack, and then call pthread_attr_setstack().

Assuming that you haven't explicitly allocated a lazy stack, specifying -n guarantees that page faults on stacks won't result in a SIGBUS if the system runs out of memory. When combined with -mL (superlocking), this option ensures that stack memory is prefaulted to the maximum size, which means that there shouldn't be any page faults for (legitimate) access to stack memory.

-P priority[s]
Set the upper end of the range of unprivileged priorities to priority − 1. Priorities range from 0 through 255:
Range Priorities
Idle thread 0
Unprivileged 1 through (priority − 1)
Privileged 1 through 255

In order to run at a priority above the unprivileged range, a process must have the PROCMGR_AID_PRIORITY ability enabled (see procmgr_ability() in the C Library Reference). The default value of priority is 64. If priority is less than 10, procnto uses a value of 10; if priority is greater than 256, it uses a value of 256.

(QNX Neutrino 6.6 or later) You can append an s or S to the priority if you want out-of-range priority requests by default to use the maximum allowed value (reach a “maximum saturation point”) instead of resulting in an error.

-p, -~p
Disable (-p) or enable (-~p) kernel preemption. Disabling kernel preemption prevents threads that are running in kernel space from being preempted by a higher-priority thread. This can be useful when debugging a system with a frequent source of high-priority interrupts. The default is to enable kernel preemption.

This option doesn't interfere with adaptive partitioning because preemption checks are independent of adaptive partitioning and are based strictly on priority.

-q string
Enable file usage restrictions; the string can include one or both of the following characters:
  • s — ignore the setuid or setgid bits of files. The effect is similar to specifying -o nosuid when you mount any filesystem (see mount).
  • t — enable pathtrust.
For more information, see Pathtrust in the System Security Guide.
-S bytes_after[,bytes_before]
(QNX Neutrino 6.6.0 or later) Specify the number of bytes after and (optionally) before the stack pointer to include in a kernel dump. The default values are 128 bytes after and 0 bytes before. If you specify a value that's zero or greater than UINT_MAX, it's ignored. For more information, see the Reading a Kernel Dump technote.
-s, -~s
(QNX Neutrino 7.0.1 or later) Enable (-s) or disable (-~s) safe shared mutexes. The problem with user-mode mutexes is that any thread can claim that any other thread is the owner of the mutex, which, when priority inheritance is applied, means that the latter's priority is boosted to that of the former. A shared mutex is safe if either every lock and unlock call goes through the kernel, or the mutex doesn't impact priority (i.e., it uses the PTHREAD_PRIO_NONE protocol). If you use this option, you should set the process-shared attribute to PTHREAD_PROCESS_SHARED for any barriers, mutexes, and reader/writer locks that are shared between processes. For more information, see Safely sharing mutexes, barriers, and reader/writer locks between processes in the QNX Neutrino Microkernel” chapter of the System Architecture guide.

If you specify the -s option, the kernel rejects any attempts to lock a PTHREAD_PRIO_INHERIT mutex whose owner isn't known to the kernel and that the locking thread claims is from a different process. In this case, pthread_mutex_lock() and SyncMutexLock() give an error of EINVAL.

-T timeout
(QNX Neutrino 6.4.0 or later) Specify the number of seconds to wait for a close() to succeed in the event of a process termination. The default is 30 seconds; if you specify a value of 0, the default is used.

When a process terminates, any outstanding connections are closed. This means that an _IO_CLOSE message is synthesized and sent to the resource manager responsible for that connection.

Because it is not guaranteed that the server will reply in a reasonable amount of time (e.g., a Qnet node may be down), a TimerTimeout() call before the send guarantees that the termination process will proceed.

-t, -~t
(QNX Neutrino 7.0.4 or later) Each thread has a software timer that's used for usleep(), TimerTimeout(), and other blocking operations. If you specify the -t option, this timer is allocated when the thread is created, and the thread isn't created if the timer can't be allocated. If you specify the -~t option, the timer is allocated the first time it's needed. The default is to allocate the timer the first time it's needed (-~t).
-U
(QNX Neutrino 7.1 or later) Allow all processes to use registered and unregistered sigevents. By default, only registered events can be used; see MsgRegisterEvent(). Instead of using this option, you can use the _NTO_COF_UNREG_EVENTS flag when you call ConnectAttach() to allow a specific connection to use registered and unregistered events.

You can detect when processes use unregistered events using secpolgenerate (via the file /dev/ secpolgenerate/errors) or secpolmonitor (when -u is specified).

CAUTION:
_NTO_COF_UNREG_EVENTS and the -U option are temporary workarounds and will be removed in a future version of the OS. Using them allows security vulnerabilities, so don't use them in production systems. You should update your system to use only registered events; the easiest way to do this is to specify the -U option, and then use secpolgenerate to identify the parts of your code that need upgrading to use registered events exclusively.
-u umask
(QNX Neutrino 6.4.0 or later) Use the given file-creation mask (umask) when creating the /proc/pid/as, /proc/pid/exefile, /proc/pid/mappings, /proc/pid/pmap, and /proc/pid/vmstat files. If you don't specify this option, procnto uses a mask of 0066. Access to these files is governed by a combination of POSIX permissions and process-manager abilities. For more information, see Controlling processes via the /proc filesystem in the “Processes” chapter of the QNX Neutrino Programmer's Guide.
-v[v]..., -~v
Be verbose; specifying more v characters increases the verbosity. If you specify the -v option, you'll get more useful information when a process is terminated by a signal. If you specify -~v, verbosity is turned off.
-x
Each thread has a buffer that the kernel can use when passing “small” messages. By default each of these buffers is 256 bytes. If you specify the -x option, each buffer is extended to be 2 KB (less some overhead), which avoids the overhead of “long” message passing and hence improves performance.

Description:

The procnto system process contains the microkernel, process management, memory management and pathname management. It's required in all bootable images made using the mkifs utility. For more information, see the QNX Neutrino System Architecture guide.

There are different versions of procnto for different processors (see the Board Support Package for your board for specific information). The most common version is procnto-smp-instr, which runs on single- or multicore systems and is instrumented for system analysis. For more information, see the System Analysis Toolkit User's Guide and the Analyzing Performance chapter of the IDE User's Guide.

Note:
  • To determine the release version of the kernel on your system, use the uname -a command.

    (QNX Neutrino 7.0.1 or later) If you're running a safety version of the kernel, the release level includes an uppercase “S”.

  • You can use the appropriate startup-* command's -P option to specify the maximum number of CPUs to activate.

The kernel also manages named semaphores, which appear in the pathname space under /dev/sem. The sem_* client functions handle named semaphores; for more information, see the QNX Neutrino C Library Reference.

Memory configuration options

The memory configuration characters that you can specify with the -m option include the following:

b, ~b
Enable (b) or disable (~b) backward compatibility. The default is to enable it (b).
Note: For details about what backward compatibility includes, see the release notes.
g, ~g
(QNX Neutrino 6.6 or later) Add (g) or don't add (~g) a guard page before any shared memory allocations. The default is not to add one (~g).
l, ~l
(“el”) Lock (l) or don't lock (~l) all memory. Locking all memory acts as if mlockall(MCL_CURRENT|MCL_FUTURE) were specified at the start of every program. For more information, see mlockall() in the QNX Neutrino C Library Reference. The default is not to lock all memory (~l).
L, ~L
Lock and superlock (L) or don't lock and superlock (~L) all memory. Locking and superlocking all memory acts as if ThreadCtl(_NTO_TCTL_IO,0) were specified at the start of every program (but only insofar as locking the memory; programs don't actually get I/O privileges). For more information, see Locking memory in the “Process Manager” chapter of the System Architecture guide. The default is not to lock and superlock all memory (~L).

The L option is a superset of the l option. You can combine them, but they're processed in the order that you specify them, resulting in different combinations of locking and superlocking:

Options Locked? Superlocked?
lL Yes Yes
l~L No No
~lL Yes Yes
~l~L No No
Ll Yes Yes
L~l Yesa Yes
~Ll Yes No
~L~l No No

a In QNX Neutrino 7.0.4 or later, you can't turn off locking if superlocking is in effect.

r, ~r
(QNX Neutrino 6.5.0 or later; not supported by the QNX Neutrino RTOS Safe Kernel 1.0) Use (r) or don't use (~r) address space layout randomization (ASLR) by default. If you use ASLR, the kernel places certain items (e.g., the stack, libc) at different addresses every time you run a process. This can help prevent someone from hacking into a program.

In QNX Neutrino 7.1 or later, the default is to use ASLR (r).

A child process normally inherits its parent's ASLR setting. You can use the on command, or posix_spawnattr_setaslr() to change this setting for a new process.

X, ~X
(QNX Neutrino 6.6 or later) Disallow (X) or allow (~X) mmap() or mprotect() to turn on PROT_EXEC for a memory-mapped file mapping if the file doesn't have execute permission for the client process. If you specify X, such attempts result in an error of EACCES. The default is to allow it (~X).
x, ~x
(QNX Neutrino 7.1 or later) These options no longer have any effect; by default, a binary's stack isn't executable, but you can use the elfnote utility to change this.

The /proc filesystem

The Process Manager component of procnto implements a /proc virtual filesystem that lets you access and control the processes and threads running in the system.

CAUTION:
This interface is intended for gathering information and debugging. Don't use it in production systems to control the behavior of processes and threads.

The /proc virtual filesystem includes the following:

/proc/pid/
Virtual directories that let you access and control every process and thread running within the system. For more information, see Controlling processes via the /proc filesystem in the “Processes” chapter of the QNX Neutrino Programmer's Guide.
/proc/boot/
The image filesystem that comprises the boot image. For more information, see OS Images in Building Embedded Systems.
/proc/config
(QNX Neutrino 7.0.1 or later) A virtual file that summarizes the configuration settings for procnto. Here's some sample output:
# cat /proc/config
align_fault:off
fd_close_timeout:30
fpustate:4
ker_verbose:1
maxfds:1000
nohalt:0
nonlazy_stack:0
nopreempt:0
pregrow_size:524288
priv_prio.prio:64
priv_prio.saturate:0
procfs_ctl_umask:0777
procfs_umask:0777
shutdown_stack_len:128/0
safe_shared_mutexes:0
thread_timer_prealloc:0
clockcycles_offset_max:0xFFFFFFFFFFFFFFFF
allow_unregistered_events:0
proc_thread_pool:3,10,75
thread_stack_prot:EXEC
mm_cleanup_prio:10
mmflags:0x201 (BACKWARDS_COMPAT,RANDOMIZE)
  

The settings correspond to the command-line options as follows:

Field Option Description
align_fault -ad, -ae, -as Indicates whether unaligned accesses cause a fault; off or on. Disabling unaligned access emulation with the command-line option enables the generation of a fault on an unaligned access.
fd_close_timeout -T The time, in seconds, to wait for a close() to succeed in the event of a process termination
fpustate -f* Floating-point flags; see below
ker_verbose -v The verbosity level
maxfds -F The maximum number of file descriptors that can be open at the same time
nohalt -h, -~h Whether or not CPU halting is disabled in the idle thread; 0 or 1
nonlazy_stack -n (QNX Neutrino 7.0.4 or later) Whether or not nonlazy stack allocation is being used; 0 or 1
nopreempt -p Whether or not kernel preemption is disabled; 0 or 1
pregrow_size -H The initial heap size for procnto, in bytes
priv_prio.prio -P The lower end of the range of privileged priorities
priv_prio.saturate -P Whether or not out-of-range priority requests use the maximum allowed value (reach a “maximum saturation point”) instead of resulting in an error
procfs_ctl_umask -d The file-creation mask, in octal, used for the /proc/pid/ctl entries
procfs_umask -u The file-creation mask, in octal, used for the /proc/pid/as entries
shutdown_stack_len -S The number of bytes after and before the stack pointer to include in a kernel dump
safe_shared_mutexes -s Whether or not the kernel rejects any attempts to lock priority-impacting mutexes whose owner isn't known to the kernel and that the locking thread claims is from a different process; 0 or 1
thread_timer_prealloc -t Whether the kernel allocates a thread's software timer when the thread is created (1), or the first time the timer is needed (0)
clockcycles_offset_max -c The maximum offset (difference) tolerated in the clock cycles of the system's CPUs
allow_unregistered_events -U Whether unregistered events are allowed (1) or not allowed (0) by default
proc_thread_pool None; see the PROC_THREAD_POOL environment variable The configuration of procnto's thread pool, including the low-water mark, high-water mark, and maximum number of threads
thread_stack_prot -mx, -m~x Whether or not the PROT_EXEC flag is enabled for system-allocated threads; EXEC or NOEXEC

The fpustate field indicates which FPU flags are set. These include the following:

Bit Option Description
0x1 The CPU_FLAG_FPU bit isn't set on at least one core (i.e., at least one core has no floating-point unit)
0x4 -fl, -~fl The lazy FPU context switch policy is enabled
0x8 -fa, -~fa An FPU context structure is preallocated for every new thread

The mmflags field indicates which memory-management flags are set. You can use the -m command-line option to set some. The flags include the following:

Flag Option Description
BACKWARDS_COMPAT -mb Backward compatibility is enabled
CACHEOP_NOCACHE None Because of a specific chip erratum, cache operations can't be done on non-cacheable memory
LOCKALL -ml, -mL All memory is locked
RANDOMIZE -mr Address space layout randomization (ASLR) is being used
REQUIRE_EXEC -mX Any attempts by mmap() or mprotect() to turn on PROT_EXEC for a memory-mapped file mapping fail if the file doesn't have execute permission for the client process
SHMEM_GUARD -mg Add a guard page before any shared memory allocations
SUPERLOCKALL -mL All memory is superlocked
/proc/dumper
A special entry that receives notification when a process terminates abnormally. The dumper utility watches this entry.
/proc/mount/
Pathname-space mountpoints.
Note: If you list the contents of the /proc directory, /proc/mount doesn't show up, but you can list the contents of /proc/mount.
/proc/qnetstats
If you're using Transparent Distributed Processing (TDP), the lsm-qnet.so module places a qnetstats entry in /proc. If you open this name and read from it, the Qnet resource manager code responds with the current statistics for Qnet.
/proc/self/
The address space for yourself (i.e., for the process that's making the query).
/proc/vm/stats
A global view of the state of virtual memory in the system.

Examples:

To disable preemption in kernel code:

procnto-smp-instr -p

Environment variables:

PROC_THREAD_POOL= low[,high[,max]]
(QNX Neutrino 7.0.4 or later) Specify the configuration of procnto's thread pool. You must specify the low-water mark, and you can optionally include the high-water mark and maximum number of threads. If the values are invalid, they're ignored. The default values are 3, 10, and 75, respectively.