Add the final manuals

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