FreeBSD Manual Pages
CAL(1) General Commands Manual CAL(1) NAME cal - displays a calendar SYNOPSIS cal [ options ] [ [ num_month ] year ] cal [ options ] [ word_month ] [ year ] DESCRIPTION By default, cal will display a calendar for the current month with the current day marked. By specifing certain arguments, cal will display a calendar for a whole year or a specified month and year. The transition from the Julian to Gregorian calendar is assumed to have occured in 1752 on the 3rd of September. Ten days following that date were eliminated by the reformation, so the calendar for that month is a bit unusual. If displaying a calendar in the single-month format, cal will look for a date file. If found, cal will read the file, looking for special date descriptions for that month which will be displayed to the right of the calendar. By default, up to 24 appointments may be displayed per month. If the current date happens to fall on one of these special dates, it will be flagged by an asterisk. If there is room, appoint- ments for the next month may also be displayed with some limitations (currently, special dates such as the 3rd Thursday of will not be cal- culated for next month). cal can also optionally use colors when displaying the calendar. It will not display colors any time the calendar is not directly display- ing on the console. This is generally the desired behavior when your redirecting cal's output to another program or a file. ARGUMENTS A verbally-specified month may be entered without specifying a year in the argument list; however, a single numerical argument will be inter- preted as a year. Only the first 3 characters of the month name are significant for a verbally-specified month. The command `cal 10' refers to 10 AD, not October, and not 1910. The available options are: --3[months] Display previous/current/next month together. This option will be ignored when displaying a full year. --a[ppts] Maximum number of appointments to display. Minimum is 8, maxi- mum is 50, default is 24. --col[or-file]=filename Read color definitions from `filename' (default color filename depends on operating system). --con[tinue]=n Display the next n successive months starting with the month specified. --d[ata-file]=filename Read appointments from `filename' (default appointment data filename depends on operating system). You may use -d up to 8 times in a commandline to specify multiple data file names. --e[urope] Use European format (first weekday is Monday). --f[uture] If current month is displayed, then show only future appoint- ments from the date file, not appointments that are past. This allows room for other descriptions with future dates to be dis- played. As time progresses through the month, old descriptions are discarded and newer ones are used. The --future switch af- fects only the display for the current month, and not other months. --j[ulian] Display Julian dates (days one-based, numbered from January 1). --m[onday] Display Monday as the first day of the week (same as --europe) --noc[olor] Inhibit the use of colors. --nod[ata] Do not try to read any appointment data file. --p[ause] Pause before exiting and prompt for a keystroke. --th[ismonth] Disable display of next month appointments; show only current month's. --to[day] Show only today's appointments. --u[se-color] Allow the use of colors. --y[ear] Display a calendar for the current year. There is an optional environment variable that can be used by cal if found. If CALOPT is set then cal will read it and use any valid com- mand line options found. This allows any commonly used switches to be set in your environment and always used (e.g. --europe). Cal will pro- duce its usage screen when run if any invalid options are set in this variable. COMMAND EXAMPLES cal --f --d=my_dates display the current month and future appointments defined in file `my_dates' cal 1996 display the entire year of 1996 cal 9 1752 display the month of September 1752 cal sep 1752 same as above cal January display January of the current year cal help help message displayed for unrecognized arguments DATE FILES cal will search for a date file called cal.dat in the directory it was executed from. If not found it will search in the users $HOME direc- tory for a file called .cal.dat. If still not found, it will look for a global cal.dat in a system wide directory. To find out where this location is you can run cal --help which will display the location. The special date descriptions specified in the date file are single lines, formatted as follows: YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx where YYYY is the year, MM is the month (01 - 12), DD is the day (00 if the NW field is used), NW is the weekday-of-month code (00 if the DD field is used) xxxx is the description; it will be truncated as necessary to fit The data MUST occupy the character fields as shown. If YYYY is speci- fied as -999, the month and day are assumed to be annual events such as holidays, and the description will be displayed for any year. If MM is specified as -9, the day is assumed to be a monthly event for the spec- ified year. In the weekday-of-month code NW, N signifies on which weekday W the special date occurs. For example, 31 indicates the third sunday. Values of W range from 1 to 7, for Sunday to Saturday, respec- tively. A value of 9 for N indicates "last" as in 95 for "last thurs- day." If ALL of the fields contain a positive number and the year is at least 1970, then the description is assumed to be periodic, starting at the given date, with the period in days specified in NW (e.g. 1995 01 06 14 will display the description every 2nd Friday using 6 January 1995 as the base date). The base date does not get displayed. You can display birthdays and anniversaries by putting the year of birth (or other special event) inside brackets or braces, in the de- scription. This number is converted to the number of years since the year you indicate and the brackets or braces are removed from the out- put. If braces {} are used the number will have an ordinal suffix, as in 21st, 32nd, 43rd, 54th, etc. If the number in brackets or braces is greater than the current year, the number will be displayed unchanged. Example: "Alex's {1961} birthday" will display as "Alex's 34th birth- day" (if the current year is 1995). If you need to include brackets or braces in your output then you can escape them by prefixing it with a '\'. Example: "Alex's \{1961\} birthday" will be displayed as "Alex's {1961} birthday". NOTE: If cal is invoked with the --europe or --monday switch, then the W values 1-7 denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7). A line in cal.dat must start with -999 or a 4-digit number to be con- sidered as data. The data lines may be in any order. All these ap- pointments will be displayed in chronological order, regardless of the ordering in the appointment data file. If cal was compiled with the reminder support then call will also search for the files dates and .dates in the same places as for the cal.dat equivalents. The dates file is used by the reminder(1) program and is an alternate, less-powerful format for specifying descriptions. A file in this format cannot be specified with the --data-file= option. The reminder format consists of text lines of length < screen width in the following format: DDDDDDDD:N:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:yyyyyy:S where DDDDDDDD is the date in one of the following formats: M/D/Y an event occurring on a specific day (year can be two or four digits, but must be two for backward compatibility with re- minder) M/D an event occurring every year D an event occurring every month DDD an event occurring every week (day of the week is 'Sun', 'Mon', etc.) N is the number of days notice of the event to give the user (ig- nored by cal) xxxxx the event description yyyyy an optional receptor of the event (e.g. Mr. Jones) S status flag, either N for normal event or D for a deleted (not displayed) event Blank lines are ignored. A line otherwise not in the above format is assume to specify a file name from which to read more events. The file is searched for in the usual places. COLOR ATTRIBUTES cal will search for a color definition file called cal.col in the di- rectory it was executed from. If not found it will search in the users $HOME directory for a file called .cal.col. If still not found, it will look for a global cal.col in a system wide directory. To find out where this location is you can run cal --help which will display the location. Users may override the default colors used when displaying calendars. This may be done by creating a color definition file. Example of a color definition file: 15 02 video colors for month name 01 03 video colors for weekday header 07 01 video colors for normal calendar days 13 01 video colors for sundays 14 02 video colors for current day 07 06 bkgd for yearly calendar (space between months) 11 00 video colors for special day descriptions 12 08 video colors for * indicating descr.=today FG BG Color definitions must appear as above, as a two-character field for the foreground color, followed by a space, followed by a two-character field for the background color. The color definitions must start on the first line, and must not contain blank lines. Comments may appear after the second field, provided that the total line length does not exceed 80 characters. Possible colors: black 0 blue 1 green 2 cyan 3 red 4 violet 5 orange 6 light gray 7 dark gray 8 bright blue 9 bright green 10 bright cyan 11 bright red 12 bright violet 13 yellow 14 white 15 Specifying a background color from 8 to 15 will result in a background color of 0 to 7, with flashing text. FILES cal.dat Date file cal.col Color definition file $HOME/.cal.dat UNIX local date file $HOME/.cal.col UNIX local color file ~/.dates Date file used with UNIX reminder program and can be used with cal. AUTHOR Alex Matulich - alex@unicorn.us.com ...with enhancements and modifications by other contributors. (c) 1993-2001 by Unicorn Research Corporation http://uni- corn.us.com. Inspired by an Amiga program by Gary L. Brant. SEE ALSO date(1), reminder(1), rs(1) 01 January 2002 CAL(1)
NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | COMMAND EXAMPLES | DATE FILES | COLOR ATTRIBUTES | FILES | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cal&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>