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