1CAL(1) User Commands CAL(1)
2
6 cal - display a calendar
7
9 cal [options] [[[day] month] year]
10 cal [options] [timestamp|monthname]
12
14 cal displays a simple calendar. If no arguments are specified, the
15 current month is displayed.
16 The month may be specified as a number (1-12), as a month name or as an
18 abbreviated month name according to the current locales.
19 Two different calendar systems are used, Gregorian and Julian. These
21 are nearly identical systems with Gregorian making a small adjustment
22 to the frequency of leap years; this facilitates improved
23 synchronization with solar events like the equinoxes. The Gregorian
24 calendar reform was introduced in 1582, but its adoption continued up
25 to 1923. By default cal uses the adoption date of 3 Sept 1752. From
26 that date forward the Gregorian calendar is displayed; previous dates
27 use the Julian calendar system. 11 days were removed at the time of
28 adoption to bring the calendar in sync with solar events. So Sept 1752
29 has a mix of Julian and Gregorian dates by which the 2nd is followed by
30 the 14th (the 3rd through the 13th are absent).
31 Optionally, either the proleptic Gregorian calendar or the Julian
33 calendar may be used exclusively. See --reform below.
34
36 -1, --one
37 Display single month output. (This is the default.)
38 -3, --three
40 Display three months spanning the date.
41 -n , --months number
43 Display number of months, starting from the month containing the
44 date.
45 -S, --span
47 Display months spanning the date.
48 -s, --sunday
50 Display Sunday as the first day of the week.
51 -m, --monday
53 Display Monday as the first day of the week.
54 -v, --vertical
56 Display using a vertical layout (aka ncal(1) mode).
57 --iso
59 Display the proleptic Gregorian calendar exclusively. This option
60 does not affect week numbers and the first day of the week. See
61 --reform below.
62 -j, --julian
64 Use day-of-year numbering for all calendars. These are also called
65 ordinal days. Ordinal days range from 1 to 366. This option does
66 not switch from the Gregorian to the Julian calendar system, that
67 is controlled by the --reform option.
68 Sometimes Gregorian calendars using ordinal dates are referred to
70 as Julian calendars. This can be confusing due to the many date
71 related conventions that use Julian in their name: (ordinal) julian
72 date, julian (calendar) date, (astronomical) julian date,
73 (modified) julian date, and more. This option is named julian,
74 because ordinal days are identified as julian by the POSIX
75 standard. However, be aware that cal also uses the Julian calendar
76 system. See DESCRIPTION above.
77 --reform val
79 This option sets the adoption date of the Gregorian calendar
80 reform. Calendar dates previous to reform use the Julian calendar
81 system. Calendar dates after reform use the Gregorian calendar
82 system. The argument val can be:
83 • 1752 - sets 3 September 1752 as the reform date (default). This
85 is when the Gregorian calendar reform was adopted by the
86 British Empire.
87 • gregorian - display Gregorian calendars exclusively. This
89 special placeholder sets the reform date below the smallest
90 year that cal can use; meaning all calendar output uses the
91 Gregorian calendar system. This is called the proleptic
92 Gregorian calendar, because dates prior to the calendar
93 system’s creation use extrapolated values.
94 • iso - alias of gregorian. The ISO 8601 standard for the
96 representation of dates and times in information interchange
97 requires using the proleptic Gregorian calendar.
98 • julian - display Julian calendars exclusively. This special
100 placeholder sets the reform date above the largest year that
101 cal can use; meaning all calendar output uses the Julian
102 calendar system.
103 See DESCRIPTION above.
105 -y, --year
107 Display a calendar for the whole year.
108 -Y, --twelve
110 Display a calendar for the next twelve months.
111 -w, --week[=number]
113 Display week numbers in the calendar (US or ISO-8601). See the
114 NOTES section for more details.
115 --color[=when]
117 Colorize the output. The optional argument when can be auto, never
118 or always. If the when argument is omitted, it defaults to auto.
119 The colors can be disabled; for the current built-in default see
120 the --help output. See also the COLORS section.
121 -h, --help
123 Display help text and exit.
124 -V, --version
126 Print version and exit.
127
129 Single digits-only parameter (e.g., 'cal 2020')
130 Specifies the year to be displayed; note the year must be fully
131 specified: cal 89 will not display a calendar for 1989.
132 Single string parameter (e.g., 'cal tomorrow' or 'cal August')
134 Specifies timestamp or a month name (or abbreviated name) according
135 to the current locales.
136 The special placeholders are accepted when parsing timestamp, "now"
138 may be used to refer to the current time, "today", "yesterday",
139 "tomorrow" refer to of the current day, the day before or the next
140 day, respectively.
141 The relative date specifications are also accepted, in this case
143 "+" is evaluated to the current time plus the specified time span.
144 Correspondingly, a time span that is prefixed with "-" is evaluated
145 to the current time minus the specified time span, for example
146 '+2days'. Instead of prefixing the time span with "+" or "-", it
147 may also be suffixed with a space and the word "left" or "ago" (for
148 example '1 week ago').
149 Two parameters (e.g., 'cal 11 2020')
151 Denote the month (1 - 12) and year.
152 Three parameters (e.g., 'cal 25 11 2020')
154 Denote the day (1-31), month and year, and the day will be
155 highlighted if the calendar is displayed on a terminal. If no
156 parameters are specified, the current month’s calendar is
157 displayed.
158
160 A year starts on January 1. The first day of the week is determined by
161 the locale or the --sunday and --monday options.
162 The week numbering depends on the choice of the first day of the week.
164 If it is Sunday then the customary North American numbering is used,
165 where 1 January is in week number 1. If it is Monday (-m) then the ISO
166 8601 standard week numbering is used, where the first Thursday is in
167 week number 1.
168
170 The output colorization is implemented by terminal-colors.d(5)
171 functionality. Implicit coloring can be disabled by an empty file
172 /etc/terminal-colors.d/cal.disable
174 for the cal command or for all tools by
176 /etc/terminal-colors.d/disable
178 The user-specific $XDG_CONFIG_HOME/terminal-colors.d or
180 $HOME/.config/terminal-colors.d overrides the global setting.
181 Note that the output colorization may be enabled by default, and in
183 this case terminal-colors.d directories do not have to exist yet.
184
186 A cal command appeared in Version 6 AT&T UNIX.
187
189 The default cal output uses 3 September 1752 as the Gregorian calendar
190 reform date. The historical reform dates for the other locales,
191 including its introduction in October 1582, are not implemented.
192 Alternative calendars, such as the Umm al-Qura, the Solar Hijri, the
194 Ge’ez, or the lunisolar Hindu, are not supported.
195
197 For bug reports, use the issue tracker at
198 https://github.com/util-linux/util-linux/issues.
199
201 The cal command is part of the util-linux package which can be
202 downloaded from Linux Kernel Archive
203 <https://www.kernel.org/pub/linux/utils/util-linux/>.
204util-linux 2.38.1 2022-05-11 CAL(1)