Merge pull request #43 from troglobit/misc

Misc

90-backlight.rules

+ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"
+ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"

README.md

-# Light
+Light - A Program to Control Backlight Controllers
+==================================================
 
-Copyright (C) 2012 - 2014, Fredrik Haikarainen
-This is free software, see the source for copying conditions.  There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
+- [Introduction](#introduction)
+- [Examples](#examples)
+- [Usage](#usage)
+  - [Operation modes](#operation-modes)
+  - [Value modes](#value-modes)
+  - [Target](#target)
+  - [Field](#field)
+  - [Controller modes](#controller-modes)
+- [Installation](#installation)
+  - [Arch Linux](#arch-linux)
+  - [Manual](#manual)
+  - [Permissions](#permissions)
+- [Origin & References](#origin--references)
 
 
-## Description
+Introduction
+------------
 
-Light is a program to control backlight controllers under GNU/Linux, it is the successor of lightscript, which was a bash script with the same purpose, and tries to maintain the same functionality.
+[Light][] is a program to control backlight controllers under GNU/Linux:
 
+* Works, in particular when other software, e.g. xbacklight, does not
+* Does not rely on X
+* Automatically detects the best controller
+* Possibility to set a minimum brightness value
 
-## Features
+Let's get started with a few examples, for details, see below for the
+full description of the different commands, options and how to access
+different controllers.
 
-* Works excellent where other software have been proven unusable or problematic, thanks to how it operates internally and the fact that it does not rely on X.
-* Can automatically figure out the best controller to use, making full use of underlying hardware.
-* Possibility to set a minimum brightness value, as some controllers set the screen to be pitch black at a vaĺue of 0 (or higher).
 
+Examples
+--------
 
-## Installation
+Get the current brightness in percent
 
-### Arch Linux
+    light -G
 
-If you run Arch Linux, there exists 2 packages;
-* [light-git](https://aur.archlinux.org/packages/light-git) - For the absolutely latest version
-* [light](https://aur.archlinux.org/packages/light) - For the latest tagged release
+or
 
-I recommend you go with light-git as you might miss important features and bugfixes if you do not.
+     light
 
-### Manual
+Increase brightness by 5 percent
 
-We recommended downloading a versioned tarball from the relases page on
-GitHub.  Download and untar the archive:
+    light -A 5
 
-    tar xf light-x.yy.tar.gz
-    cd light-x.yy/
-    ./configure && make
-    sudo make install
+Set the minimum cap to 2 in raw value on the acpi_video0 controller:
 
-However, should you want to try the latest GitHub source you first need
-to clone the repository and run the `autogen.sh` script.  This requires
-`automake` and `autoconf` to be installed on your system.
+    light -cr -s acpi_video0 -S 2
 
-    ./autogen.sh
-    ./configure && make
-    sudo make install
+Try to set the brightness to 0 after that, it will be changed to the
+minimum 2:
 
-The `configure` script and `Makefile.in` files are not part of GIT
-because they are generated at release time with `make release`.
+    light -r -s acpi_video0 -S 0
 
+Find keyboard controllers:
 
-### Permissions
+    light -k -L
+
+Activate `ScrollLock` LED, here `input15` is used, but this varies
+between different systems:
+
+    light -k -s "input15::scrolllock" -S 100
+
+Usually, LEDs only take 0 or 1 in raw value (i.e. for off/on), so you
+can instead write:
+
+    light -kr -s "input15::scrolllock" -S 1
 
-**Optional:** If you want to use udev rules instead of suid to manage sysfs permissions, you may skip the `make install` step and instead add something like the following to `/etc/udev/rules.d/90-backlight.rules` after copying your binaries:
-```
-ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"
-ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"
-```
+Verify by reading back the max brightness, you should get a value of 1:
 
+    light -kr -m -s "input15::scrolllock
 
-## Usage
 
-This application usually has 5 different criteria on flags to use, which are operation modes, value mode, target, field and controller mode. Flags from these different modes can never be used in conjunction, but all of them do not always have to be specified (although it is recommended to do so for verbosity).
+Usage
+-----
 
-**Note:** This application will only print errors if you are using it incorrectly. If something goes wrong, and you can't figure out why, try setting the verbosity flag with -v:
+### Commands
+
+* `-G`: Get (read) brightness/data from controllers/files
+* `-S VAL`: Set (write)brightness/data to controllers/files
+* `-A VAL`: Like `-S`, but adds the given value
+* `-U VAL`: Like `-S`, but subtracts the given value
+* `-O`: Save the current brightness for later use (usually used on shutdown)
+* `-I`: Restore the previously saved brightness (usually used on boot)
+* `-L`: List available controllers, see below `-k` option as well
+
+Without any options (below) the commands operate on the brightness of an
+automatically selected controller.  Values are given in percent, unless
+the below `r` option is also given.
+
+**Note:** like most UNIX applications, light only gives output on
+  errors.  If something goes wrong try the verbosity option `-v VAL`:
 
 * 0: No debug output
 * 1: Errors
 * 2: Errors, warnings
 * 3: Errors, warnings, notices
 
-### Operation modes
-
-The operation modes describe **what** you want to do.
+### Options
 
-* -G: Which **reads/gets** brightness/data from controllers/files
-* -S: Which **writes/sets** brightness/data to controllers/files
-* -A: Which does like -S but instead **adds** the value
-* -U: Which does like -S but instead '**subtracts** the value
-* -O: Save the current brightness for later use (usually used on shutdown)
-* -I: Restore the previously saved brightness (usually used on boot)
-* -L: List the available controllers
+Values may be given, or presented, in percent or raw mode.  Raw mode is
+the format specific to the controller.  The default is in percent, but
+raw mode may be required for precise control, or when the steps are very
+few, e.g. for most keyboard backlight controllers.
 
-When used by themselves operate on the brightness of a controller that is selected automatically. S, A and U needs another argument -- except for the main 4 criteria -- which is the value to set/add/subtract.   This can be specified either in percent or in raw values, but remember to specify the value mode (read below) if you want to write raw values.
+* `-p`: Percent, default
+* `-r`: Raw mode
 
-### Value modes
+By default the screen is the active target for all commands, use `-k` to
+select the keyboard instead.  In either case you may need to select a
+different controller, see below.
 
-The value mode specify in what unit you want to read or write values in. The default one (if not specified) is in percent, the other one is raw mode and should always be used when you need very precise values (or only have a controller with a very small amount of brightness levels).
+* `-l`: Act on screen backlight, default
+* `-k`: Act on keyboard backlight and LEDs
 
-* -p: Percent
-* -r: Raw mode
+By default commands act on the brightness property, which is read+write.
+The maximum brightness is a read-only property.  The minimum brightness
+cap is a feature implemented to protect against setting brightness too
+low, since some controllers make the screen go pitch black at 0%.  For
+controllers like that it is recommended to set this value.
 
-Remember, this is the unit that will be used when you set, get, add or subtract brightness values.
+* `-b`: Current brightness of selected controller, default
+* `-m`: Max. brightness of selected controller
+* `-c`: Min. brightness (cap) of selected controller (recommend raw mode)
 
-### Target
+Controller is automatically done to select the controller with maximum
+precision.  It can however also be done manually and we recommend the
+`-L` and `-Lk` commands to list available controllers:
 
-You can choose which target to act on:
+* `-a`: Automatic controller selection
+* `-s ARG`: Manual controller selection
 
-* -l: Act on screen backlight
-* -k: Act on keyboard backlight and LEDs
+**Note:** Without the `-s` flag on _every_ command light will default
+  to automatic controller selection.
 
-### Field
 
-As you can not only handle the **brightness** of controllers, you may also specify a field to read/write from/to:
+Installation
+------------
 
-* -b: Current brightness of selected controller
-* -m: Maximum brightness of selected controller
-* -c: Minimum brightness (cap) of selected controller
+### Arch Linux
 
-The minimum brightness is a feature implemented as some controllers make the screen go pitch black at 0%, if you have a controller like that, it is recommended to set this value (in either percent or in raw mode). These values will be saved in raw mode though, so if you specify it in percent it might not be too accurate depending on your controller.
+If you run Arch Linux, there exists 2 packages;
 
-### Controller modes
+* [light-git][] - For the absolutely latest version
+* [light-tag][] - For the latest tagged release
 
-Finally, you can either use the built-in controller selection to get the controller with the maximum precision, or you can specify one manually with the -s flag. The -a flag will force automatic mode and is default. Use -L to get a list of controllers to use with the -s flag (to specify which controller to use). 
+We recommend you go with light-git as you might miss important features
+and bugfixes if you do not.
 
-**Notice: You _need_ to include the `-s` or `-a` flag on _every_ command you run. The controller setting will _not_ be stored anywhere! If you do not use any of the flags, it will always default to automatic selection.**
 
-### Examples
+### Manual
 
-Get the current brightness in percent
+We recommended downloading a versioned tarball from the relases page on
+GitHub.  Download and untar the archive:
 
-`light -G`, or simply `light`
+    tar xf light-x.yy.tar.gz
+    cd light-x.yy/
+    ./configure && make
+    sudo make install
 
-Increase brightness by 5 percent
+However, should you want to try the latest GitHub source you first need
+to clone the repository and run the `autogen.sh` script.  This requires
+`automake` and `autoconf` to be installed on your system.
 
-`light -A 5`
+    ./autogen.sh
+    ./configure && make
+    sudo make install
 
-Set the minimum cap to 2 in raw value on the acpi_video0 controller:
+The `configure` script and `Makefile.in` files are not part of GIT
+because they are generated at release time with `make release`.
 
-`light -Scrs "acpi_video0" 2`
 
-Try to set the brightness to 0 after that, it will be changed to the minimum 2
+### Permissions
 
-`light -Srs "acpi_video0" 0`
+**Optional:** Instead of SUID root you can set up udev rules to manage
+   sysfs permissions, you may skip the `make install` step and instead
+   copy the file `90-backlight.rules` to `/etc/udev/rules.d/`:
 
-Find keyboard controllers
 
-`light -Lk`
+    ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"
+    ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"
 
-Activate `ScrollLock` LED
 
-`light -Sks "input15::scrolllock" 100`
+Origin & References
+-------------------
 
-Usually, LEDs only take 0 or 1 in raw value (i.e. for off/on), so you can write
+Copyright (C) 2012-2018 Fredrik Haikarainen
 
-`light -Skrs "input15::scrolllock" 1`
+This is free software, see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
 
-Verify this with `light -v3 -mkrs input15::scrolllock`, you should get a max. brightness of 1
+[Light]:     https://github.com/haikarainen/light
+[light-git]: https://aur.archlinux.org/packages/light-git
+[light-tag]: https://aur.archlinux.org/packages/light

src/Makefile.am

 bin_PROGRAMS   = light
 light_SOURCES  = main.c light.c light.h helpers.c helpers.h
 light_CPPFLAGS = -I../include -D_XOPEN_SOURCE=500
-light_CFLAGS   = -W -Wall -Wextra -pedantic -std=c89
+light_CFLAGS   = -W -Wall -Wextra -pedantic -std=c99
 
 install-exec-hook:
 	chmod 4755 $(DESTDIR)$(bindir)/light

src/light.c

 }
 
 void light_printVersion(){
-  printf("Light %u.%u (%s)\n", LIGHT_VER_MAJOR, LIGHT_VER_MINOR, LIGHT_VER_TYPE);
-  printf("Copyright (C) %u %s\n", LIGHT_YEAR, LIGHT_AUTHOR);
-  printf("This is free software, see the source for copying conditions.  There is NO\n");
-  printf("warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\n\n");
+  printf("v%s\n", VERSION);
 }
 
 void light_printHelp(){
-  printf("Usage: light <options> <value>\n");
-  printf("<value> has to be either integral(raw mode) or decimal(percent mode) depending on the specified value mode.\n");
-  printf("<options> can be any of the following:\n\n");
-
-  printf("Operations (can not be used in conjunction):\n");
-  printf("  -H -h:\tPrints this help and exits\n");
-  printf("  -V:\t\tPrints version info and exits\n");
-  printf("  -G:\t\tGet value (default)\n");
-  printf("  -S:\t\tSet value\n");
-  printf("  -A:\t\tAdd value\n");
-  printf("  -U:\t\tSubtract value\n");
-  printf("  -L:\t\tList controllers\n");
-  printf("  -I:\t\tRestore brightness\n");
-  printf("  -O:\t\tSave brightness\n\n");
-
-  printf("Targets (can not be used in conjunction):\n");
-  printf("  -l:\t\tAct on screen backlight (default)\n");
-  printf("  -k:\t\tAct on keyboard backlight\n\n");
-
-  printf("Fields (can not be used in conjunction):\n");
-  printf("  -b:\t\tBrightness (default)\n  \t\tUsed with [GSAU]\n\n");
-  printf("  -m:\t\tMaximum brightness\n  \t\tUsed with [G]\n\n");
-  printf("  -c:\t\tMinimum cap\n  \t\tUsed with [GS]\n");
-  printf("  \t\tG returns null if no minimum cap is set.\n\n");
-
-  printf("Controller selection (can not be used in conjunction):\n");
-  printf("  -a:\t\tSelects controller automatically (default).\n");
-  printf("  -s:\t\tSpecify controller to use. (needs argument)\n\n");
-
-  printf("Value modes (can not be used in conjunction):\n");
-  printf("  -p:\t\tInterpret <value> as, and output values in, percent. (default)\n");
-  printf("  -r:\t\tInterpret <value> as, and output values in, raw mode.\n\n");
-
-  printf("Other:\n");
-  printf("  -v:\t\tSets the verbosity level, (needs argument).\n  \t\t0: Only outputs read values.\n  \t\t1: Read values, Errors.\n  \t\t2: Read values, Errors, Warnings.\n  \t\t3: Read values, Errors, Warnings, Notices.\n\n");
+	printf("Usage:\n"
+	       "  light [OPTIONS] <COMMAND> [VALUE]\n"
+	       "\n"
+	       "Commands:\n"
+	       "  -A VAL  Add value\n"
+	       "  -G      Get (read) value, default command\n"
+	       "  -H, -h  Show this help and exit\n"
+	       "  -I      Restore brightness\n"
+	       "  -L      List available controllers\n"
+	       "  -O      Save brightness\n"
+	       "  -S VAL  Set (write) value\n"
+	       "  -U VAL  Subtract value\n"
+	       "  -V      Show program version and exit\n"
+	       "\n"
+	       "Options:\n"
+	       "  -a      Automatic controller selection, default\n"
+	       "  -b      Brightness, default\n"
+	       "  -c      Act on minimum cap, only possible to read and set\n"
+	       "  -k      Act on keyboard backlight\n"
+	       "  -l      Act on screen backlight, default\n"
+	       "  -m      Maximum brightness, only possible to read\n"
+	       "  -p      Interpret input, and output, values in percent, default\n"
+	       "  -r      Interpret input, and outpot, values in raw mode\n"
+	       "  -s ARG  Specify controller to use, use -L and -Lk to list available\n"
+	       "  -v ARG  Verbosity level:\n"
+	       "            0: Values only, default\n"
+	       "            1: Values, Errors.\n"
+	       "            2: Values, Errors, Warnings.\n"
+	       "            3: Values, Errors, Warnings, Notices.\n"
+	       "\n");
+
+	printf("Copyright (C) %s  %s\n", LIGHT_YEAR, LIGHT_AUTHOR);
+	printf("This is free software, see the source for copying conditions.  There is NO\n"
+	       "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\n"
+	       "\n");
 }
 
 LIGHT_BOOL light_initialize(int argc, char** argv)

src/light.h

-#ifndef LIGHT_H
-#define LIGHT_H
+#ifndef LIGHT_H_
+#define LIGHT_H_
 
+#include "config.h"
 #include "helpers.h"
 
 #include <sys/types.h>
 #include <dirent.h>
 #include <linux/limits.h>
 
-#define LIGHT_VER_MAJOR 0
-#define LIGHT_VER_MINOR 10
-#define LIGHT_VER_TYPE "beta"
-#define LIGHT_YEAR 2014
+#define LIGHT_YEAR   "2012-2018"
 #define LIGHT_AUTHOR "Fredrik Haikarainen"
 
-#define ASSERT_SET(t,v) \
-  if(v)\
-  {\
-    fprintf(stderr, t" arguments can not be used in conjunction.\n");\
-    return FALSE;\
-  }\
-  v = TRUE;
+#define ASSERT_SET(t,v)							\
+	if (v) {							\
+		fprintf(stderr, t" arguments cannot be used in conjunction.\n"); \
+		return FALSE;						\
+	}								\
+	v = TRUE;
 
 #define ASSERT_OPSET() ASSERT_SET("Operation", opSet)
 #define ASSERT_TARGETSET() ASSERT_SET("Target", targetSet)
 
 LIGHT_BOOL light_restoreBrightness(char const *controller);
 
-#endif /* LIGHT_H */
+#endif /* LIGHT_H_ */