Execute a command on another node or tty (BlackBerry 10 OS)
on [-A ability-spec] [-ad | -ae] [-C cpunum] [-d] [-E] [-e key=value] [-h] [-L rlimit:cur[:max]] [-n|f nodename] [-P] [-p priority[policy]] [-R runmask] [-s] [-t tty] [-u uid[:gid[,gid,…] | -u user_name | -l user_name] [-W nsec[:msec]] [-w device] [-Xsched_command] [command [args]]
- -A ability-spec
- Specify an ability to be allowed or disallowed.
The ability-spec argument is a comma-separated list that contains the following, as required,
ignoring the case of the strings:
- the ability identifier, as defined in <sys/procmgr.h>, but omitting the PROCMGR_AID_ prefix (e.g., specify setuid for PROCMGR_AID_SETUID)
- allow or deny
- lock if you want to prevent the process from changing the ability
- root, nonroot, or all to specify the applicable domain
- inherit or noinherit
If the ability accepts a subrange, the above may be followed by 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
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 entry for procmgr_ability() in the BlackBerry 10 OS C Library Reference.
- -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 CPU affinity to cpunum, where the first CPU is 0. You can use this option multiple times. For more information, see Setting the runmask, below.
- 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.
- 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.
- -f nodename
- Spawn from the remote node using the remote node's / as the network root (i.e., search for the executable on the remote node). In contrast, the -n option searches for the executable on the local node. For more details, see The -f vs -n option, below.
- 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, 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 BlackBerry 10 OS C Library Reference.
- -l user_name
- (el) Login as the given user. This option is similar to the -u option, but also sets the LOGNAME, HOME, and SHELL environment variables, and changes to the directory specified for the user in the password database.
- -n nodename
- Execute command (as found on the local node) on the remote nodename. In contrast, the -f option searches for the executable on the remote node. For more details, see The -f vs -n option, below.
- Spawn the process, setting the SPAWN_PADDR64_SAFE flag to indicate that the process is known to operate safely with 64-bit addressing or doesn't care about the physical memory location.
- -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 an effective user ID of 0 (i.e., root) can use them. Non-root (and root) 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).
If you don't specify a command, the change applies to the parent process.
- -R runmask
- Set the CPU 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.
- Spawn the command in a new process group.
- -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.
- -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
on the given device to succeed before continuing.
If device doesn't contain a slash (/),
/dev/ is added to the beginning.
You can repeat the -w and -W options on the command line. They're processed in the order given, before any other options.
- Launch using the specified command for an external scheduler. The possible commands include:
- command [args]
- The command to be executed, and any arguments to be passed to it.
The on utility extends the process creation abilities of the shell (sh). You can start a process on a remote node, on a different controlling terminal, in a HELD state for debugging or later synchronized starting.
If the -d option isn't specified, a network connection is created as a local agent for the remote child process. When the child terminates, the parent must do a wait() on the created connection to reap the zombie process entry for the child. If the -d option is specified, the command is detached from its parent. The parent isn't able to do a wait() for the child, nor is it able to control it via signals.
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.
The -f vs -n option
The -f and -n options look similar, but they're subtly different. To illustrate this, let's consider two nodes, this_node and that_node. On each node, we'll create a copy of the sleep command, appending the node name; on the this_node node, this looks like this:
cp /usr/bin/sleep /tmp/sleep_this_node
Now, let's run the sleep_that_node command with the -f and -n options:
$ on -f /net/that_node /tmp/sleep_that_node 1 $ on -n /net/that_node /tmp/sleep_that_node 1 on: No such file or directory (/tmp/sleep_that_node)
The first command succeeds because we're using /net/that_node as the network root, and that's where sleep_that_node exists. The second command fails because sleep_that_node doesn't exist on our local node.
$ on -f /net/that_node /tmp/sleep_this_node 1 on: No such file or directory (/tmp/sleep_this_node) $ on -n /net/that_node /tmp/sleep_this_node 1
This time, the first command fails because sleep_this_node doesn't exist on /net/that_node. The second command finds sleep_this_node on the local node, and executes it on /net/that_node.
As a more useful example, let's use pidin to get information about the processes running on that_node:
on -f /net/that_node pidin | less
If you use the -n option instead, like this:
on -n /net/that_node pidin | less
you get information about the processes running on this_node, but the command is executed on that_node.
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.
Run sort as an orphan on the node named peterv:
on -d -n peterv sort file.dat
The on utility exits with the exit status of command.