Switch the Active X Pointer Safely with xsetpointer

You will use xsetpointer to inspect the X Input devices visible to your session, make one device the main pointer, and restore core pointer events if you temporarily disabled them. This is a session-level change, not a system configuration change.

Allow about ten minutes. You need the x11-xserver-utils package, a running X server, and permission to connect to that server. These examples use the installed package version 7.7+10build2. Wayland-only sessions are outside this command's scope.

1. Confirm the command and display

Check which executable will run, then inspect the display variable used by your shell:

$ command -v xsetpointer
/usr/bin/xsetpointer
$ printf 'DISPLAY=%s\n' "${DISPLAY-}"

The second line is host-specific. It should contain the display name for your active X session, often something like :0. If it is empty, do not guess a value. Run the command from a terminal that belongs to the X session, or set DISPLAY and the matching X authorisation in the same way your desktop session does.

Checkpoint: a missing or incorrect DISPLAY prevents every useful xsetpointer operation. On this machine, running xsetpointer -l without an X display produces unable to connect to X Server try to set the DISPLAY variable and exits with status 1.

2. List the available input devices

Ask the X server for its device names:

$ xsetpointer -l
# device lines are supplied by your X server
$ printf 'exit status: %s\n' "$?"
exit status: 0

The output is deliberately not shown as a fixed list. Device names depend on the server, drivers and hardware attached to this session. Copy the exact name of the device you want from this output. Do not substitute a Linux path such as /dev/input/event0; xsetpointer expects an X Input device name.

The -l option only lists devices. It does not select one. If the command fails, return to step 1 and fix the display connection before changing anything.

3. Select one device as the main pointer

Pass the exact X device name as the sole operand. Quote it because names can contain spaces or punctuation:

$ xsetpointer 'EXACT DEVICE NAME FROM -l'
$ printf 'exit status: %s\n' "$?"
exit status: 0

Replace EXACT DEVICE NAME FROM -l with a real name. A successful status means the request was accepted by the X server. The command does not print a success message, so the exit status is the useful checkpoint.

Move the physical device or click in a harmless area to check the result. If the wrong device became active, run step 2 again, choose the intended name, and repeat this step. There is no universal undo name: restoring the previous device requires the previous name from your notes or from the device list.

4. Understand core pointer events

Some X servers implement a virtual core pointer. For those servers, -c disables the sending of core input events and +c enables it again:

$ xsetpointer -c
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ xsetpointer +c
$ printf 'exit status: %s\n' "$?"
exit status: 0

These are state-changing commands. Disabling core events can make ordinary pointer-driven desktop controls stop receiving input. Use -c only when you have a specific test or compatibility reason, and keep the recovery command xsetpointer +c ready before you begin. The option affects servers that implement a virtual core pointer; it is not a general switch for every input stack.

5. Keep the change temporary and reviewable

xsetpointer changes the live X server state. The manpage does not describe a configuration file, boot setting or persistent profile for this command. Treat a successful selection as a change to the current session, and do not put an unreviewed device name into a login script or desktop startup file.

For a script, check the command's status and keep device names as explicit data:

device_name='EXACT DEVICE NAME FROM -l'
if xsetpointer "$device_name"; then
    printf 'main pointer request accepted\n'
else
    status=$?
    printf 'xsetpointer failed with status %s\n' "$status" >&2
    exit "$status"
fi

Do not parse a guessed line number from -l, and do not treat a command that cannot connect to the X server as a device-selection failure. Those are separate problems with different fixes.

6. Diagnose the common failures

If xsetpointer -l reports that it cannot connect, check DISPLAY and X authorisation from the same terminal context as the desktop. If the device is absent from the list, the X server has not exposed that device under the name you supplied. Check the session type and input-device setup before trying a different spelling.

If a quoted name still fails, copy it again from the current list. Hardware can disappear between listing and selection, especially after a receiver is unplugged. Avoid repeatedly selecting devices while troubleshooting a live desktop, because each successful request changes where pointer events are directed.

There is no need for elevated privileges for listing, selection or toggling core events. If a desktop policy prevents access to the X server, address that policy through the session's normal administration process. Do not weaken access controls by exposing the display to other users.