on

Runs on:

QNX OS

Options:

-A ability-spec

Configure an ability. The ability-spec argument is a comma-separated list that contains the following, ignoring the case of the strings:

• either the ability identifier, as defined in <sys/procmgr.h> but omitting the PROCMGR_AID_ prefix (e.g., specify setuid for PROCMGR_AID_SETUID), or able=string or able=numeric_ID to specify a dynamic ability. If you specify a dynamic ability using a string, the utility calls procmgr_ability_lookup() to determine the ability's ID. For this to succeed, the ability must have already been created or on must be running with the PROCMGR_AID_ABLE_CREATE ability enabled.
• one or more of the following operations: allow, deny, lock (if you want to prevent the process from changing the ability), inherit, or noinherit
  You can omit the operations if the ability accepts a subrange and you're configuring it. In this case, the argument string must conclude with a colon and a comma-separated list of subranges, in one of the following forms:

  • two numbers separated by a hyphen (e.g., 4-27)
  • one number followed by a hyphen (e.g., 4- indicates 4 and greater)
  • a single number
• root, nonroot, or all to specify the applicable domain

  Note that the lock, inherit, and noinherit operations apply to the ability as a whole; you can't affect the root and non-root domains independently for any of them.

The operation and domain values map to the flags used by procmgr_ability(); for information about the required and allowed flag combinations, see the ability argument for this function and the list of allowable operation and domain flags. The order of the flag settings doesn't matter, and there are no default settings. For instance, if you don't specify either inherit or noinherit, there's no change to the ability's inheritance setting.

You can specify multiple -A options. For example, to deny forking while running as root, but allow the process to set _CS_HOSTNAME when non-root, specify:

on -A root,deny,fork -A nonroot,allow,confset:2 ...

If you specify allow, deny, lock, root, nonroot, or all without an ability name, the action applies to all abilities not specifically mentioned in another -A option. For more information about abilities, see the procmgr_ability() reference.

If you are using a security policy, use the -T option rather than -A to manage which channels the process may attach to. For information about security policies, see the Security Developer’s Guide.

-ad | -ae

Disable or enable address space layout randomization (ASLR). If you don't specify either of these options, ASLR is left as it currently is.

-C cpunum

Set the processor affinity to cpunum, where the first CPU is 0. You can use this option multiple times. For more information, see Setting the runmask, below.

--critical

Create a critical process (see the POSIX_SPAWN_CRITICAL flag in the entry for posix_spawn()). If a critical process dies, the system crashes.

-d

Detach command from its parent (i.e., sever the parent/child relationship). This is useful for remotely created processes that never exit and that the shell therefore doesn't need to wait for. Unless this option is specified, a network connection is created connecting the parent to the child.

-E

Clear all environment variables, including any preceding -e options.

-e key=value

Define the environment variable key with value value for the child process. You can specify multiple -e options.

-h

Start command in a HELD state. This option is useful for starting up programs with the intention of debugging them. You can also start up several commands in the HELD state, and then send them all a signal to start; they'll all start at almost the exact same time, since their load times will have been eliminated.

-L rlimit:cur[:max]

Specify a limit on a system resource for the child process. The arguments are as follows:

• rlimit — either a textual string (e.g., "freemem") or a numeric value that identifies the rlimit being set; see RLIMIT_* in <sys/resource.h>. The case in the textual string is ignored.
• cur — the rlim_cur field (i.e., the soft limit). It can be a number or "inf" for RLIM_INFINITY.
• max (optional) — the rlim_max field (i.e., the hard limit). It can also be a number or "inf". If you don't specify this limit, it maintains its previous value.

For more information about the limits, see the entry for setrlimit() in the QNX OS C Library Reference.

-p priority[policy]

Execute the command at the specified priority, optionally changing the scheduling policy.

Priorities are in the range from 0 through 255. Priority 0 is used for the idle thread; by default, priorities of 64 and greater are privileged, so only processes with the PROCMGR_AID_PRIORITY ability enabled (see procmgr_ability() in the C Library Reference) can use them. Unprivileged (and privileged) processes can use priorities from 1 through 63.

You can change the range of privileged priorities with the -P option for procnto.

The scheduling policy must be one of:

