aboutsummaryrefslogtreecommitdiff
path: root/man/luxset.3
diff options
context:
space:
mode:
authorThomas Voss <thomasvoss@live.com> 2022-09-10 01:06:12 +0200
committerThomas Voss <thomasvoss@live.com> 2022-09-10 01:06:12 +0200
commit97cf3eb4685f5c5396f16736eb6afc9827fe7593 (patch)
treeb821d68ffc1f3e6c1aceb9767f5549b05572523d /man/luxset.3
parent51afa8f0d88df978a0c6620ef6231a0cb923ec7d (diff)
Add the final manuals
Diffstat (limited to 'man/luxset.3')
-rw-r--r--man/luxset.3169
1 files changed, 169 insertions, 0 deletions
diff --git a/man/luxset.3 b/man/luxset.3
new file mode 100644
index 0000000..1aa620f
--- /dev/null
+++ b/man/luxset.3
@@ -0,0 +1,169 @@
+.\" 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 9 2022 $
+.Dt LUXSET 3
+.Os
+.Sh NAME
+.Nm luxset ,
+.Nm luxinc ,
+.Nm luxdec ,
+.Nm luxsetp ,
+.Nm luxincp ,
+.Nm luxdecp
+.Nd modify display brightness levels
+.Sh SYNOPSIS
+.In lux.h
+.Ft int
+.Fn luxset "struct luxdisp *disp" "int n"
+.Ft int
+.Fn luxinc "struct luxdisp *disp" "int n"
+.Ft int
+.Fn luxdec "struct luxdisp *disp" "int n"
+.Ft double
+.Fn luxsetp "struct luxdisp *disp" "double p"
+.Ft double
+.Fn luxincp "struct luxdisp *disp" "double p"
+.Ft double
+.Fn luxdecp "struct luxdisp *disp" "double p"
+.Sh DESCRIPTION
+The
+.Fn luxset
+function sets the brightness of the display associated with
+.Va disp
+to
+.Va n .
+It is the responsibility of the caller to ensure that the given brightness is
+valid, meaning that it is non-negative and does not exceed the maximum supported
+brightness.
+On failure \-1 is returned, however it is sometimes possible to guarantee that
+this function will not fail.
+For more information, read the
+.Xr luxget 3
+manual.
+.Pp
+The
+.Fn luxinc
+and
+.Fn luxdec
+functions act identically to
+.Fn luxset
+however instead of setting the brightness of the display to
+.Va n ,
+the current brightness is either incremented or decremented by
+.Va n
+respectively.
+.Pp
+The
+.Fn luxsetp ,
+.Fn luxincp ,
+and
+.Fn luxdecp
+all function similarly to their non-p counterparts, but instead of taking a raw
+brightness as a parameter they take percentages.
+As an example,
+.Fn luxincp &disp 50.0
+increases the display brightness by 50% of the maximum brightness and
+.Fn luxsetp &disp 25.0
+sets the current display brightness to 25%.
+On error these three functions return \-1, and they can only fail in the same
+cases as
+.Fn luxgetp ,
+so check the
+.Xr luxgetp 3
+manual for details on when you should and shouldn't error check.
+.Sh RETURN VALUES
+The
+.Fn luxset ,
+.Fn luxinc ,
+and
+.Fn luxdec
+functions all return the new raw brightness value of the display.
+.Pp
+The
+.Fn luxsetp ,
+.Fn luxincp ,
+and
+.Fn luxdecp
+functions all return the new brightness percentage of the display.
+A return value of 100.0 means the display is at 100% brightness.
+.Pp
+On error, all the above functions will return \-1 and errno is set to indicate
+the error.
+.Sh EXAMPLES
+The following program allows the user to use the
+.Fl i
+and
+.Fl d
+flags to increase and decrease the brightness of their display by a certain
+percentage.
+.Bd -literal -offset indent
+#define _POSIX_C_SOURCE 2
+#include <err.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#include <lux.h>
+
+int
+main(int argc, char **argv)
+{
+ int opt;
+ struct luxdisp disp;
+
+ luxinit(&disp);
+ while ((opt = getopt(argc, argv, ":i:d:")) != -1) {
+ switch (opt) {
+ case 'i':
+ if (luxincp(&disp, atoi(optarg)) == -1)
+ err(EXIT_FAILURE, "luxincp");
+ break;
+ case 'd':
+ if (luxdecp(&disp, atoi(optarg)) == -1)
+ err(EXIT_FAILURE, "luxdecp");
+ break;
+ default:
+ fprintf(stderr, "Usage: %s [-id val]\en", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ luxfree(&disp);
+ return EXIT_SUCCESS;
+}
+.Ed
+.Sh ERRORS
+.Fn luxset ,
+.Fn luxinc ,
+.Fn luxdec ,
+.Fn luxsetp ,
+.Fn luxincp ,
+and
+.Fn luxdecp
+can fail with any of the errors specified for
+.Fn fdopen
+or
+.Fn openat .
+.Sh SEE ALSO
+.Xr luxfree 3 ,
+.Xr luxget 3 ,
+.Xr luxgetp 3 ,
+.Xr luxinit 3 ,
+.Xr luxmax 3
+.Sh AUTHORS
+.An Thomas Voss Aq Mt thomasvoss@live.com