From 3a151898dcd5143be081b0aae2515ebcb60fe926 Mon Sep 17 00:00:00 2001 From: "matthias@quintern.xyz" Date: Thu, 20 Mar 2025 19:04:25 +0100 Subject: [PATCH] switch readme --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++- readme.md | 67 ------------------------------------------------------- 2 files changed, 65 insertions(+), 68 deletions(-) delete mode 100644 readme.md diff --git a/README.md b/README.md index 4644cc1..dbbb15e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,67 @@ # udev-filter +Super fast and efficient way of only getting udev events you desire. +It provides an efficient way to perform automatic tasks when any device related event occurs, +entirely in userspace and *without adding any udev rules*! -Efficient way of performing userspace actions on udev events \ No newline at end of file +**udev-filter** listens to events via `udevadm monitor -p`. +It matches the udev events to event properties that are passed as command arguments. +When all properties of an event are registered, the program ouputs the name of the event, as defined by the user. + +## Examples +```shell +udev-filter --event=USB_REMOVED ACTION=remove +USB_REMOVED +USB_REMOVED +... +``` +prints `USB_REMOVED` any time a USB device is removed. +The name after --event can be freely chosen. +Another, more useful example might be: + +```shell +udev-filter --event=YUBIKEY_ADDED ACTION=add ID_USB_VENDOR=Yubico +``` +prints `YUBIKEY_ADDED` every time a device with vendor id "Yubico" is added. + +You can, of course, also listen to many events add once. To combine the previous two: +```shell +udev-filter \ + --event=USB_REMOVED ACTION=remove SUBSYSTEM=USB \ + --event=YUBIKEY_ADDED ACTION=add ID_USB_VENDOR=Yubico" +``` + +### Performing actions on events +To automatically open yubico-authenticator every time a yubikey is connected, create +this shell script and run it in the background: +```shell +# stdbuf is necessary to force buffer flushing on newlines +stdbuf -oL ./udev-filter --command-add="-s usb" \ + --event=YUBIKEY_ADDED ACTION=add ID_USB_VENDOR=Yubico | \ +while read EVENT; do + # in this example the only possible event is YUBIKEY_ADDED, so the switch-case is not necessary, + # but it is useful for further expansion + case $EVENT in + YUBIKEY_ADDED) + notify-send "Yubikey Added!" + { pgrep yubico || yubico-authenticator & } + ;; + *) + notify-send "Unhandled event: $EVENT" + ;; + esac +done +``` +Because **udev-filter** relies on events instead of polling, this script will consume near zero resources. +It will only do something whenever a udev event occurs. + + +To find out which properties you need to query, run `udevadm monitor -p`. +To limit the events to a certain subsystem, add `-s ` to udevadm, and later `--command-add="-s "` to `udev-filter`. + +## Installation +gcc, with glibc++ for C++23 and GNU make are required, which will be available in most modern Linux distributions already. +``` +cd src +make release +``` +will create `../udev-filter`. Copy it anywhere you want, for example `~/.local/bin` diff --git a/readme.md b/readme.md deleted file mode 100644 index dbbb15e..0000000 --- a/readme.md +++ /dev/null @@ -1,67 +0,0 @@ -# udev-filter -Super fast and efficient way of only getting udev events you desire. -It provides an efficient way to perform automatic tasks when any device related event occurs, -entirely in userspace and *without adding any udev rules*! - -**udev-filter** listens to events via `udevadm monitor -p`. -It matches the udev events to event properties that are passed as command arguments. -When all properties of an event are registered, the program ouputs the name of the event, as defined by the user. - -## Examples -```shell -udev-filter --event=USB_REMOVED ACTION=remove -USB_REMOVED -USB_REMOVED -... -``` -prints `USB_REMOVED` any time a USB device is removed. -The name after --event can be freely chosen. -Another, more useful example might be: - -```shell -udev-filter --event=YUBIKEY_ADDED ACTION=add ID_USB_VENDOR=Yubico -``` -prints `YUBIKEY_ADDED` every time a device with vendor id "Yubico" is added. - -You can, of course, also listen to many events add once. To combine the previous two: -```shell -udev-filter \ - --event=USB_REMOVED ACTION=remove SUBSYSTEM=USB \ - --event=YUBIKEY_ADDED ACTION=add ID_USB_VENDOR=Yubico" -``` - -### Performing actions on events -To automatically open yubico-authenticator every time a yubikey is connected, create -this shell script and run it in the background: -```shell -# stdbuf is necessary to force buffer flushing on newlines -stdbuf -oL ./udev-filter --command-add="-s usb" \ - --event=YUBIKEY_ADDED ACTION=add ID_USB_VENDOR=Yubico | \ -while read EVENT; do - # in this example the only possible event is YUBIKEY_ADDED, so the switch-case is not necessary, - # but it is useful for further expansion - case $EVENT in - YUBIKEY_ADDED) - notify-send "Yubikey Added!" - { pgrep yubico || yubico-authenticator & } - ;; - *) - notify-send "Unhandled event: $EVENT" - ;; - esac -done -``` -Because **udev-filter** relies on events instead of polling, this script will consume near zero resources. -It will only do something whenever a udev event occurs. - - -To find out which properties you need to query, run `udevadm monitor -p`. -To limit the events to a certain subsystem, add `-s ` to udevadm, and later `--command-add="-s "` to `udev-filter`. - -## Installation -gcc, with glibc++ for C++23 and GNU make are required, which will be available in most modern Linux distributions already. -``` -cd src -make release -``` -will create `../udev-filter`. Copy it anywhere you want, for example `~/.local/bin`