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 -c, --columns=columns
123 Number of columns to use. auto uses as many as fit the terminal.
124 -h, --help
126 Display help text and exit.
127 -V, --version
129 Print version and exit.
130
132 Single digits-only parameter (e.g., 'cal 2020')
133 Specifies the year to be displayed; note the year must be fully
134 specified: cal 89 will not display a calendar for 1989.
135 Single string parameter (e.g., 'cal tomorrow' or 'cal August')
137 Specifies timestamp or a month name (or abbreviated name) according
138 to the current locales.
139 The special placeholders are accepted when parsing timestamp, "now"
141 may be used to refer to the current time, "today", "yesterday",
142 "tomorrow" refer to of the current day, the day before or the next
143 day, respectively.
144 The relative date specifications are also accepted, in this case
146 "+" is evaluated to the current time plus the specified time span.
147 Correspondingly, a time span that is prefixed with "-" is evaluated
148 to the current time minus the specified time span, for example
149 '+2days'. Instead of prefixing the time span with "+" or "-", it
150 may also be suffixed with a space and the word "left" or "ago" (for
151 example '1 week ago').
152 Two parameters (e.g., 'cal 11 2020')
154 Denote the month (1 - 12) and year.
155 Three parameters (e.g., 'cal 25 11 2020')
157 Denote the day (1-31), month and year, and the day will be
158 highlighted if the calendar is displayed on a terminal. If no
159 parameters are specified, the current month’s calendar is
160 displayed.
161
163 A year starts on January 1. The first day of the week is determined by
164 the locale or the --sunday and --monday options.
165 The week numbering depends on the choice of the first day of the week.
167 If it is Sunday then the customary North American numbering is used,
168 where 1 January is in week number 1. If it is Monday (-m) then the ISO
169 8601 standard week numbering is used, where the first Thursday is in
170 week number 1.
171
173 The output colorization is implemented by terminal-colors.d(5)
174 functionality. Implicit coloring can be disabled by an empty file
175 /etc/terminal-colors.d/cal.disable
177 for the cal command or for all tools by
179 /etc/terminal-colors.d/disable
181 The user-specific $XDG_CONFIG_HOME/terminal-colors.d or
183 $HOME/.config/terminal-colors.d overrides the global setting.
184 Note that the output colorization may be enabled by default, and in
186 this case terminal-colors.d directories do not have to exist yet.
187 The logical color names supported by cal are:
189 today
191 The current day.
192 weeknumber
194 The number of the week.
195 header
197 The header of a month.
198 workday
200 Days that fall within the work-week.
201 weekend
203 Days that fall outside the work-week.
204 For example:
206 echo -e 'weekend 35\ntoday 1;41\nheader yellow' >
208 $HOME/.config/terminal-colors.d/cal.scheme
209
211 A cal command appeared in Version 6 AT&T UNIX.
212
214 The default cal output uses 3 September 1752 as the Gregorian calendar
215 reform date. The historical reform dates for the other locales,
216 including its introduction in October 1582, are not implemented.
217 Alternative calendars, such as the Umm al-Qura, the Solar Hijri, the
219 Ge’ez, or the lunisolar Hindu, are not supported.
220
222 terminal-colors.d(5)
223
225 For bug reports, use the issue tracker at
226 https://github.com/util-linux/util-linux/issues.
227
229 The cal command is part of the util-linux package which can be
230 downloaded from Linux Kernel Archive
231 <https://www.kernel.org/pub/linux/utils/util-linux/>.
232util-linux 2.39.2 2023-06-14 CAL(1)