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