.\" 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: November 17 2022 $
.Dt LUXSET 3
.Os Linux
.Sh NAME
.Nm luxset ,
.Nm luxinc ,
.Nm luxdec ,
.Nm luxsetp ,
.Nm luxincp ,
.Nm luxdecp
.Nd modify display brightness levels
.Sh LIBRARY
.Lb liblux
.Sh SYNOPSIS
.In lux.h
.Ft int
.Fn luxset "lux_t *disp" "int n"
.Ft int
.Fn luxinc "lux_t *disp" "int n"
.Ft int
.Fn luxdec "lux_t *disp" "int n"
.Ft double
.Fn luxsetp "lux_t *disp" "double p"
.Ft double
.Fn luxincp "lux_t *disp" "double p"
.Ft double
.Fn luxdecp "lux_t *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;
	lux_t 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 ,
.Xr lux.h 3head
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com