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 December 6, 2004 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 46The 47.Nm 48utility processes text files and displays lines that match certain dates. 49.Pp 50The following options are available: 51.Bl -tag -width Ds 52.It Fl a 53Process the 54.Dq calendar 55files of all users and mail the results to them. 56This requires super-user privileges. 57.It Fl d Ar MMDD[[YY]YY] 58Display lines for the given date. 59By default, the current date is used. 60The year, which may be given in either two or four digit format, is used 61only for purposes of determining wether the given date falls on a Friday 62in that year (see below). 63If the year is not specified, the current year is assumed. 64.It Fl f Ar file 65Display matching calendar files from the given filename. 66By 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 75and the first which is found is used. 76The filename may be absolute. 77If not absolute, it is taken relative to the current directory or the 78directory specified by the 79.Ev CALENDAR_DIR 80environment variable. 81Or, if the 82.Fl a 83flag is given, a non-absolute filename is taken relative to each user's 84home directory in turn. 85.It Fl l Ar days 86Causes the program to 87.Dq look ahead 88a given number of days (default one) from the specified date and 89display their entries as well. 90.It Fl w Ar days 91Causes the program to add the specified number of days to the 92.Dq look ahead 93number if and only if the day specified is a Friday. 94The default value is two, which causes 95.Nm 96to print entries through the weekend on Fridays. 97.It Fl x 98Causes 99.Nm 100not to set the 101.Ev CPP_RESTRICTED 102environment variable. 103Passing this flag allows users the (somewhat obscure) option of 104including a named pipe via 105.Xr cpp 1 Ns No 's 106.Li #include 107syntax, but opens up the possibility of 108.Nm 109hanging indefinitely if users do so incorrectly. 110For this reason, the 111.Fl x 112flag should never be used with 113.Nm 114.Fl a . 115.El 116.Pp 117Lines should begin with a month and day. 118They may be entered in almost any format, either numeric or as character 119strings. 120A single asterisk 121.Pq Sq * 122matches every month, or every day if a month has been provided. 123This means that two asterisks 124.Pq Sq ** 125matches every day of the year, and is thus useful for ToDo tasks. 126A day without a month matches that day of every week. 127A month without a day matches the first of that month. 128Two numbers default to the month followed by the day. 129Lines with leading tabs default to the last entered date, allowing 130multiple line specifications for a single date. 131By convention, dates followed by an asterisk are not fixed, i.e., change 132from year to year. 133.Pp 134The 135.Dq calendar 136file is preprocessed by 137.Xr cpp 1 , 138allowing the inclusion of shared files such as company holidays or 139meetings. 140If the shared file is not referenced by a full pathname, 141.Xr cpp 1 142searches in the current (or home) directory first, and then in the 143directory 144.Pa /usr/share/calendar . 145Empty lines and lines protected by the C commenting syntax 146.Pq Li /* ... */ 147are ignored. 148.Pp 149Some possible calendar entries: 150.Bd -literal -offset indent 151#include \*[Lt]calendar.usholiday\*[Gt] 152#include \*[Lt]calendar.birthday\*[Gt] 153 1546/15 ... June 15 (if ambiguous, will default to month/day). 155Jun. 15 ... June 15. 15615 June ... June 15. 157Thursday ... Every Thursday. 158June ... Every June 1st. 15915 * ... 15th of every month. 160*15 ... 15th of every month. 161June* ... Every day of June. 162** ... Every day 163.Ed 164.Sh FILES 165The following default calendar files are provided: 166.Pp 167.Bl -tag -width calendar.christian -compact 168.It Pa calendar.birthday 169Births and deaths of famous (and not-so-famous) people. 170.It Pa calendar.christian 171Christian holidays. 172This calendar should be updated yearly by the local system administrator 173so that roving holidays are set correctly for the current year. 174.It Pa calendar.computer 175Days of special significance to computer people. 176.It Pa calendar.history 177Everything else, mostly U.S. historical events. 178.It Pa calendar.holiday 179Other holidays, including the not-well-known, obscure, and 180.Em really 181obscure. 182.It Pa calendar.judaic 183Jewish holidays. 184This calendar should be updated yearly by the local system administrator 185so that roving holidays are set correctly for the current year. 186.It Pa calendar.lotr 187Important dates in the Lord of the Rings series. 188.It Pa calendar.music 189Musical events, births, and deaths. 190Strongly oriented toward rock 'n' roll. 191.It Pa calendar.netbsd 192Important dates in the history of the 193.Nx 194project. 195Mostly releases and port additions. 196.It Pa calendar.usholiday 197U.S. holidays. 198This calendar should be updated yearly by the local system administrator 199so that roving holidays are set correctly for the current year. 200.El 201.Sh SEE ALSO 202.Xr at 1 , 203.Xr cpp 1 , 204.Xr cron 8 205.Sh COMPATIBILITY 206The 207.Nm 208program previously selected lines which had the correct date anywhere 209in the line. 210This is no longer true, the date is only recognized when it occurs 211first on the line. 212.Pp 213In 214.Nx 3.0 , 215the 216.Nm 217command was modified to search the user's home directory instead of the current 218directory by default. 219Users desiring the historical behavior should set the 220.Ev CALENDAR_DIR 221environment variable to 222.Pa \&. , 223or use the 224.Fl f 225flag. 226.Sh HISTORY 227A 228.Nm 229command appeared in 230.At v7 . 231.Sh BUGS 232.Nm 233doesn't handle events that move around from year to year, i.e., 234.Dq the last Monday in April . 235.Pp 236The 237.Fl a 238option ignores the user's 239.Ev CALENDAR_DIR 240environment variable. 241