• f — FIFO
• r — round-robin
• o — other (currently the same as round-robin)
• s:low_priority:max_repl:repl_period:init_budget— Sporadic scheduling. This scheduling policy requires additional, unique parameters.
  • low_priority — The background or low priority for the thread that's executing.
  • max_repl — The maximum number of times a replenishment will be scheduled, typically because of a blocking operation. After a thread has blocked this many times, it automatically drops to the low-priority level for the remainder of its execution until its execution budget is replenished.
  • repl_period — The time, in milliseconds, that should be used for scheduling the replenishment of an execution budget after being blocked or having overrun the maximum number of replenishments. This time is used as an offset against the time that a thread is made READY.
  • init_budget — The time, in milliseconds, that should be used for the thread's execution budget. As the thread runs at its high-priority level, its execution time is carved out of this budget. Once the budget is entirely depleted, the thread drops to its low-priority level, where, if possible because of priority arrangements, it can continue to run until the execution budget is replenished.

If you don't specify a command, the change applies to the parent process.

-R runmask

Set the processor affinity to runmask. You can use this option multiple times to specify masks that are more than 32 bits long. For more information, see Setting the runmask, below.

-S path

Specify the path to the security policy file. The default path and policy file name is /proc/boot/secpol.bin. For more information about security policies, see the Security Developer’s Guide.

-s

Spawn the command in a new process group.

-T type

Runs the command as a given type after looking up the policy for the type in the security policy file; determines its attach rules for the path manager as well as which channels the process may attach to. In this way, the process is launched with respect to policy. Types are defined in the security policy file.

The procmgr ability PROCMGR_AID_SETTYPEID controls the ability of a process to specify a type ID when creating a new process from itself. The procmgr ability PROCMGR_AID_CHANNEL_CONNECT controls attaching/connecting to channels.

For more information about security policies, see the Security Developer’s Guide.

-t tty

Open the specified terminal name as file descriptors 0, 1, and 2 for command. The command is run in a new session with tty as its controlling terminal. If tty doesn't contain a slash (/), /dev/ is added to the beginning.

Note:

The -t option runs the command in background and detaches the spawned child process as per the -d option.

-u uid[:gid[,gid,…]] or -u user_name

Run as the user specified by the numeric uid, in the specified group(s), or as the given user_name.

-W nsec[:msec]

The number of seconds to wait for the device specified in the following -w option. The default is forever.

You can optionally specify a polling interval, in milliseconds. The default is 100 milliseconds.

-w device

Wait for a stat() on the given device to succeed before continuing. If device doesn't contain a slash (/), /dev/ is added to the beginning.

Note:

• You can repeat the -w and -W options on the command line. They're processed in the order given, before any other options.
• If you specify the -w option, on exits with a status of 0 on success, or a nonzero value if a timeout occurred.

-Xsched_cmd

Launch using the specified command for an external scheduler.

command [args]

The command to be executed, and any arguments to be passed to it.

Description:

If you are attempting to launch a process with a non-root userid, you may require additional procmgr abilities within the on command line. For example, you may want to add the abilities to add physical memory and attach an interrupt if you are launching a serial driver with a non-root userid.

By default, the command is run in the current session. The -t option starts a new session, which means the command won't receive a SIGHUP if the current session leader terminates.

Setting the runmask

On a multicore system, you can use a runmask to specify which processors a thread or process can run on. The default is all 1s (i.e., all CPUs).

You can use on to set the runmask and inherit mask for a new process; to change the masks for threads that are already running, use slay. Both commands interpret the -C and -R options in the same way.

You can use more than one -R option to specify a runmask that's more than 32 bits long. The first -R option specifies bits 0 through 31, the second specifies bits 32 through 63, and so on.

If you use both the -C and -R options or multiple instances of them, the resultant mask is the bitwise ORing of all -C and -R options. For example, on -R 0x1 is equivalent to on -C0, and on -R 0x1 -C3 is equivalent to on -C0 -C3. The on command sets the process's runmask and inherit mask to the same value.

For more information about runmasks, see the Multicore Processing chapter of the QNX OS Programmer's Guide.

Examples:

on -T serial_driver_t devc-ser8250

on -t con2 login

on -p200 ksh

Exit status:

The on utility exits with the exit status of command. If you specify the -w option, on exits with a status of 0 on success, or a nonzero value if a timeout occurred.