Skip to content
Browse files

Add a README file.

  • Loading branch information...
1 parent f5bc16d commit 1f2035aa16aa4c74885a6ea465af04f6bab8c1ab @mgorny committed
Showing with 72 additions and 0 deletions.
  1. +72 −0 README
View
72 README
@@ -0,0 +1,72 @@
+sw-notify-send -- a system-wide notify-send wrapper
+===================================================
+
+
+A quick introduction
+--------------------
+
+Even wondered why libnotify doesn't support sending notifications using
+user other than the one running the notification daemon? I have done
+that many times too, and never found an answer. This is why I have
+created this tiny tool.
+
+sw-notify-send stands for 'system-wide notify-send', and that means it
+is a wrapper for the `notify-send` tool, allowing to use it using
+another user account (and send notifications out of the particular
+session running the daemon).
+
+
+System requirements
+-------------------
+
+* The `proc` library (which can be found in the procps package),
+* the `notify-send` program (which is a part of libnotify).
+
+
+How to use
+----------
+
+sw-notify-send is only a dumb wrapper for notify-send. Thus, it doesn't
+take any arguments of its' own and passes all of them to notify-send.
+Thus, to use it you simply replace `notify-send` with `sw-notify-send`
+in your shell script (or command line, or wherever you're going to use
+it).
+
+In other words, you use it like:
+
+ sw-notify-send 'Test' 'Hello world!'
+
+Simple, isn't it?
+
+Please notice though that sw-notify-send doesn't do any syntax checking
+on its' own. If you run it with invalid arguments, only the actual
+notify-send will complain. And if sw-notify-send doesn't notice any
+running notification daemon, you won't see any complaints at all!
+
+And as you might have expected, sw-notify-send requires a lot
+of privileges (details below). Thus, if run using a regular user, it
+will most certainly notice only his own notification daemon. To get real
+system-wide notifications, you need to run sw-notify-send using
+the superuser account (e.g. through sudo).
+
+
+Technical details
+-----------------
+
+sw-notify-send simply iterates over all running processes (using
+the `/proc` filesystem) looking for anything looking like
+a DBus session bus. And by 'looking like', I mean having `dbus-daemon`
+as the basename and `--session` among its arguments.
+
+For every one it finds, it tries to grab the access details and execute
+`notify-send`. It tries to preserve DISPLAY and XAUTHORITY, and calls
+`setuid()` to get the identity of that user -- and that should be enough
+for dbus to let us in.
+
+In addition to that, sw-notify-send also supports having
+the notification daemon running in a chroot. If it founds one doing so
+(looking at the `root` procfs entry), it calls `chroot()` to enter
+the chroot.
+
+
+<!-- vim:se syn=markdown : -->

0 comments on commit 1f2035a

Please sign in to comment.
Something went wrong with that request. Please try again.