--- name: "sysmouse" section: "4" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/sysmouse" --- # sysmouse(4) virtualized mouse driver ## NAME **sysmouse** – virtualized mouse driver ## SYNOPSIS **#include \** **#include \** ## DESCRIPTION The console driver, in conjunction with the mouse daemon [moused(8)](/moused/8.md), supplies mouse data to the user process in the standardized way via the **sysmouse** driver. This arrangement makes it possible for the console and the user process (such as the X Window System) to share the mouse. The user process which wants to utilize mouse operation simply opens */dev/sysmouse* with a [open(2)](/open/2.md) call and reads mouse data from the device via [read(2)](/read/2.md). Make sure that [moused(8)](/moused/8.md) is running, otherwise the user process will not see any data coming from the mouse. ### Operation Levels The **sysmouse** driver has two levels of operation. The current operation level can be referred to and changed via ioctl calls. The level zero, the basic level, is the lowest level at which the driver offers the basic service to user programs. The **sysmouse** driver provides horizontal and vertical movement of the mouse and state of up to three buttons in the MouseSystems format as follows. - Byte 1 - bit 7 Always one. - bit 6..3 Always zero. - bit 2 Left button status; cleared if pressed, otherwise set. - bit 1 Middle button status; cleared if pressed, otherwise set. Always one, if the device does not have the middle button. - bit 0 Right button status; cleared if pressed, otherwise set. - Byte 2 The first half of horizontal movement count in two's complement; -128 through 127. - Byte 3 The first half of vertical movement count in two's complement; -128 through 127. - Byte 4 The second half of the horizontal movement count in two's complement; -128 through 127. To obtain the full horizontal movement count, add the byte 2 and 4. - Byte 5 The second half of the vertical movement count in two's complement; -128 through 127. To obtain the full vertical movement count, add the byte 3 and 5. At the level one, the extended level, mouse data is encoded in the standard format MOUSE\_PROTO\_SYSMOUSE as defined in [mouse(4)](/mouse/4.md). ## IOCTLS This section describes two classes of [ioctl(2)](/ioctl/2.md) commands: commands for the **sysmouse** driver itself, and commands for the console and the console control drivers. ### Sysmouse Ioctls There are a few commands for mouse drivers. General description of the commands is given in [mouse(4)](/mouse/4.md). Following are the features specific to the **sysmouse** driver. - MOUSE\_GETLEVEL *int* *\*level* - MOUSE\_SETLEVEL *int* *\*level* These commands manipulate the operation level of the mouse driver. - MOUSE\_GETHWINFO *mousehw\_t* *\*hw* Returns the hardware information of the attached device in the following structure. Only the *iftype* field is guaranteed to be filled with the correct value in the current version of the **sysmouse** driver. ``` typedef struct mousehw { int buttons; /* number of buttons */ int iftype; /* I/F type */ int type; /* mouse/track ball/pad... */ int model; /* I/F dependent model ID */ int hwid; /* I/F dependent hardware ID */ } mousehw_t; ``` The *buttons* field holds the number of buttons detected by the driver. The *iftype* is always MOUSE\_IF\_SYSMOUSE. The *type* tells the device type: MOUSE\_MOUSE, MOUSE\_TRACKBALL, MOUSE\_STICK, MOUSE\_PAD, or MOUSE\_UNKNOWN. The *model* is always MOUSE\_MODEL\_GENERIC at the operation level 0. It may be MOUSE\_MODEL\_GENERIC or one of MOUSE\_MODEL\_XXX constants at higher operation levels. The *hwid* is always zero. - MOUSE\_GETMODE *mousemode\_t* *\*mode* The command gets the current operation parameters of the mouse driver. ``` typedef struct mousemode { int protocol; /* MOUSE_PROTO_XXX */ int rate; /* report rate (per sec) */ int resolution; /* MOUSE_RES_XXX, -1 if unknown */ int accelfactor; /* acceleration factor */ int level; /* driver operation level */ int packetsize; /* the length of the data packet */ unsigned char syncmask[2]; /* sync. bits */ } mousemode_t; ``` The *protocol* field tells the format in which the device status is returned when the mouse data is read by the user program. It is MOUSE\_PROTO\_MSC at the operation level zero. MOUSE\_PROTO\_SYSMOUSE at the operation level one. The *rate* is always set to -1. The *resolution* is always set to -1. The *accelfactor* is always 0. The *packetsize* field specifies the length of the data packet. It depends on the operation level. - *level* *0* 5 bytes - *level* *1* 8 bytes The array *syncmask* holds a bit mask and pattern to detect the first byte of the data packet. *syncmask\[0\]* is the bit mask to be ANDed with a byte. If the result is equal to *syncmask\[1\]*, the byte is likely to be the first byte of the data packet. Note that this method of detecting the first byte is not 100% reliable; thus, it should be taken only as an advisory measure. - MOUSE\_SETMODE *mousemode\_t* *\*mode* The command changes the current operation parameters of the mouse driver as specified in *mode*. Only *level* may be modifiable. Setting values in the other field does not generate error and has no effect. - MOUSE\_READDATA *mousedata\_t* *\*data* - MOUSE\_READSTATE *mousedata\_t* *\*state* These commands are not supported by the **sysmouse** driver. - MOUSE\_GETSTATUS *mousestatus\_t* *\*status* The command returns the current state of buttons and movement counts in the structure as defined in [mouse(4)](/mouse/4.md). ### Console and Consolectl Ioctls The user process issues console **ioctl**() calls to the current virtual console in order to control the mouse pointer. The console **ioctl**() also provides a method for the user process to receive a [signal(3)](/signal/3.md) when a button is pressed. The mouse daemon [moused(8)](/moused/8.md) uses **ioctl**() calls to the console control device */dev/consolectl* to inform the console of mouse actions including mouse movement and button status. Both classes of **ioctl**() commands are defined as CONS\_MOUSECTL which takes the following argument. ``` struct mouse_info { int operation; union { struct mouse_data data; struct mouse_mode mode; struct mouse_event event; } u; }; ``` - *operation* This can be one of - MOUSE\_SHOW Enables and displays mouse cursor. - MOUSE\_HIDE Disables and hides mouse cursor. - MOUSE\_MOVEABS Moves mouse cursor to position supplied in *u.data*. - MOUSE\_MOVEREL Adds position supplied in *u.data* to current position. - MOUSE\_GETINFO Returns current mouse position in the current virtual console and button status in *u.data*. - MOUSE\_MODE This sets the [signal(3)](/signal/3.md) to be delivered to the current process when a button is pressed. The signal to be delivered is set in *u.mode*. The above operations are for virtual consoles. The operations defined below are for the console control device and are used by [moused(8)](/moused/8.md) to pass mouse data to the console driver. - MOUSE\_ACTION - MOUSE\_MOTION\_EVENT These operations take the information in *u.data* and act upon it. Mouse data will be sent to the **sysmouse** driver if it is open. MOUSE\_ACTION also processes button press actions and sends signal to the process if requested or performs cut and paste operations if the current console is a text interface. - MOUSE\_BUTTON\_EVENT *u.data* specifies a button and its click count. The console driver will use this information for signal delivery if requested or for cut and paste operations if the console is in text mode. MOUSE\_MOTION\_EVENT and MOUSE\_BUTTON\_EVENT are newer interface and are designed to be used together. They are intended to replace functions performed by MOUSE\_ACTION alone. - *u* This union is one of - *data* ``` struct mouse_data { int x; int y; int z; int buttons; }; ``` *x*, *y* and *z* represent movement of the mouse along respective directions. *buttons* tells the state of buttons. It encodes up to 31 buttons in the bit 0 though the bit 30. If a button is held down, the corresponding bit is set. - *mode* ``` struct mouse_mode { int mode; int signal; }; ``` The *signal* field specifies the signal to be delivered to the process. It must be one of the values defined in ⟨signal.h⟩. The *mode* field is currently unused. - *event* ``` struct mouse_event { int id; int value; }; ``` The *id* field specifies a button number as in *u.data.buttons*. Only one bit/button is set. The *value* field holds the click count: the number of times the user has clicked the button successively. ## FILES - */dev/consolectl* device to control the console - */dev/sysmouse* virtualized mouse driver - */dev/ttyv%d* virtual consoles ## SEE ALSO [vidcontrol(1)](/vidcontrol/1.md), [ioctl(2)](/ioctl/2.md), [signal(3)](/signal/3.md), [mouse(4)](/mouse/4.md), [moused(8)](/moused/8.md) ## HISTORY The **sysmouse** driver first appeared in FreeBSD 2.2. ## AUTHORS This manual page was written by John-Mark Gurney ⟨*jmg@FreeBSD.org*⟩ and Kazutaka Yokota ⟨*yokota@FreeBSD.org*⟩.