CALENDAR(1)

NAME
calendar - reminder service

SYNOPSIS
calendar [-A num] [-a] [-B num] [-d] [-F friday] [-f calendar_file] [-H calendar_home] [-h] [-L latitude,longitude[,elevation]] [-s category] [-T hh:mm[:ss]] [-t [[[CC]YY]MM]DD] [-U ±hh[[:]mm]] [-W num]

DESCRIPTION
The calendar utility processes calendar files and displays lines that fall into the specified date range. On the day before a weekend (normally Friday), events for the next three days are displayed.

The following options are available:

-A num
    Print lines from today and the next num days (forward, future).

-a  Process the calendar files (~/.calendar/calendar) of all users and mail the results to them. This requires super-user privileges.

-B num
    Print lines from today and the previous num days (backward, past).

-d  Print debug messages. This flag may be repeated multiple times to increase the verbosity.

-F friday
    Specify which day of the week is “Friday” (the day before the weekend begins). The default is 5.

-f calendar_file
    Use calendar_file as the default calendar file. If specified as -, then read from standard input. Note that this flag cannot be used together with the -a flag.

-H calendar_home
    Use calendar_home as the calendar home directory. Note that this flag cannot be used together with the -a flag.

-h  Show the utility usage.

-L latitude,longitude[,elevation]
    Specify the location for use in some calculations, such as the current Sun and Moon positions and their rise and set times. The latitude and longitude arguments are given in units of degrees, which can be a decimal number or in the DMS format of “[+-]d:m:s”. The elevation argument is optional and is given in units of meters. If not specified, the latitude and elevation arguments are default to 0, while the longitude argument is calculated from the adopted UTC offset (i.e., 15 degrees times the UTC offset in hours).

-s category
    Show information of the specified category, which can take the following values:

    chinese
        Show the Chinese calendar and the 24 solar terms (a.k.a. Jieqi) in this year.
    julian
        Show the Julian calendar.
    moon
        Show Moon position, phases, rise and set times, and lunar events in this year.
    sun Show Sun position, rise and set times, and solar events in this year.

-T hh:mm[:ss]
    Specify the time of day to use instead of the current system time. This time is only used in determining the Sun and Moon information.

-t [[[CC]YY]MM]DD
    Act like the specified value is “today” instead of using the current date. If YY is specified, but CC is not, a value for YY between 69 and 99 results in a CC value of 19. Otherwise, a CC value of 20 is used.

-U ±hh[[:]mm]
    Specify the timezone with a UTC offset. If not specified, the timezone of localtime is used.

-W num
    Print lines from today and the next num days (forward, future). Similar to the -A option but ignore weekends when calculating the number of days.

FILE FORMAT
The calendar files are preprocessed by a limited subset of cpp(1) internally, allowing the inclusion of shared calendar files. This limited directive subset consists of #include, #ifndef, #endif, and #define. If the calendar file to be included (via the #include directive) is not referenced by a full pathname, calendar searches in its home directory (~/.calendar or specified by the -H flag) first, then in the /etc/calendar directory, and finally in the /usr/share/calendar directory. Both the C-style comment (/* ... */) and C++-style comment (// ...) are supported.

The default calendar used by the calendar utility is the “Gregorian calendar”. In addition, the following calendars are supported:
Julian
    The Julian calendar
Chinese
    The Chinese calendar
Specify “CALENDAR=<calendar>” in the calendar file to select the calendar to use. The calendar will be reset to the default Gregorian calendar at the end of the calendar file. When a non-default calendar is selected, the matched events will be printed with a secondary date formatted in the selected calendar.

To handle calendars in national code table, specify “LANG=<locale>” in the calendar file, before the national names being used. This setting will also make the event date in this calendar file be formatted in national names in the output. The locale change will be reset at the end of the calendar file.

To handle the local name of sequences, specify them as “SEQUENCE=<first> <second> <third> <fourth> <fifth> <last>” in the calendar file.

The names of the following special days are recognized:
Easter
    Catholic Easter.
Paskha
    Orthodox Easter.
Advent
    First Sunday of Advent.
NewMoon
    The lunar New Moon.
FullMoon
    The lunar Full Moon.
MarEquinox
    The solar equinox in March.
JunSolstice
    The solar solstice in June.
SepEquinox
    The solar equinox in September.
DecSolstice
    The solar solstice in December.
ChineseNewYear
    The first day of the Chinese year.
ChineseQingming
    The Chinese Qingming festival (a.k.a. Tomb-Sweeping Day).
