Man Linux: Main Page and Category List


       ccal - display a colored calendar


       ccal [ options ] [ [ num_month ] year ]
       ccal [ options ] [ [ word_month ] year ]


       ccal  is an enhanced version of the Unix cal command.  It is compatible
       to the Unix version in that it uses the same input  arguments  and  its
       output may be piped or redirected anywhere.

       ccal  displays  a  calendar for a specified year, a specified month and
       year, or for the current date.  By default, it displays a calendar  for
       the  current  system-date  month,  with  the current day hilighted.  It
       correctly handles the transition from the Julian to Gregorian calendars
       in September 1752.


       A  verbally-specified month may be entered without specifying a year in
       the argument  list;  however,  a  single  numerical  argument  will  be
       interpreted  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  options  are  explained  more  fully  in the ENHANCEMENTS sections
       below.  The available options are:

              Do not try to read any appointment data file.

              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.

              If  current  month  is  displayed,   then   show   only   future
              appointments  from  the  appointment file, not appointments that
              are past. NOTE:  This switch was -d in previous versions.

              If current month is displayed, then show only  appointments  for
              today from the appointment file.

              Use European format (first weekday is Monday).

              Use North American format (first weekday is Sunday), this is the

              Maximum number  of  appointments  to  display.   Minimum  is  8,
              maximum is 50, default is 24.

              Pause before exiting and prompt for a keystroke.

              Allows  the  use 8 bit extended ASCII (code page 437) characters
              in Unix version.  It is always allowed in DOS and OS/2 versions

              Inhibit the use of colors.

              Read color definitions from ‘filename’ (default  color  filename
              depends on operating system).


       ccal -f -d=my_dates
              display  the  current  month  and future appointments defined in
              file ‘my_dates’

       ccal 1996
              display the entire year of 1996

       ccal 9 1752
              display the month of September 1752

       ccal sep 1752
              same as above

       ccal January
              display January of the current year

       ccal help
              help message displayed for unrecognized arguments

       If displaying the single-month format, ccal will look for a  date  file
       (the  default  file  or  whatever  you specify with the -d option).  If
       found, ccal 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 (number may be changed with  -m)  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,  appointments  for  the  next  month  may also be displayed (next
       month’s dates having definitions like "2nd Thursday" will be  skipped).

       The  special  date  descriptions  specified in the date file are single
       lines, formatted as follows:

        YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


       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
       specified  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 specified 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,
       respectively.   A  value of 9 for N indicates "last" as in 95 for "last

       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
       description.  This number is converted to the number of years since the
       year  you  indicate  and  the  brackets  or braces are removed from the
       output.  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 birthday" (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  ccal  is invoked with the -europe switch, then the W values
       1-7 denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7).
       If  invoked  with  the  -american  switch, then the W values 1-7 denote
       Sunday(1) to Monday(7). If none of those switches are used it will  use
       the locale definitions (LC_TIME), if available.

       A  line  in  cal.dat  must  start  with  -999 or a 4-digit number to be
       considered as data.  The data lines may be in  any  order.   All  these
       appointments  will  be  displayed in chronological order, regardless of
       the ordering in the appointment data file.

       If compiled with the USE_REMINDER (this is the default in Debian) flag,
       ccal will also search for the files dates and .dates in the same places
       as for  the  caldat  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:



              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

        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’,

       N      is  the  number  of  days  notice  of the event to give the user
              (ignored by ccal)

       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.

       The  -f  commandline  switch  causes  any  date  description older than
       today’s date to be ignored, thereby giving room for other  descriptions
       with  future  dates  to  be  displayed.  As time progresses through the
       month, old descriptions are discarded and newer ones are used.  The  -f
       switch  affects  only  the display for the current month, and not other

       There is an optional environment variable that can be used by  ccal  if
       found.   If  CALOPT  is  set  then  ccal will read it and use any valid
       command line options found.  This allows any commonly used switches  to
       be  set  in  your environment and always used (e.g. -europe).  Cal will
       produce its usage screen when run if any invalid  options  are  set  in
       this variable.


       Under  MS-DOS  or  OS/2,  commandline  arguments  may  begin with a ’/’
       instead of a ’-’ character.  It works either way.

       The default name for the date file under  MS-DOS  and  OS/2  is  called
       cal.dat.   It  will  first  look for this file (or whatever you specify
       with the -d option) in the current directory and if that fails it  will
       look in the directory that the cal program is located in.

       ccal  modifies  the  display  attributes  behind its output in order to
       display the calendar in attractive colors.  Display manipulation is not
       done if ccal’s output is redirected to a file.  When ccal starts up, it
       looks for a file called cal.col (or whatever you specify  with  the  -c
       option), first in ccal’s originating directory, and then in the current
       directory.  The colors have their own  defaults  if  the  file  is  not


       Under  Unix  the default filenames and places that are searched for are
       different.  For the calendar date file,  ccal  searches  for  the  file
       .caldat in the users home directory.  If it is not found ccal will then
       look for the file caldat in the current directory and then look for  it
       in /usr/lib.

       For  the  default  color  file,  it  will look first in the user’s home
       directory for the file .calcol.   It  then  looks  for  calcol  in  the
       current directory and then in /etc/.


       Under  Debian,  ccal  will  also  use  the user’s locale definitions to
       determine which day to use as start week day. Currently, only Monday or
       Sunday are used.

       If  you  do  not  set  the  -europe or -american switch, your locale is
       defined properly, and you see a different start week day different from
       what  you  would  expect,  either  ccal or your libc definitions are to
       blame. If you think this is a bug, please report  it.   Remember,  ccal
       will not accept a default week day which is not Monday or Sunday.


       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.


       cal.dat             DOS and OS/2 date file
       cal.col             DOS and OS/2 color file
       ~/.caldat           Unix local date file
       ~/.calcol           Unix local color file
       /usr/lib/caldat     Unix global date files
       /etc/calcol         Unix global color files
       ~/.dates            date  file  used with Unix reminder program and can
                           be used with cal.


            Alex Matulich  -

            ...with enhancements and modifications by other

            (c) 1995 by Unicorn Research Corporation.  All rights
            reserved.  Inspired by an Amiga program by
            Gary L. Brant.


       date(1), reminder(1), rs(1), locale(1)

                                28 January 2004