1.\" Copyright (c) 1989, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)calendar.1 8.1 (Berkeley) 6/29/93 29.\" $FreeBSD: head/usr.bin/calendar/calendar.1 314436 2017-02-28 23:42:47Z imp $ 30.\" 31.Dd September 14, 2020 32.Dt CALENDAR 1 33.Os 34.Sh NAME 35.Nm calendar 36.Nd reminder service 37.Sh SYNOPSIS 38.Nm 39.Op Fl A Ar num 40.Op Fl a 41.Op Fl B Ar num 42.Op Fl d 43.Op Fl F Ar friday 44.Op Fl f Ar calendar_file 45.Op Fl H Ar calendar_home 46.Op Fl h 47.Op Fl L Ar latitude,longitude[,elevation] 48.Op Fl s Ar category 49.Op Fl T Ar hh:mm[:ss] 50.Op Fl t Ar [[[CC]YY]MM]DD 51.Op Fl U Ar \(+-hh[[:]mm] 52.Op Fl W Ar num 53.Sh DESCRIPTION 54The 55.Nm 56utility processes calendar files and displays lines that fall into the 57specified date range. 58On the day before a weekend (normally Friday), events for the next 59three days are displayed. 60.Pp 61The following options are available: 62.Bl -tag -width Ds 63.It Fl A Ar num 64Print lines from today and the next 65.Ar num 66days (forward, future). 67.It Fl a 68Process the calendar files 69.Pa ( ~/.calendar/calendar ) 70of all users and mail the results to them. 71This requires super-user privileges. 72.It Fl B Ar num 73Print lines from today and the previous 74.Ar num 75days (backward, past). 76.It Fl d 77Print debug messages. 78This flag may be repeated multiple times to increase the verbosity. 79.It Fl F Ar friday 80Specify which day of the week is 81.Dq Friday 82(the day before the weekend begins). 83The default is 5. 84.It Fl f Pa calendar_file 85Use 86.Ar calendar_file 87as the default calendar file. 88If specified as 89.Pa - , 90then read from standard input. 91Note that this flag cannot be used together with the 92.Fl a 93flag. 94.It Fl H Pa calendar_home 95Use 96.Ar calendar_home 97as the calendar home directory. 98Note that this flag cannot be used together with the 99.Fl a 100flag. 101.It Fl h 102Show the utility usage. 103.It Fl L Ar latitude,longitude[,elevation] 104Specify the location for use in some calculations, such as the current 105Sun and Moon positions and their rise and set times. 106The 107.Ar latitude 108and 109.Ar longitude 110arguments are given in units of degrees, 111which can be a decimal number or in the DMS format of 112.Dq [+-]d:m:s . 113The 114.Ar elevation 115argument is optional and is given in units of meters. 116If not specified, the 117.Ar latitude 118and 119.Ar elevation 120arguments are default to 0, while the 121.Ar longitude 122argument is calculated from the adopted UTC offset 123(i.e., 15 degrees times the UTC offset in hours). 124.It Fl s Ar category 125Show information of the specified 126.Ar category , 127which can take the following values: 128.Pp 129.Bl -tag -width chinese -compact 130.It Cm chinese 131Show the Chinese calendar and the 24 solar terms (a.k.a. Jieqi) in this year. 132.It Cm julian 133Show the Julian calendar. 134.It Cm moon 135Show Moon position, phases, rise and set times, and lunar events in this year. 136.It Cm sun 137Show Sun position, rise and set times, and solar events in this year. 138.El 139.It Fl T Ar hh:mm[:ss] 140Specify the time of day to use instead of the current system time. 141This time is only used in determining the Sun and Moon information. 142.It Fl t Ar [[[CC]YY]MM]DD 143Act like the specified value is 144.Dq today 145instead of using the current date. 146If 147.Ar YY 148is specified, but 149.Ar CC 150is not, 151a value for 152.Ar YY 153between 69 and 99 results in a 154.Ar CC 155value of 19. 156Otherwise, a 157.Ar CC 158value of 20 is used. 159.It Fl U Ar \(+-hh[[:]mm] 160Specify the timezone with a UTC offset. 161If not specified, the timezone of localtime is used. 162.It Fl W Ar num 163Print lines from today and the next 164.Ar num 165days (forward, future). 166Similar to the 167.Fl A 168option but ignore weekends when calculating the number of days. 169.El 170.Sh FILE FORMAT 171The calendar files are preprocessed by a limited subset of 172.Xr cpp 1 173internally, allowing the inclusion of shared calendar files. 174This limited directive subset consists of 175.Sy #include , 176.Sy #ifndef , 177.Sy #endif , 178and 179.Sy #define . 180If the calendar file to be included (via the 181.Sy #include 182directive) is not referenced by a full pathname, 183.Nm 184searches in its home directory 185.Pa ( ~/.calendar 186or specified by the 187.Fl H 188flag) 189first, then in the 190.Pa @@CALENDAR_ETCDIR@@ 191directory, and finally in the 192.Pa @@CALENDAR_DIR@@ 193directory. 194Both the C-style comment 195.Pq Li /* ... */ 196and C++-style comment 197.Pq Li // ... 198are supported. 199.Pp 200The default calendar used by the 201.Nm 202utility is the 203.Dq Gregorian calendar . 204In addition, the following calendars are supported: 205.Bl -tag -offset indent -width chinese -compact 206.It Julian 207The Julian calendar 208.It Chinese 209The Chinese calendar 210.El 211Specify 212.Dq CALENDAR=<calendar> 213in the calendar file to select the calendar to use. 214The calendar will be reset to the default Gregorian calendar 215at the end of the calendar file. 216When a non-default calendar is selected, the matched events will 217be printed with a secondary date formatted in the selected calendar. 218.Pp 219To handle calendars in national code table, specify 220.Dq LANG=<locale> 221in the calendar file, before the national names being used. 222This setting will also make the event date in this calendar file 223be formatted in national names in the output. 224The locale change will be reset at the end of the calendar file. 225.Pp 226To handle the local name of sequences, specify them as 227.Dq SEQUENCE=<first> <second> <third> <fourth> <fifth> <last> 228in the calendar file. 229.Pp 230The names of the following special days are recognized: 231.Bl -tag -offset indent -width 1234567890123456 -compact 232.It Easter 233Catholic Easter. 234.It Paskha 235Orthodox Easter. 236.It Advent 237First Sunday of Advent. 238.It NewMoon 239The lunar New Moon. 240.It FullMoon 241The lunar Full Moon. 242.It MarEquinox 243The solar equinox in March. 244.It JunSolstice 245The solar solstice in June. 246.It SepEquinox 247The solar equinox in September. 248.It DecSolstice 249The solar solstice in December. 250.It ChineseNewYear 251The first day of the Chinese year. 252.It ChineseQingming 253The Chinese Qingming festival (a.k.a. Tomb-Sweeping Day). 254.It ChineseJieqi 255The 24 solar terms (Jieqi) in Chinese calendar. 256.El 257These names may be reassigned to their local names via an assignment 258like 259.Dq <name>=<local_name> 260in the calendar file, and then the 261.Dq <local_name> 262can also be used to specify the date. 263.Pp 264Other lines should begin with a year (optional), month and day. 265They may be entered in multiple formats, either numeric or as 266character strings. 267If the proper locale is set (via 268.Dq LANG=<locale> ) , 269national month and weekday names can be used as well. 270Additional rules are as follows: 271.Bl -bullet -offset indent 272.It 273Two numbers default to the month followed by the day. 274.It 275A single asterisk 276.Pq Sq * 277matches every month. 278.It 279A day without a month matches that day of every week. 280.It 281A day of zero means the last day of previous month. 282.It 283The names of special days may be followed by a 284positive or negative integer to represent the date offset, like: 285.Dq Easter+3 286or 287.Dq Paskha-4 . 288.It 289A weekday may be followed by a sequence name 290.Dq ( First 291.Li ... 292.Dq Fifth , 293and 294.Dq Last ) 295to specify moving events, like 296.Dq the last Monday in April . 297Numeric sequence 298.Dq ( \(+-[12345] ) 299can also be used. 300.It 301A date may be followed by an asterisk 302.Pq Sq * 303to indicate that it is not fixed (i.e., changes from year to year). 304.It 305A date must be immediately followed by <tab> character(s), and then 306followed by the event description. 307Lines without containing a <tab> character are invalid and thus ignored. 308.It 309Lines starting with a <tab> character are treated as a continuation of 310the previous line, allowing multiple-line description of an event. 311.El 312.Pp 313The supported date styles can vary with calendars. 314In the Gregorian calendar, the following date styles are supported: 315.Bd -literal -offset indent 316Date ::= Year . '/' . Month . '/' . DayOfMonth | 317 Year . ' ' . Month . ' ' . DayOfMonth | 318 Month . '/' . DayOfMonth | 319 Month . ' ' . DayOfMonth | 320 Month . '/' . DayOfWeek . Index | 321 Month . ' ' . DayOfWeek . Index | 322 MonthName . '/' . AllDays | 323 MonthName . ' ' . AllDays | 324 AllDays . '/' . MonthName | 325 AllDays . ' ' . MonthName | 326 AllMonths . '/' . DayOfMonth | 327 AllMonths . ' ' . DayOfMonth | 328 DayOfMonth . '/' . AllMonths | 329 DayOfMonth . ' ' . AllMonths | 330 DayOfMonth . '/' . Month | 331 DayOfMonth . ' ' . Month | 332 DayOfWeek . Index . '/' . MonthName | 333 DayOfWeek . Index . ' ' . MonthName | 334 DayOfWeek . Index 335 SpecialDay . Offset 336 337Year ::= '0' ... '9' | '00' ... '09' | '10' ... '99' | 338 '100' ... '999' | '1000' ... '9999' 339 340Month ::= MonthName | MonthNumber 341MonthNumber ::= '0' ... '9' | '00' ... '09' | '10' ... '12' 342MonthName ::= MonthNameShort | MonthNameLong 343MonthNameLong ::= 'January' ... 'December' 344MonthNameShort ::= 'Jan' ... 'Dec' | 'Jan.' ... 'Dec.' 345 346DayOfWeek ::= DayOfWeekShort | DayOfWeekLong 347DayOfWeekShort ::= 'Mon' ... 'Sun' 348DayOfWeekLong ::= 'Monday' ... 'Sunday' 349DayOfMonth ::= '0' ... '9' | '00' ... '09' | '10' ... '29' | 350 '30' ... '31' 351 352AllMonths ::= '*' 353AllDays ::= '*' 354 355Index ::= '' | IndexName | 356 '+' . IndexNumber | '-' . IndexNumber 357IndexName ::= 'First' | 'Second' | 'Third' | 'Fourth' | 358 'Fifth' | 'Last' 359IndexNumber ::= '1' ... '5' 360 361Offset ::= '' | '+' . OffsetNumber | '-' . OffsetNumber 362OffsetNumber ::= '0' ... '9' | '00' ... '99' | '000' ... '299' | 363 '300' ... '359' | '360' ... '365' 364 365SpecialDay ::= 'Easter' | 'Paskha' | 'Advent' | 366 'ChineseNewYear' | 367 'ChineseQingming' | 'ChineseJieqi' | 368 'NewMoon' | 'FullMoon' | 369 'MarEquinox' | 'SepEquinox' | 370 'JunSolstice' | 'DecSolstice' 371.Ed 372.Sh EXAMPLES 373Some possible calendar entries (<tab> characters highlighted as 374.Sq \fB\et\fR ) : 375.Bd -unfilled -offset indent 376CLANEDAR=Gregorian 377LANG=C 378Easter=Ostern 379 380/* Include shared calendar files */ 381#include <calendar.birthday> 382#include <calendar.holiday> 383 3846/15\fB\et\fRJune 15 (if ambiguous, will default to month/day) 385Jun. 15\fB\et\fRJune 15 38615 June\fB\et\fRJune 15 38715 *\fB\et\fR15th of every month 3880 *\fB\et\fRLast day of every month 389March/0\fB\et\fRLast day of February 3902010/4/15\fB\et\fR15 April 2010 3912020/11/03*\fB\et\fRU.S. Election Day ('*' indicates a movable event) 392 393Thursday\fB\et\fREvery Thursday 394SatSecond\fB\et\fRSecond Saturday of every month 395Apr/Mon\fB\et\fREvery Monday in April 396May Sun+2\fB\et\fRSecond Sunday in May (Muttertag) 39704/SunLast\fB\et\fRLast Sunday in April, 398\fB\et\fRSummer time in Europe // continuation of previous line 399 400Easter\fB\et\fREaster 401Ostern-2\fB\et\fRGood Friday (2 days before Easter) 402Paskha\fB\et\fROrthodox Easter 403NewMoon\fB\et\fRNew moon of every month 404.Ed 405.Sh FILES 406.Bl -tag -width calendar.123456789012 -compact 407.It Pa calendar 408The calendar file to find in current directory. 409.It Pa ~/.calendar 410The default calendar home directory. 411A 412.Xr chdir 2 413is done into this directory if it exists. 414.It Pa ~/.calendar/calendar 415The calendar file to use if no calendar file exists in the current directory. 416.It Pa ~/.calendar/nomail 417Do not send mail if this file exists. 418.It Pa @@CALENDAR_ETCDIR@@/default 419The system-wide default calendar file, which is used if the 420.Pa ~/.calendar/calendar 421doesn't exist. 422This fallback calendar file is ignored in the 423.Fl a 424mode. 425.El 426.Pp 427The following calendar files are provided in 428.Pa @@CALENDAR_DIR@@ : 429.Pp 430.Bl -tag -width calendar.123456789012 -compact 431.It Pa calendar.all 432File which includes all the calendar files. 433.It Pa calendar.australia 434Calendar of events in Australia. 435.It Pa calendar.birthday 436Births and deaths of famous (and not-so-famous) people. 437.It Pa calendar.brazilian 438Calendar of events in Brazil. 439.It Pa calendar.canada 440Canadian holidays. 441.It Pa calendar.chinese 442Calendar of events in China. 443.It Pa calendar.christian 444Christian holidays. 445.It Pa calendar.computer 446Days of special significance to computer people. 447.It Pa calendar.croatian 448Calendar of events in Croatia. 449.It Pa calendar.discord 450Discordian calendar (all rites reversed). 451.It Pa calendar.dragonfly 452.Dx 453related events. 454.It Pa calendar.dutch 455Calendar of events in the Netherlands. 456.It Pa calendar.fictional 457Fantasy and fiction dates (mostly 458.Em Load Of The Rings ) . 459.It Pa calendar.french 460Calendar of events in France. 461.It Pa calendar.german 462Calendar of events in Germany. 463.It Pa calendar.history 464Miscellaneous history. 465.It Pa calendar.holiday 466Other holidays, including the not-well-known, obscure, and 467.Em really 468obscure. 469.It Pa calendar.hungarian 470Calendar of events in Hungary. 471.It Pa calendar.judaic 472Jewish holidays. 473This calendar should be updated yearly by the local system administrator 474so that roving holidays are set correctly for the current year. 475The entries for this calendar have been obtained from the port 476.Pa deskutils/hebcal . 477.It Pa calendar.misc 478Miscellaneous events. 479.It Pa calendar.music 480Musical events, births, and deaths. 481Strongly oriented toward rock 'n' roll and classical. 482.It Pa calendar.newzealand 483Calendar of events in New Zealand. 484.It Pa calendar.orthodox 485Orthodox holidays. 486.It Pa calendar.russian 487Russian calendar. 488.It Pa calendar.southafrica 489Calendar of events in South Africa. 490.It Pa calendar.space 491Aerospace and astronomical events. 492.It Pa calendar.uk 493Calendar of events in U.K. 494.It Pa calendar.ukrainian 495Calendar of events in Ukraine. 496.It Pa calendar.ushistory 497U.S.\& history. 498.It Pa calendar.usholiday 499U.S.\& holidays. 500This calendar should be updated yearly by the local system administrator 501so that roving holidays are set correctly for the current year. 502.It Pa calendar.world 503Includes all calendar files except for national ones. 504.El 505.Sh COMPATIBILITY 506The 507.Nm 508utility previously selected lines which had the correct date anywhere 509in the line. 510This is no longer true: the date is only recognized when it occurs 511at the beginning of a line. 512.Sh SEE ALSO 513.Xr at 1 , 514.Xr cal 1 , 515.Xr mail 1 , 516.Xr cron 8 517.Rs 518.%A Edward M. Reingold 519.%A Nachum Dershowitz 520.%B Calendrical Calculations: The Ultimate Edition (4th Edition) 521.%I Cambridge University Press 522.%D 2018 523.%O ISBN: 9781107057623 524.Re 525.Sh HISTORY 526A 527.Nm 528command appeared in 529.At v7 . 530.Pp 531The 532.Nm 533utility was significantly enhanced in 534.Fx 9.0 535by 536.An Edwin Groothuis Aq Mt edwin@FreeBSD.org , 537and was later rewritten to support multiple calendars in 538.Dx 5.9 539by 540.An Aaron LI Aq Mt aly@aaronly.me . 541.Sh NOTES 542The new and full moons are happening on the day indicated. 543They can happen in the time period from the early morning to 544the late evening. 545.Pp 546The adopted methods to calculate solar and lunar events are 547simplified astronomical algorithms, so the accuracy of events is 548within several minutes, provided that the precise location is specified. 549Druids and Werewolves should double-check the start and end time of 550solar and lunar events. 551.Sh BUGS 552The 553.Nm 554internal preprocessor only recognizes 555.Sy #include , 556.Sy #ifndef , 557.Sy #endif , 558and 559.Sy #define . 560Quoted or escaped comment marks are not supported yet. 561.Pp 562An event can repeat at most 100 times in the specified date range. 563The most repeated event is an weekly event, so a maximum of 100 repeats 564covers a date range of about 2 years. 565If more repeats of events are needed, you're likely using 566.Nm 567in the wrong way ;) 568