diff options
| -rw-r--r-- | man/luxget.3 | 147 | ||||
| -rw-r--r-- | man/luxgetp.3 | 18 | ||||
| -rw-r--r-- | man/luxmax.3 | 18 |
3 files changed, 183 insertions, 0 deletions
diff --git a/man/luxget.3 b/man/luxget.3 new file mode 100644 index 0000000..5ada1a9 --- /dev/null +++ b/man/luxget.3 @@ -0,0 +1,147 @@ +.\" vi: tw=80 +.\" +.\" BSD Zero Clause License +.\" +.\" Copyright (c) 2022 Thomas Voss +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +.\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: September 8 2022 $ +.Dt LUXGET 3 +.Os +.Sh NAME +.Nm luxget , +.Nm luxmax , +.Nm luxgetp +.Nd query the current or maximum brightness of a display +.Sh SYNOPSIS +.In lux.h +.Ft int +.Fn luxget "struct luxdisp *disp" +.Ft int +.Fn luxmax "struct luxdisp *disp" +.Ft double +.Fn luxgetp "struct luxdisp *disp" +.Sh DESCRIPTION +The +.Fn luxget +function takes a pointer to a +.Vt "struct luxdisp" +structure and returns the raw brightness value of the associated display. +If the function returns \-1 it means that an error has occured, however this is +only possible if +.Va disp +has not yet been passed to any other library function that interacts with the +current brightness level, whether that be to get the current brightness or set +the current brightness. +.Pp +The +.Fn luxmax +function behaves identically to the +.Fn luxget +function except it returns the maximum supported brightness of the display +refered to by +.Va disp . +Additionally, this function can only error if +.Va disp +has not yet been used as a parameter to an invocation of either +.Fn luxmax +or any of the +.Fn lux*p +functions. +.Pp +The +.Fn luxgetp +function takes a pointer to a +.Vt "struct luxdisp" +structure and returns the brightness of the associated display as a percentage. +A return value of 100.0 means the display is at 100% brightness. +If the function returns \-1 it means that an error has occured. +Internally this function calls both +.Fn luxget +and +.Fn luxmax , +so if both of those functions are in a state where they can no longer fail, then +you do not need to error check this function. +.Sh RETURN VALUES +The +.Fn luxget +function returns the raw brightness value of the associated display. +.Pp +The +.Fn luxmax +function returns the maximum raw brightness value of the associated display. +.Pp +The +.Fn luxgetp +function returns the current brightness percentage of the associated display. +A value of 100.0 is equivalent to 100% brightness. +.Pp +On error, all the above functions will return \-1 and +.Va errno +is set to indicate the error. +.Sh EXAMPLES +The following program queries and prints information regarding displays current +brightness. +.Bd -literal -offset indent +#include <err.h> +#include <stdio.h> +#include <stdlib.h> + +#include <lux.h> + +int +main(void) +{ + int cur, max; + double curp; + struct luxdisp disp; + + luxinit(&disp); + + if ((cur = luxget(&disp)) == -1) + err(EXIT_FAILURE, "luxget"); + if ((max = luxmax(&disp)) == -1) + err(EXIT_FAILURE, "luxmax"); + + /* Because we already passed disp to luxget() and luxmax() previously, + * we don't need to do error checking! + */ + curp = luxgetp(&disp); + + printf("Current Brightness (Raw): %d/%d\en", cur, max); + printf("Current Brightness (Percentage): %d%%/100%%\en", (int) curp); + + luxfree(&disp); + return EXIT_SUCCESS; +} +.Ed +.Sh ERRORS +.Fn luxget , +.Fn luxmax , +and +.Fn luxgetp +can fail with any of the errors specified for +.Fn fdopen +or +.Fn openat . +.Sh SEE ALSO +.Xr luxdec 3 , +.Xr luxdecp 3 , +.Xr luxfree 3 , +.Xr luxinc 3 , +.Xr luxincp 3 , +.Xr luxinit 3 , +.Xr luxset 3 , +.Xr luxsetp 3 +.Sh AUTHORS +.An Thomas Voss Aq Mt thomasvoss@live.com diff --git a/man/luxgetp.3 b/man/luxgetp.3 new file mode 100644 index 0000000..5f03a22 --- /dev/null +++ b/man/luxgetp.3 @@ -0,0 +1,18 @@ +.\" vi: tw=80 +.\" +.\" BSD Zero Clause License +.\" +.\" Copyright (c) 2022 Thomas Voss +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +.\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.so luxget.3 diff --git a/man/luxmax.3 b/man/luxmax.3 new file mode 100644 index 0000000..5f03a22 --- /dev/null +++ b/man/luxmax.3 @@ -0,0 +1,18 @@ +.\" vi: tw=80 +.\" +.\" BSD Zero Clause License +.\" +.\" Copyright (c) 2022 Thomas Voss +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +.\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.so luxget.3 |