ChineseJieqi
    The 24 solar terms (Jieqi) in Chinese calendar.
These names may be reassigned to their local names via an assignment like “<name>=<local_name>” in the calendar file, and then the “<local_name>” can also be used to specify the date.

Other lines should begin with a year (optional), month and day. They may be entered in multiple formats, either numeric or as character strings. If the proper locale is set (via “LANG=<locale>”), national month and weekday names can be used as well. Additional rules are as follows:

•   Two numbers default to the month followed by the day.

•   A single asterisk (‘*’) matches every month.

•   A day without a month matches that day of every week.

•   A day of zero means the last day of previous month.

•   The names of special days may be followed by a positive or negative integer to represent the date offset, like: “Easter+3” or “Paskha-4”.

•   A weekday may be followed by a sequence name “(First” ... “Fifth”, and “Last”) to specify moving events, like “the last Monday in April”. Numeric sequence “(±[12345]”) can also be used.

•   A date may be followed by an asterisk (‘*’) to indicate that it is not fixed (i.e., changes from year to year).

•   A date must be immediately followed by <tab> character(s), and then followed by the event description. Lines without containing a <tab> character are invalid and thus ignored.

•   Lines starting with a <tab> character are treated as a continuation of the previous line, allowing multiple-line description of an event.

The supported date styles can vary with calendars. In the Gregorian calendar, the following date styles are supported:

    Date                    ::=     Year . '/' . Month . '/' . DayOfMonth |
                                    Year . ' ' . Month . ' ' . DayOfMonth |
                                    Month . '/' . DayOfMonth |
                                    Month . ' ' . DayOfMonth |
                                    Month . '/' . DayOfWeek . Index |
                                    Month . ' ' . DayOfWeek . Index |
                                    MonthName . '/' . AllDays |
                                    MonthName . ' ' . AllDays |
                                    AllDays . '/' . MonthName |
                                    AllDays . ' ' . MonthName |
                                    AllMonths . '/' . DayOfMonth |
                                    AllMonths . ' ' . DayOfMonth |
                                    DayOfMonth . '/' . AllMonths |
                                    DayOfMonth . ' ' . AllMonths |
                                    DayOfMonth . '/' . Month |
                                    DayOfMonth . ' ' . Month |
                                    DayOfWeek . Index . '/' . MonthName |
                                    DayOfWeek . Index . ' ' . MonthName |
                                    DayOfWeek . Index
                                    SpecialDay . Offset
    Year                    ::=     '0' ... '9' | '00' ... '09' | '10' ... '99' |
                                    '100' ... '999' | '1000' ... '9999'
    Month                   ::=     MonthName | MonthNumber
    MonthNumber             ::=     '0' ... '9' | '00' ... '09' | '10' ... '12'
    MonthName               ::=     MonthNameShort | MonthNameLong
    MonthNameLong           ::=     'January' ... 'December'
    MonthNameShort          ::=     'Jan' ... 'Dec' | 'Jan.' ... 'Dec.'
    DayOfWeek               ::=     DayOfWeekShort | DayOfWeekLong
    DayOfWeekShort          ::=     'Mon' ... 'Sun'
    DayOfWeekLong           ::=     'Monday' ... 'Sunday'
    DayOfMonth              ::=     '0' ... '9' | '00' ... '09' | '10' ... '29' |
                                    '30' ... '31'
    AllMonths               ::=     '*'
    AllDays                 ::=     '*'
    Index                   ::=     '' | IndexName |
                                    '+' . IndexNumber | '-' . IndexNumber
    IndexName               ::=     'First' | 'Second' | 'Third' | 'Fourth' |
                                    'Fifth' | 'Last'
    IndexNumber             ::=     '1' ... '5'
    Offset                  ::=     '' | '+' . OffsetNumber | '-' . OffsetNumber
    OffsetNumber            ::=     '0' ... '9' | '00' ... '99' | '000' ... '299' |
                                    '300' ... '359' | '360' ... '365'
    SpecialDay              ::=     'Easter' | 'Paskha' | 'Advent' |
                                    'ChineseNewYear' |
                                    'ChineseQingming' | 'ChineseJieqi' |
                                    'NewMoon' | 'FullMoon' |
                                    'MarEquinox' | 'SepEquinox' |
                                    'JunSolstice' | 'DecSolstice'

