path: root/redshift.1

.TH REDSHIFT 1 REDSHIFT-NG
.SH NAME
redshift \- Automatically adjust display colour temperature according the Sun

.SH SYNOPSIS
.B redshift
[-b
.IR brightness ]
[-c
.IR config-file ]
[-D | +D] [-E | +E | -e
.IR elevations ]
[-g
.IR gamma ]
[-l
.IB latitude : longitude
| -l
.IR provider [\fB:\fP options ]]
[-m
.IR method [\fB:\fP options ]
[-P | +P] [-r | +r] [-dv]
[-O
.I temperature
| -o | -p | -t
.I temperature
| -x] | -h | -V

.SH DESCRIPTION
.B redshift
adjusts the colour temperature of your screen according to your
surroundings. This may help your eyes hurt less or reduce the risk for
delayed sleep phase syndrome if you are working in front of the screen
at night.
.PP
The colour temperature is set according the the position of the Sun.
A different colour temperature is set during the night and during the
day. During dawn and early morning, the colour temperature transitions
smoothly from night- to day-time temperature to allow your eyes to
slowly adapt over a period of about an hour. At night, the colour
temperature should be set to match the maps in your room. This is
typically a low temperature at around 3000K-4000K (default is 4500K).
During the day, the colour temperature should match the light from
outside. Typically around 5500K-6500K (default is 6500K). The light has
a lower temperature on an overcast day.
.PP
In addition to the command-line tool
.BR redshift ,
the GUI
.BR redshift-gtk (1)
provides an alternative interface that shows up as a notification icon
in the desktop environment.

.SH OPTIONS
The following options are supported:
.TP
.BI -b\fR\  brightness
Synonym for
.B -b
.IB brightness : brightness\fR.
.TP
.BI -b\fR\  day : night
Monitor whitepoint brightness to apply at daytime and at
nighttime. (Default: 1:1)

The values most be between 0.1 and 1.0.

.I day
or
.I night
may be omitted, to keep unmodified, however
at least one must be specified.
.TP
.BI -c\fR\  config-file
Load settings from specified configuration file.

.B /dev/null
can be used to tell
.B redshift
not to load the configuration file.

If
.RB \(dq - \(dq,
the standard input will be used.
.TP
.B -D
Start in enabled state. (Default)
.TP
.B +D
Start in disabled state.

Ignored in one-shot mode.
.TP
.B -E
Use wall-clock based schedule.
.TP
.B +E
Use solar elevation based schedule.
.TP
.BI -e\fR\  elevations
Synonym for
.B -e
.IB elevations : elevations\fR.
.TP
.BI -e\fR\  elevation-high : elevation-low
Sets the lowest solar elevation during daytime to
.I elevation-high
and the higest solar elevation during nighttime to
.IR elevation-low .

The value should be formatted as real, decimal
values measured in degrees. Each value shall be
formatted as one complete value, without unit
suffix, and not split into degrees, minutes, and
seconds. Positive values are above the horizon
and negative values are below the horizon.

.I elevation-high
or
.I elevation-low
may be omitted, to keep unmodified, however at least
one must be specified.

Implies
.BR +E .
.TP
.B -d
Keep the process alive and remove the colour effects
when killed.

Ignored for
.B -p
and
.BR -x ;
always active for
.B -t
and the
.B quartz
adjustment method.
.TP
.BI -g\fR\  gamma
Synonym for
.B -g
.IB gamma : gamma\fR.
.TP
.BI -g\fR\  day : night
Synonym for
.B -g
.IB day : day : day : night : night : night\fR.

However, if
.I day
is omitted, it is a synonym for
.B -g
.BI : night : night : night\fR,
or if
.I night
is omitted, it is a synonym for
.B -g
.IB day : day : day :\fR.
.TP
.BI -g\fR\  red : green : blue
Synonym for
.B -g
.IB red : green : blue : red : green : blue\fR.
.TP
.BI -g\fR\  day-r : day-g : day-b : night-r : night-g : night-b
Additional gamma correction to apply at daytime and
at nighttime. (Default: 1:1:1:1:1:1)

The values most be between 0.1 and 10.0.

.IB day-r : day-g : day-b
or
.IB night-r : night-g : night-b
may be omitted,
to keep unmodified, however at least one set must be specified.
Individual components of one set cannot be omitted, either
nothing is omitted or an entire set, including its two colons
.RB ( : )
are omitted.
.TP
.B -h
Display help message.
.TP
.BI -l\fR\  latitude : longitude
Your current location, in degrees. Shall be formatted a single
real number, rather than split into integer degrees, minutes
and seconds. The location should be specified using the GPS
coordinate system.
.TP
.BI -l\fR\  provider\fR[ : options\fR]
Select provider for automatic location updates.

.I options
is a colon-
.RB ( : )
and semicolon-separated
.RB ( ; )
list. Each option an option name and value
separated by an equals sign
.RB ( = ).

Use
.B -l list
to see available providers.

Use
.BI -l\  provider :help
to see available options,
or refer to the
.B EXTENDED DESCRIPTION
section.
.TP
.BI -m\fR\  method\fR[ : options\fR]
Method to use to set colour temperature.

.I options
is a colon-
.RB ( : )
and semicolon-separated
.RB ( ; )
list. Each option an option name and value
separated by an equals sign
.RB ( = ).

Use
.B -m list
to see available methods.

Use
.BI -m\  method :help
to see available options,
or refer to the
.B EXTENDED DESCRIPTION
section.
.TP
.BI -O\  temperature
This is a synonym for
.B -O
.IB temperature : temperature\fR.
.TP
.BI -O\  day : night
One-shot manual mode (set colour temperature). The colour set
is interpolated between day and night depending on the Sun's
elevation or the clock time (depending on which
.B redshift
is configured to use).

Values must be at least 1000 and integral.

Use this with the
.B -P
option to clear the existing gamma ramps
before applying the new color temperature.

This is a synonym for
.B -t
.IB day : night
.BR -o .
.TP
.B -o
One-shot mode (do not continuously adjust colour temperature).

Use this with the
.B -P
option to clear the existing gamma ramps
before applying the new color temperature.
.TP
.B -P
Reset exiting gamma ramps before applying new colour effects.
.TP
.B +P
Preserve preexisting gamma adjustments. (Default)
.TP
.B -p
Print parameter and exit.
.TP
.B -r
Disable fading between colour temperatures.
.TP
.B +r
Enable fading between colour temperatures. (Default)
.TP
.BI -t\fR\  temperature
This is a synonym for
.B -t
.IB temperature : temperature\fR.
.TP
.BI -t\fR\  day : night
Colour temperature to set at daytime and at nighttime.

Values must be at least 1000 and integral.

The value 6500 is equivalent to no colour temperature
adjustment.

Default mode, but default values may change between
versions.
.TP
.B -V
Show program implementation and verison.
.TP
.B -v
Enable verbose output.
.TP
.B -x
Remove adjustments from screen.
.PP
For mutually exclusive options or options specified multiple times,
the last specified takes effect, except the first specified option
that outputs text (except
.BR -p )
is used. However, if the daytime
alue or nighttime value is omitted for an option, the last previously
pecified value will be used; that is, for example,
.B -t 5000:
and
.B -t :3000
do not override each other, but
.B -t 5000:
overrides, if specified later,
.B 6000
but not
.B 3000
in
.BR "-t 6000:3000" .
.PP
Options in the command line override settings from the configuration
file.

.SH OPERANDS
None.

.SH STDIN
Not used.

.SH INPUT FILES
None.

.SH ASYNCHRONOUS EVENTS
.B redshift
takes the standard action for all signals except:
.TP
.B SIGINT
.TQ
.B SIGTERM
.TQ
.B SIGQUIT
Smoothly disable the effects of
.B redshift
and terminate the
process. If already sent, immediately disable the effects
and terminate the process.
.TP
.B SIGUSR1
Disable the effects of
.BR redshift ,
or if already disabled, reenable them.
.TP
.BR SIGUSR2 \ with\ value\ \fI0\fR
Normally signals may be processed out of order, however
when this signal is received,
.B SIGUSR2
will be blocked until all pending
.B SIGUSR2
signals has been processed, creating signal processing
order barrier. This is useful when mixing
.B SIGUSR2
value
.I 3
(reloading configuration file) with other configuration changing
.I SIGUSR2
values.
.TP
.BR SIGUSR2 \ with\ value\ \fI1\fR
Disable the effects of
.BR redshift .
.TP
.BR SIGUSR2 \ with\ value\ \fI2\fR
Enable the effects of
.BR redshift .
.TP
.BR SIGUSR2 \ with\ value\ \fI3\fR
Reload the configuration file.

Settings from the command line will be overriden.
.TP
.BR SIGUSR2 \ with\ value\ \fI4\fR
Execute into the currently installed version of
.BR redshift .

Only available on Linux.
.TP
.BR SIGUSR2 \ with\ value\ \fI5\fR
Set the
.B fade
setting to off.
.TP
.BR SIGUSR2 \ with\ value\ \fI6\fR
Set the
.B fade
setting to on.
.TP
.BR SIGUSR2 \ with\ value\ \fI7\fR
Set the
.B preserve-gamma
setting to off.
.TP
.BR SIGUSR2 \ with\ value\ \fI8\fR
Set the
.B preserve-gamma
setting to on.
.TP
.BR SIGUSR2 \ with\ value\ \fI9\fR
Exit the process without removing the its effects.
If the used adjustment method does not support leaving
the effects, they will be removed.
.TP
.BR SIGUSR2 \ with\ value\ \fI10\fR
Do not terminate
.B redshift
the standard output and standard error are closed.
.TP
.BR SIGUSR2 \ with\ value\ \fI11\fR
Enable verbose mode. (The
.B -v
option will be treated as specified.)
.TP
.BR SIGUSR2 \ with\ value\ \fI12\fR
Disable verbose mode.

Ignore if started in verbose mode
.RB ( -v
option).
.TP
.BR SIGUSR2 " with other values or no value"
Ignored.

.SH STDOUT
The standard output is used to print state information and requested
help information. The output is subject to localisation, and the
following formats apply for the
.RB \(dq C \(dq
locale. Applications taking use of this information must make sure
to set the message locale to
.RB \(dq C \(dq.
For floating-point values
.RB (\(dq %f \(dq)
the precision is not documented as it may change between versions and
applications should not expect any particular precision to be used.
.PP
When
.B -m list
is specified, the available gamma ramp adjustment methods
are printed with the header
.B \(dqAvailable adjustment methods:\en\(dq
followed by the list in the format
.RS
.nf

\fB\(dq%s%s\en\(dq, \fI<arbitrary whitespace>\fP, \fP<method name>\fR.

.fi
.RE
.PP
The list is terminated by an empty line. Additional information for
human users is printed after the empty line.
.PP
When
.B -l list
is specified, the available location providers are
printed with the header
.B \(dqAvailable location providers:\en\(dq
followed by the list in the format
.RS
.nf

\fB\(dq%s%s\en\(dq, \fI<arbitrary whitespace>\fP, \fP<provider name>\fR.

.fi
.RE
.PP
The list is terminated by an empty line. Additional information for
human users is printed after the empty line.
.PP
When
.B list
is specified for the
.B edid
suboption to
.BR -m ,
a list of available monitors will be printed to the standard output,
with the header
.BR "\(dqAvailable outputs:\en\(dq" ,
in the format
.RS
.nf

\fB\(dq%s%s\en\(dq, \fI<arbitrary whitespace>\fP, \fP<monitor identifier>\fR.

.fi
.RE
.PP
When
.BR "-m method:help" ,
.BR "-l provider:help" ,
or
.B -h
is specified help information is printed on in unspecified format,
intended only for human users.
.PP
When
.B -V
is specified, the used version of the program is printed to
the standard output in the format
.RS
.nf

\fB\(dq%s %s\en\(dq, \fI<implementation name>\fP, \fP<version number>\fR.

.fi
.RE
.PP
If
.B -v
is specified and the colour settings depend on the Sun's
elevation, the elevation thresholds are printed to the standard
output in the format
.RS
.nf

\fB\(dqSolar elevations: day above %f, night below %f\en\(dq,\fR
\fI<minimum solar elevation at daytime>\fB,\fR
\fI<maximum solar elevation at nighttime>\fR.

.fi
.RE
This line may be printed, if
.B -v
is specified, if
.B redshift
is configured.
.PP
If
.B -v
is specified and the colour settings depend on the clock time,
the time schedule is printed to the standard output, with the header
.B \(dqSchedule:\en\(dq
and the footer
.BR "\(dq(End of schedule)\e\n\(dq" ,
in the format
.RS
.nf

\fB\(dq%s%f%% day at %02u:%02u:%02u\en\(dq, \fI<arbitrary whitespace>\fP,\fR
\fI<dayness level (0-100)>\fB, \fP<start hour (0-23)>\fP,\fR
\fI<start minute (0-59)>\fB, \fP<start second (0-59)>\fR.

.fi
.RE
These lines may be printed, if
.B -v
is specified, if
.B redshift
is configured.
.PP
If
.B -v
is specified, the colour settings is printed to the standard
output in the format
.RS
.nf

\fB\(dqTemperatures: %luK at day, %luK at night\en\(dq\fR
\fB\(dqBrightness: %f:%f\en\(dq\fR
\fB\(dqGamma (Daytime): %f, %f, %f\en\(dq\fR
\fB\(dqGamma (Night): %f, %f, %f\en\(dq,\fR
\fI<daytime colour temperature>\fB, \fP<nighttime temperature>\fP,\fR
\fI<daytime whitepoint brightness>\fB, \fP<nighttime brightness>\fP,\fR
\fI<daytime red gamma>\fB, \fP<daytime green gamma>\fP,\fR
\fI<daytime blue gamma>\fB, \fP<nighttime red gamma>\fP,\fR
\fI<nighttime green gamma>\fB, \fP<nighttime blue gamma>\fR.

.fi
.RE
Each line may be printed, if
.B -v
is specified, if
.B redshift
is configured.
.PP
If the colour effects depend on the Sun's elevation, the user's
geographical location will printed to the standard output in the
format
.RS
.nf

\fB\(dqLocation: %f %c, %f %c\en\(dq,\fR
\fIfabs(<GPS latitude>)\fB, \fPsignbit(<GPS latitude>) ? 'S' : 'N'\fP,\fR
\fIfabs(<GPS longitude>)\fB, \fPsignbit(<GPS longitude>) ? 'W' : 'E'\fR.

.fi
.RE
This message is printed when the program starts and any time the
location is updated.
.PP
If the colour effects are non-static, the current period of the day
(which determine the colour effects) is printed to standard output, if
.B -v
or
.B -p
is specified, in the format
.RS
.nf

\fB\(dqPeriod: %s\en\(dq, \fI<period>\fR

.fi
.RE
where
.I <period>
is
.BR None ,
.BR Daytime ,
or
.BR Night ,
or in the format
.RS
.nf

\fB\(dqPeriod: Transition (%f%% day)\en\(dq, \fI<dayness level> * 100\fR.

.fi
.RE
.I <dayness level>
is exclusively between 0 (night) and 1 (daytime).
.PP
This message is printed when the program starts and any time it
changes (if
.B -v
is specified).
.PP
If
.B -v
or
.B -p
is specified, the colour settings are printed to the
standard output when the program standard and any time it changes
(fade effect is ignored). These are printed in three different
messages and, on chagne, only the settings that changed are printed:
.RS
.nf

\fB\(dqColor temperature: %luK\en\(dq, \fI<colour temperature>\fR;

\fB\(dqBrightness: %f\en\(dq, \fI<whitepoint brightness level (0-1)>\fR;

\fB\(dqGamma: %f, %f, %f\en\(dq, \fI<red gamma>\fP, \fP<green gamma>\fP, \fP<blue gamma>\fR.

.fi
.RE
.PP
If
.B -v
is specified, and if running in continual mode, the program will print
.B \(dqStatus: Enabled\en\(dq
if starting in or when entering enabled mode, and
.B \(dqStatus: Disabled\en\(dq
if starting in or when entering disabled mode.
.PP
If
.B -v
is specified, and if running in continual mode, the program will print
.B \(dqFade: Enabled\en\(dq
or
.B \(dqFade: Disabled\en\(dq
to indicate whether the
.B fade
setting is enabled, when the program starts and when the
setting is modified.
.PP
If
.B -v
is specified, and if running in continual mode, the program will print
.B \(dqPreserve gamma: Enabled\en\(dq
or
.B \(dqPreserve gamma: Disabled\en\(dq
to indicate whether the
.B preserve-gamma
setting is enabled, when the
program starts and when the setting is modified.
.PP
If the
.B dummy
gamma ramp adjustment method is used, any time a colour
change is applied (including each fade step), the colour temperature
is output, for debugging purposes (brightness and gamma are not printed),
to the standard output in the format
.RS
.nf

\fB\(dqTemperature: %lu\en\(dq, \fI<colour temperature>\fR.
.fi
.RE

.SH STDERR
Default.

.SH OUTPUT FILES
None.

.SH FILES
Unless the
.B -c
option is used,
.B redshift
will look for its configuration
file, and if found, load it. When searching for the configuration file,
.B redshift
will load the first found file. It will primary look for
.IR redshift-ng/redshift.conf ,
secondarily for
.IR redshift/redshift.conf ,
and tertiarily for
.IR redshift.conf ,
in each directory it searches. It
will search the following directories in order: the directory set in
the environment variable
.IR XDG_CONFIG_HOME ,
the directory set in the
environment variable
.I localappdata
(Windows only), the
.I .config
directory inside directory set in the environment variable
.IR HOME ,
and the
.I .config
directory inside the user's home directory. For the two
latter, it will quaternarily look for the file
.IR .redshift.conf .
If not found, it will also look for the file in each directory listed in the
environment variable
.I XDG_CONFIG_DIRS
(delimited by colon
.RB ( : )
on Unix-like systems and by semicolon
.RB ( ; )
on Windows), however it try each
directory before moving on to then next filename option. Lastly, on
Unix-like systems, it will look for the file in
.IR /etc .
This means that the preferred location for the configuration file is
.IB ${XDG_CONFIG_HOME} /redshift-ng/redshift.conf\fR.
.PP
.B redshift
will use the same pattern to find the hook directory, and the
tested subdirectories for each search directory are
.I /redshift-ng/hooks
and secondarily
.IR /redshift/hooks .
All executable files, in the found
directory, that are neither prefixed with a period
.BR ( . )
or suffixed with a tilde
.RB ( ~ )
will be used as hooks scripts, and will be executed in
arbitrary order. Subdirectories are not search for executable files.
This means that the preferred location for the hook scripts is (directly
inside)
.IB ${XDG_CONFIG_HOME} /redshift-ng/hooks/\fR.

.SH EXTENDED DESCRIPTION
.SS Configuration file
The configuration file uses the standard INI format. General program
options are placed under the
.B redshift
header
.RB ( [redshift] ),
while options for location providers are adjustment methods are
placed under a hader with the name of that proivder or method.
.PP
General options are:
.TP
.BI temp\fR\ =\  temperature
.TQ
.BI temperature\fR\ =\  temperature
Set temperature for daytime and nighttime. The value shall be
format in the same way as with the
.B -O
and
.B -t
options.
.TP
.BI temp-day\fR\ =\  integer
.TQ
.BI temperature-day\fR\ =\  integer
Set temperature for daytime. That value shall be an integer no
less than 1000 (Kelvin).
.TP
.BI temp-night\fR\ =\  integer
.TQ
.BI temperature-night\fR\ =\  integer
Set temperature for nighttime. That value shall be an integer
no less than 1000 (Kelvin).
.TP
.BI brightness\fR\ =\  brightness
Set whitepoint brightness for daytime and nighttime. The value
shall be format in the same way as with the
.B -b
option.
.TP
.BI brightness-day\fR\ =\  0.1-1.0
Set whitepoint brightness for daytime. That value shall be an
within [0.1, 1.0].
.TP
.BI brightness-night\fR\ =\  0.1-1.0
Set whitepoint brightness for nighttime. That value shall be an
within [0.1, 1.0].
.TP
.BI gamma\fR\ =\  gamma
Set gamma correction for daytime and nighttime. The value shall
be format in the same way as with the
.B -g
option.
.TP
.BI gamma-day\fR\ =\  0.1-10.0
.TQ
.BI gamma-day\fR\ =\  red : green : blue
Set gamma correction for daytime. Values must be within [0.1,
10.0], and are applied to each colour channel individually,
however if only one value is specified it is applied to all
each channels.
.TP
.BI gamma-night\fR\ =\  0.1-10.0
.TQ
.BI gamma-night\fR\ =\  red : green : blue
Set gamma correction for nighttime. Values must be within [0.1,
10.0], and are applied to each colour channel individually,
however if only one value is specified it is applied to all
each channels.
.TP
.BI fade\fR\ =\ \fP0 " or " 1
Disable (if
.BR 0 )
or enable (if
.BR 1 )
fading between colour settings with large differences.

The
.B -r
and
.B +r
options can be used to override this setting.
.TP
.BI preserve-gamma\fR\ =\ \fP0 " or " 1
If
.BR 1 ,
preapplied colour calibrations (all applied effects are
assumed to be colour calibrations) will be preserved, if
.BR 0 ,
colour calibrations will be reset while
.B redshift
is running.

The
.B -P
and
.B +P
options can be used to override this setting.

Note that if
.BR 0 ,
colour calibrations will be reset even when
.B redshift
is running but is disabled. This is necessary to
support the
.B -o
and
.B -O
options.

This setting is ignored when
.B coopgamma
is used as
.B coopgamma
allows multiple programs to modify the gamma ramps
at the same time.
.TP
.BI start-disabled\fR\ =\ \fP0 " or " 1
Start
.B redshift
in disabled (if
.BR 1 )
or enabled (if
.BR 0 )
state.

The
.B -D
and
.B +D
options can be used to override this setting.
.TP
.BI elevation-high\fR\ =\  decimal
The lowest solar elevation, in degrees, during daytime.
.TP
.BI elevation-low\fR\ =\  decimal
The highest solar elevation, in degrees, during nighttime.
.TP
.BI dawn-time\fR\ =\  HH : MM\fR[ : SS\fR][ - HH : MM\fR[ : SS\fR]]
.TQ
.BI dusk-time\fR\ =\  HH : MM\fR[ : SS\fR][ - HH : MM\fR[ : SS\fR]]
Custom time interval for the transition from night to day
.RB ( dawn-time )
and for the transition from day to night
.BR ( dusk-time ).

When specified, both settings must be specified and the
solar elevation will not be used to determine the current
daytime/nighttime period, nor will a location provider
used.

The left-hand hour must be within [0, 23], but the right-hand
hour may be within [0, 47], the timespan must not be greater
than 24 hours. The minutes and seconds must be within [0, 59],
and the default value for the seconds is 0.
.TP
.BI adjustment-method\fR\ =\  name
Select adjustment method. Options for the adjustment method can
be given under the configuration file heading of the same name.

Not used if the
.B -p
option is specified.
.TP
.BI location-provider\fR\ =\  name
Select location provider. Options for the location provider can
be given under the configuration file heading of the same name.

Not used if
.B dawn-time
and
.B dusk-time
are used or if the colours
settings are specified to be the same during the day and the
night.
.PP
Options for the location provider
.B manual
are:
.TP
.BI lat\fR\ =\  decimal
The GPS latitude of the user's geographical location.
Shall be specified in degrees and formatted a single
real number, rather than split into integer degrees,
minutes and seconds. Positive values used for the
northern hemisphere and negative values are ued for
the southern hemisphere.
.TP
.BI lon\fR\ =\  decimal
The GPS longitude of the user's geographical location.
Shall be specified in degrees and formatted a single
real number, rather than split into integer degrees,
minutes and seconds. Positive values used for the
eastern hemisphere and negative values are ued for
the western hemisphere.
.PP
There are no options for the location providers
.B geoclue2
(may be available on Unix-like systems) and
.B corelocation
(available on Mac OS X).
.PP
Options for the adjustment method
.B randr
(preferred method for X) are:
.TP
.BI display\fR\ =\  name
X display to apply adjustments to. Default is determined
by the environment variable
.IR DISPLAY .

The value is expected to contain a colon
.RB ( : )
and can only be terminated with a semicolon
.RB ( ; ).
.TP
.BI screen\fR\ =\  "ordinal list or " all
Comma-separated
.RB ( , )
list of X screens to apply adjustments to.
All available X screens are used if the list is empty or
if the setting is omitted.

.B all
may be specified as a synonym for an empty list.
.TP
.BI crtc\fR\ =\  "number list or " all
Comma-separated
.RB ( , )
list of CRTC numbers for monitors to
apply adjustments to. All available CRTCs are used if the
list is empty or if the setting is omitted.

A CRTC number may either be specified as an overall
ordinal for all selected X screens, or the index of
the X screen followed by a dot
.RB ( . )
and the index of the CRTC within the specified X screen.
The specified X screen is automatically included in the
.B screen
selection.

.B all
may be specified as a synonym for an empty list.

The index of the first CRTC is 0.
.TP
.BI edid\fR\ =\  "name list or " list
Comma-separated
.RB ( , )
list of EDIDs of monitors to apply adjustments to.

If
.B list
is specified, all available EDIDs will be
printed to the standard output and the program exits.

This list must not be empty; to select all monitors,
instead specify
.BR crtc=all .
.PP
Options for the adjustment method
.B vidmode
(fallback method for X) are:
.TP
.BI display\fR\ =\  name
X display to apply adjustments to. Default is determined
by the environment variable
.IR DISPLAY .

The value is expected to contain a colon
.RB ( : )
and can only be terminated with a semicolon
.RB ( ; ).
.TP
.BI screen\fR\ =\  "ordinal list or " all
Comma-separated
.RB ( , )
list of X screens to apply adjustments to.
All available X screens are used if the list is empty or
if the setting is omitted.

.B all
may be specified as a synonym for an empty list.
.PP
Options for the adjustment method
.B drm
(method for Linux without display server) are:
.TP
.BI card\fR\ =\  "ordinal list or " all
Comma-separated
.RB ( , )
list of indices of graphics card screens to apply
adjustments to. All available graphics cards
are used if the list is empty or
if the setting is omitted.

.B all
may be specified as a synonym for an empty list.
.TP
.BI crtc\fR\ =\  "number list or " all
Comma-separated
.RB ( , )
list of CRTC numbers for monitors to
apply adjustments to. All available CRTCs are used if the
list is empty or if the setting is omitted.

A CRTC number may either be specified as an overall
ordinal for all selected graphics card, or the index of
the graphics card followed by a dot
.RB ( . )
and the index of
the CRTC within the specified graphics card. The specified
graphics card is automatically included in the
.B card
selection.

.B all
may be specified as a synonym for an empty list.

The index of the first CRTC is 0.
.TP
.BI edid\fR\ =\  "name list or " list
Comma-separated
.RB ( , )
list of EDIDs of monitors to apply adjustments to.

If
.B list
is specified, all available EDIDs will be
printed to the standard output and the program exits.

This list must not be empty; to select all monitors,
instead specify
.BR crtc=all .
.PP
There are no options for the adjustment methods
.B wingdi
(available on Windows),
.B quartz
(available on Mac OS X), and
.B dummy
(used for debugging, does not apply any colour effects).

.SS Hooks
Executable files (that are not dotfiles or tilde files) in the hook
directory (see the
.B FILES
section), are executed on certain events.
The file inherit the
.B redshift
process standard input and standard
error, however the standard output is redirected to the standard error.
.PP
Each file is executed with at least one argument. This first argument
indicate what event has taked place. Additional arguments may be
provided for additional event data.
.PP
.B redshift
will be the parent process of the executed script.
.PP
Currently available events are:
.TP
.B period-changed
This indicate that the period of the day has changed (and at
start of continual mode). The script will be provided two
additional arguments (the second argument and the third
argument). The second argument will the previous period, and
the third argument will be the new period. The argument values
will be either of
.BR night ,
.BR daytime ,
.BR transition
(transition in either direction between night and daytime), or
.B none
(not previously or no longer calculated).
.B none
appears as the
previous period at start up and can also appear when the when
.B redshift
is reconfigured if the colour settings no longer
depending on the period of the day or has started depending
on the period of the day.

.SS Gamma ramps
.B redshift
applies a redness effect to the graphical display. The
intensity of the redness can be customised and scheduled to only be
applied at night or to be applied with more intensity at night.
.PP
.B redshift
uses colour correction lookup tables (CLUTs), usually called
gamma ramps or gamma correction ramps, to apply this effect.

.SS Colour temperature
The redness effect applied by
.B redshift is modelled after black-body
radiation, specifically with a 10 degree observer. Although black-body
radiation starts at 0,
.BR redshift 's
model start at the conventional 1000K
(1000 Kelvin). For this reason, no colour temperature below 1000K can be
specified. However, as there is a limit can be determined for the colour
when the colour temperature appreciates infinity, the upper limit for
allow colour temperature is instead determined by the data type it is
stored in. However, it also means that it is meaningless to use colour
temperatures above 40000K.
.PP
The sRGB colour space, and modern monitors, use the standard illuminant
D65 as the reference for pure white, modelling ideal day light. The
correlated colour temperature of D65 is called 6500K, however it's
actually 6504K, but
.BR redshift 's
defines this illuminant has having the colour temperature 6500K.
This means that 6500K is the neutral (no effect) colour temperature.
.PP
The current version
.B redshift
assumes the monitor uses sRGB. However
this is usually only true for CRT monitors. HDR-capable monitors
particular diverges significant for sRGB. This means that the display
colour does not perfectly correlated to the specified colour temperate.
Lower (more red) colour temperatures, about 1900K and below, are out of
gamut, and thus incorrect even on sRGB monitors.

.SH EXIT STATUS
Default.

.SH EXAMPLES
Example for the superelliptical roundabout in Stockholm, Sweden:
.RS
.nf

redshift -l 59.333:18.065 -t 5700:3600 -b 1:0.8
.fi
.RE
.PP
Example configuration file equivalent to above command:
.RS
.nf

[redshift]
temperature-day=5700
temperature-night=3600
brightness-day=1
brightness-night=0.8
location-provider=manual

[manual]
lat=59.333
lon=18.065
.fi
.RE
.PP
Sample hook script:
.RS
.nf

#!/bin/sh
case "$1" in
  period-changed)
    notify-send "redshift-ng" "Period changed from $2 to $3";;
esac
.fi
.RE

.SH KNOWN ISSUES
.SS No or incorrect effect on cursor
Some graphics drivers apply the effect (colour corrects) twice or not at
all on hardware cursors. It is often possible to reconfigure the display
server to use software cursors, to avoid this problem, however at mouse
pointer performance cost that may be noticeable on very low-end computer.

.SS D65-flashes
For some versions of some graphics drivers, there will be an occasional
flash where gamma ramps are not applied to the output.

.SS Limited hardware support
Low-end hardware, especially embedded devices, often lack colour
correction features
.B redshift
abuse to apply its effect.
.B redshift
is not always able to tell if support is missing.

.SS Limited software support
.B redshift
does not yet support Wayland. If your environment contains the
variable
.IR WAYLAND_DISPLAY ,
you are using a Wayland compositor and cannot
currently expect
.B redshift
to work. Even with Wayland support, it would be up to each individual
Wayland compositor to opt in to support applications like
.BR redshift .

.SS Backlight control
.B redshift
uses gamma ramps rather than backlight control to adjust
brightness. This actually intentional and for your best. Most
contemporary monitors require Pulse-Width Modulation, which causes
flicker than can cause eye-strain and headaches, to adjust backlight.
Using gamma ramps is a safe option, it's also considerably less work
basically no extra code and posses no additional limitations. It's often
not possible to adjust backlight on desktop monitors from software, for
devices for which it is possible (mostly telephones and laptops, however
not all have fine-grained enough configurability to be usable) it's not
possible from software to determine well enough how changing the
backlight settings changes the backlight physically. If you still want
backlight to be controlled, you can hook in a tool such as
.BR adjbacklight (1).

.SS Flickering and temporary suspension
.B redshift
uses the gamma ramps for the monitor to apply it's effect. The
gamma ramps where originally intended for colour correction. Therefore
there is no standardised why have multiple applications applying
different effects without overriding each other. This can cause
continuous flicker if multiple instance are running or effects
temporarily disappearing. By default,
.B redshift
uses
.BR coopgammad (1),
which is a daemon applications can opt to use instead of directly
setting the gamma ramps themselves,
.BR coopgammad (1)
can then calculate the result of all
of the effects and apply them as one, allowing the user to use multiple
applications that apply different effects. However
.BR coopgammad (1)
still has to compete with applications that does not use it.

.SS DRM and display servers
Using the DRM gamma ramp adjustment method can block starting or
switching to and already started display server (like X). Users may
also find that trying to switch to and an already started display cases
the computer hang, or more precisely appear to hang, as the display
server is not beign presented, the screen freezes, and the keyboard
doesn't do anything. (Once upon a time, this wasn't as catastrophic,
and it probably depend on display server implementation details.) The
only solution, abort from restarting the computer, is to remote into
it and kill the display server.

.SH RATIONALE
To prevent the user from accidental making the screen black, brightness
level below 0.1 are forbidden.
.PP
To prevent colour distortion and making the screen too white, brightness
level above 1.0 are forbidden.
.PP
Gamma correction is preserved for backwards compatibility and is
deprecated (gamma parameters in particular).
.PP
.RB \(dq : \(dq
was used as the option delimited for
.B -l
and
.B -m
in the original
.BR redshift ,
this is preserved for backwards compatbility. However because
some new options are expected to have
.RB \(dq : \(dq
in their value,
.RB \(dq ; \(dq
has added as an additional delimiter. Despite this
.RB \(dq : \(dq
is still the preferred delimiter as it is more user-friendly
and use of options that require delimiting with
.RB \(dq ; \(dq
is uncommon.

.SH NOTES
\(dqColour temperature\(dq, or just \(dqtemperature\(dq, is actually short for
\(dqcorrelated colour temperature\(dq. (Your monitor is not a black-body
radiator.) And specifically the correlated colour temperature of the
monitor's whitepoint.
.PP
It's common for users to miss to specify a coordinate as negative,
which, if missed on the longitude can swap day and night. The latitude
is negative on the southern hemisphere and the longitude is negative on
the western hemisphere.

.SH SEE ALSO
.BR cg-tools (7),
.BR coopgammad (1),
.BR radharc (1)