usr.bin/calendar/calendar.1

   1 .\"     $NetBSD: calendar.1,v 1.22 2008/03/07 19:22:22 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)calendar.1  8.1 (Berkeley) 6/29/93
  31 .\"
  32 .Dd August 27, 2009
  33 .Dt CALENDAR 1
  34 .Os
  35 .Sh NAME
  36 .Nm calendar
  37 .Nd reminder service
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl ax
  41 .Op Fl d Ar MMDD[[YY]YY]
  42 .Op Fl f Ar file
  43 .Op Fl l Ar days
  44 .Op Fl w Ar days
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility processes text files and displays lines that match certain dates.
  49 .Pp
  50 The following options are available:
  51 .Bl -tag -width Ds
  52 .It Fl a
  53 Process the
  54 .Dq calendar
  55 files of all users and mail the results to them.
  56 This requires super-user privileges.
  57 .It Fl d Ar MMDD[[YY]YY]
  58 Display lines for the given date.
  59 By default, the current date is used.
  60 The year, which may be given in either two or four digit format, is used
  61 only for purposes of determining wether the given date falls on a Friday
  62 in that year (see below).
  63 If the year is not specified, the current year is assumed.
  64 .It Fl f Ar file
  65 Display matching calendar files from the given filename.
  66 By default, the following filenames are checked for:
  67 .Bl -item -compact -offset indent
  68 .It
  69 .Pa ~/calendar
  70 .It
  71 .Pa ~/.calendar
  72 .It
  73 .Pa /etc/calendar
  74 .El
  75 and the first which is found is used.
  76 The filename may be absolute.
  77 If not absolute, it is taken relative to the
  78 directory specified by the
  79 .Ev CALENDAR_DIR
  80 environment variable, if set; otherwise, it is taken relative to the
  81 user's home directory.
  82 Or, if the
  83 .Fl a
  84 flag is given, a non-absolute filename is taken relative to each user's
  85 home directory in turn.
  86 .It Fl l Ar days
  87 Causes the program to
  88 .Dq look ahead
  89 a given number of days (default one) from the specified date and
  90 display their entries as well.
  91 .It Fl w Ar days
  92 Causes the program to add the specified number of days to the
  93 .Dq look ahead
  94 number if and only if the day specified is a Friday.
  95 The default value is two, which causes
  96 .Nm
  97 to print entries through the weekend on Fridays.
  98 .It Fl x
  99 Causes
 100 .Nm
 101 not to set the
 102 .Ev CPP_RESTRICTED
 103 environment variable.
 104 Passing this flag allows users the (somewhat obscure) option of
 105 including a named pipe via
 106 .Xr cpp 1 Ns No 's
 107 .Li #include
 108 syntax, but opens up the possibility of
 109 .Nm
 110 hanging indefinitely if users do so incorrectly.
 111 For this reason, the
 112 .Fl x
 113 flag should never be used with
 114 .Nm
 115 .Fl a .
 116 .El
 117 .Pp
 118 Lines should begin with a month and day.
 119 They may be entered in almost any format, either numeric or as character
 120 strings.
 121 A single asterisk
 122 .Pq Sq *
 123 matches every month, or every day if a month has been provided.
 124 This means that two asterisks
 125 .Pq Sq **
 126 matches every day of the year, and is thus useful for ToDo tasks.
 127 A day without a month matches that day of every week.
 128 A month without a day matches the first of that month.
 129 Two numbers default to the month followed by the day.
 130 Lines with leading tabs default to the last entered date, allowing
 131 multiple line specifications for a single date.
 132 By convention, dates followed by an asterisk are not fixed, i.e., change
 133 from year to year.
 134 .Pp
 135 The
 136 .Dq calendar
 137 file is preprocessed by
 138 .Xr cpp 1 ,
 139 allowing the inclusion of shared files such as company holidays or
 140 meetings.
 141 If the shared file is not referenced by a full pathname,
 142 .Xr cpp 1
 143 searches in the current (or home) directory first, and then in the
 144 directory
 145 .Pa /usr/share/calendar .
 146 Empty lines and lines protected by the C commenting syntax
 147 .Pq Li /* ... */
 148 are ignored.
 149 .Pp
 150 Some possible calendar entries:
 151 .Bd -literal -offset indent
 152 #include        \*[Lt]calendar.usholiday\*[Gt]
 153 #include        \*[Lt]calendar.birthday\*[Gt]
 154
 155 6/15            ... June 15 (if ambiguous, will default to month/day).
 156 Jun. 15         ... June 15.
 157 15 June         ... June 15.
 158 Thursday        ... Every Thursday.
 159 June            ... Every June 1st.
 160 15 *            ... 15th of every month.
 161 *15             ... 15th of every month.
 162 June*           ... Every day of June.
 163 **              ... Every day
 164 .Ed
 165 .Sh FILES
 166 The following default calendar files are provided:
 167 .Pp
 168 .Bl -tag -width calendar.christian -compact
 169 .It Pa calendar.birthday
 170 Births and deaths of famous (and not-so-famous) people.
 171 .It Pa calendar.christian
 172 Christian holidays.
 173 This calendar should be updated yearly by the local system administrator
 174 so that roving holidays are set correctly for the current year.
 175 .It Pa calendar.computer
 176 Days of special significance to computer people.
 177 .It Pa calendar.history
 178 Everything else, mostly U.S. historical events.
 179 .It Pa calendar.holiday
 180 Other holidays, including the not-well-known, obscure, and
 181 .Em really
 182 obscure.
 183 .It Pa calendar.judaic
 184 Jewish holidays.
 185 This calendar should be updated yearly by the local system administrator
 186 so that roving holidays are set correctly for the current year.
 187 .It Pa calendar.lotr
 188 Important dates in the Lord of the Rings series.
 189 .It Pa calendar.music
 190 Musical events, births, and deaths.
 191 Strongly oriented toward rock 'n' roll.
 192 .It Pa calendar.netbsd
 193 Important dates in the history of the
 194 .Nx
 195 project.
 196 Mostly releases and port additions.
 197 .It Pa calendar.usholiday
 198 U.S. holidays.
 199 This calendar should be updated yearly by the local system administrator
 200 so that roving holidays are set correctly for the current year.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr at 1 ,
 204 .Xr cpp 1 ,
 205 .Xr cron 8
 206 .Sh COMPATIBILITY
 207 The
 208 .Nm
 209 program previously selected lines which had the correct date anywhere
 210 in the line.
 211 This is no longer true, the date is only recognized when it occurs
 212 first on the line.
 213 .Pp
 214 In
 215 .Nx 3.0 ,
 216 the
 217 .Nm
 218 command was modified to search the user's home directory instead of the current
 219 directory by default.
 220 Users desiring the historical behavior should set the
 221 .Ev CALENDAR_DIR
 222 environment variable to
 223 .Pa \&. ,
 224 or use the
 225 .Fl f
 226 flag.
 227 .Sh HISTORY
 228 A
 229 .Nm
 230 command appeared in
 231 .At v7 .
 232 .Sh BUGS
 233 .Nm
 234 doesn't handle events that move around from year to year, i.e.,
 235 .Dq the last Monday in April .
 236 .Pp
 237 The
 238 .Fl a
 239 option ignores the user's
 240 .Ev CALENDAR_DIR
 241 environment variable.