1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12
13. 13
14. 14
15. 15
16. 16
17. 17
18. 18
19. 19
20. 20
21. 21
22. 22
23. 23
24. 24
25. 25
26. 26
27. 27
28. 28
29. 29
30. 30
31. 31
32. 32
33. 33
34. 34
35. 35
36. 36
37. 37
38. 38
39. 39
40. 40
41. 41
42. 42
43. 43
44. 44
45. 45
46. 46
47. 47
48. 48
49. 49
50. 50
51. 51
52. 52
53. 53
54. 54
55. 55
56. 56
57. 57
58. 58
59. 59
60. 60
61. 61
62. 62
63. 63
64. 64
65. 65
66. 66
67. 67
68. 68
69. 69
70. 70
71. 71
72. 72
73. 73
74. 74
75. 75
76. 76
77. 77
78. 78
79. 79
80. 80
81. 81
82. 82
83. 83
84. 84
85. 85
86. 86
87. 87
88. 88
89. 89
90. 90
91. 91
92. 92
93. 93
94. 94
95. 95
96. 96
97. 97
98. 98
99. 99
100. 100
101. 101
102. 102
103. 103
104. 104
105. 105
106. 106
107. 107
108. 108
109. 109
110. 110
111. 111
112. 112
113. 113
114. 114
115. 115
116. 116
117. 117
118. 118
119. 119
120. 120
121. 121
122. 122
123. 123
124. 124
125. 125
126. 126
127. 127
128. 128
129. 129
130. 130
131. 131
132. 132
133. 133
134. 134
135. 135
136. 136
137. 137
138. 138
139. 139
140. 140
141. 141
142. 142
143. 143

// Copyright (C) 2025 Shota FUJI
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
// SPDX-License-Identifier: GPL-3.0-only

= sunwait(1)
:docdate: 2025-07-09
:doctype: manpage
:mansource: sunwait

== Name

sunwait - Calculates sunrise or sunset times

== Synposis

// TODO: Split these into dedicated pages

*sunwait* *poll* [_general options_] [_calculation options_]

*sunwait* *wait* [_general options_] [_calculation options_]

*sunwait* *list* [_DAYS_] [_general options_] [_calculation options_]

*sunwait* *report* [*d* _<DAY>_] [*m* _<MONTH>_] [*y* _<YEAR>_] [_general options_] [_calculation options_]

*sunwait* *report* *today* [_options_] [_calculation options_]

== Description

Sunwait calculates, displays, or waits for sunrise or sunset times at the given location.

*poll* will be called if no command is specified.

== Options

=== General options

++[++*no*]*debug*::
	Prints debug logs. *wait* command exits in one minute if this option is set.

++[++*no*]*version*::
	Print the version number.

++[++*no*]*help*::
	Print help message.

++[++*no*]*gmt*::
	Print times in GMT.

=== Calculation options

_TWILIGHT TYPE_::
*sunwait* considers it's day when twilight starts and night when twilight ends.
This option sets a twilight type, which defines an angle of the Sun to consider twilight.
Possible values are:

* *daylight*      Top of the Sun just below (0 degrees) the horizon.
* *civil*         Civil twilight, top of the Sun 6 degrees below the horizon.
* *nautical*      Nautical twilight, top of the Sun 12 degrees below the horizon.
* *astronomical*  Astronomical twilight, top of the Sun 18 degrees below the horizon.

+
The default value is *daylight*.
You can also set arbitrary angle with "*angle* _<degree>_".

_SUNRISE OR SUNSET_::
Targets sunrise or sunset when set.
If this option is not set, *sunwait* targets both.

* *rise*   Sunrise, the Sun rose and the twilight starts.
* *set*    Sunset, the Sun set past the twilight.

*offset* _OFFSET_::
Time offset to add to sunrise time and subtract from sunset time.
This offset value shifts sunrise and sunset time towards noon by the specified amount.
The value can be either of _MM_ (minutes) or _HH:MM_, and can have minus sign to represent negative amount.

_LATITUDE_::
Degrees in positive floating point without a unit, suffixed with *N* or *S*.
When unspecified, this will be the latitude of Bingham, England.

_LONGITUDE_::
Degrees in positive floating point without a unit, suffixed with *E* or *W*.
When unspecified, this will be the longitude of Bingham, England.

_DAYS_::
Prints report for next _N_ days, where _N_ is the specified value.
Defaults to *1*.

*d* _<DAY>_::
Day of the month. 1 to 31.

*m* _<MONTH>_::
Month. 1 to 12.

*y* _<YEAR>_::
Years since 2000. 0 to 99.

== Exit status

*0*    Command successfully ended.

*1*    Error, uncategorized or generic.

*2*    It's day or twilight. Only *poll* exits with this status.

*3*    It' night (after twilight). Only *poll* exits with this status.

== Examples

Prints it's DAY or NIGHT at Giza Necropolis.

[,shell]
----
sunwait poll 29.977435N 31.132484E
----

Waits for 10 minutes before sunset at Giza Necropolis.

[,shell]
----
sunwait wait set offset 10 29.977435N 31.132484E
----

Wait until 1 hour 15 minutes 10 seconds before the Sun rises in Greenwich, London.

[,shell]
----
sunwait wait rise offset -1:15:10 51.477932N 0.000000E
----