EXAMPLES
Some possible calendar entries (<tab> characters highlighted as ‘\t’):

    CLANEDAR=Gregorian
    LANG=C
    Easter=Ostern
    /* Include shared calendar files */
    #include <calendar.birthday>
    #include <calendar.holiday>
    6/15\tJune 15 (if ambiguous, will default to month/day)
    Jun. 15\tJune 15
    15 June\tJune 15
    15 *\t15th of every month
    0 *\tLast day of every month
    March/0\tLast day of February
    2010/4/15\t15 April 2010
    2020/11/03*\tU.S. Election Day ('*' indicates a movable event)
    Thursday\tEvery Thursday
    SatSecond\tSecond Saturday of every month
    Apr/Mon\tEvery Monday in April
    May Sun+2\tSecond Sunday in May (Muttertag)
    04/SunLast\tLast Sunday in April,
    \tSummer time in Europe  // continuation of previous line
    Easter\tEaster
    Ostern-2\tGood Friday (2 days before Easter)
    Paskha\tOrthodox Easter
    NewMoon\tNew moon of every month

FILES
calendar
    The calendar file to find in current directory.
~/.calendar
    The default calendar home directory. A chdir(2) is done into this directory if it exists.
~/.calendar/calendar
    The calendar file to use if no calendar file exists in the current directory.
~/.calendar/nomail
    Do not send mail if this file exists.
/etc/calendar/default
    The system-wide default calendar file, which is used if the ~/.calendar/calendar doesn't exist. This fallback calendar file is ignored in the -a mode.

The following calendar files are provided in /usr/share/calendar:

calendar.all
    File which includes all the calendar files.
calendar.australia
    Calendar of events in Australia.
calendar.birthday
    Births and deaths of famous (and not-so-famous) people.
calendar.brazilian
    Calendar of events in Brazil.
calendar.canada
    Canadian holidays.
calendar.chinese
    Calendar of events in China.
calendar.christian
    Christian holidays.
calendar.computer
    Days of special significance to computer people.
calendar.croatian
    Calendar of events in Croatia.
calendar.discord
    Discordian calendar (all rites reversed).
calendar.dragonfly
    DragonFly related events.
calendar.dutch
    Calendar of events in the Netherlands.
calendar.fictional
    Fantasy and fiction dates (mostly Load Of The Rings).
calendar.french
    Calendar of events in France.
calendar.german
    Calendar of events in Germany.
calendar.history
    Miscellaneous history.
calendar.holiday
    Other holidays, including the not-well-known, obscure, and really obscure.
calendar.hungarian
    Calendar of events in Hungary.
calendar.judaic
    Jewish holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year. The entries for this calendar have been obtained from the port deskutils/hebcal.
calendar.misc
    Miscellaneous events.
calendar.music
    Musical events, births, and deaths. Strongly oriented toward rock 'n' roll and classical.
calendar.newzealand
    Calendar of events in New Zealand.
calendar.orthodox
    Orthodox holidays.
calendar.russian
    Russian calendar.
calendar.southafrica
    Calendar of events in South Africa.
calendar.space
    Aerospace and astronomical events.
calendar.uk
    Calendar of events in U.K.
calendar.ukrainian
    Calendar of events in Ukraine.
calendar.ushistory
    U.S. history.
calendar.usholiday
    U.S. holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year.
calendar.world
    Includes all calendar files except for national ones.

COMPATIBILITY
The calendar utility previously selected lines which had the correct date anywhere in the line. This is no longer true: the date is only recognized when it occurs at the beginning of a line.

SEE ALSO
at(1), cal(1), mail(1), cron(8) Edward M. Reingold, Nachum Dershowitz, Calendrical Calculations: The Ultimate Edition (4th Edition), Cambridge University Press, 2018, ISBN: 9781107057623.

HISTORY
A calendar command appeared in AT&T UNIX.

The calendar utility was significantly enhanced in FreeBSD 9.0 by Edwin Groothuis <edwin@FreeBSD.org>, and was later rewritten to support multiple calendars in DragonFly 5.9 by Aaron LI <aly@aaronly.me>.

NOTES
The new and full moons are happening on the day indicated. They can happen in the time period from the early morning to the late evening.

The adopted methods to calculate solar and lunar events are simplified astronomical algorithms, so the accuracy of events is within several minutes, provided that the precise location is specified. Druids and Werewolves should double-check the start and end time of solar and lunar events.

BUGS
The calendar internal preprocessor only recognizes #include, #ifndef, #endif, and #define. Quoted or escaped comment marks are not supported yet.

An event can repeat at most 100 times in the specified date range. The most repeated event is an weekly event, so a maximum of 100 repeats covers a date range of about 2 years. If more repeats of events are needed, you're likely using calendar in the wrong way ;)