| blob | 6dc1a438b571264bc6b1fccd1c955fcc27f783b3 |
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
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 whether 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]
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 COMPATIBILITY
203 The
204 .Nm
205 program previously selected lines which had the correct date anywhere
206 in the line.
207 This is no longer true, the date is only recognized when it occurs
208 first on the line.
209 .Pp
210 In
211 .Nx 3.0 ,
212 the
213 .Nm
214 command was modified to search the user's home directory instead of the current
215 directory by default.
216 Users desiring the historical behavior should set the
217 .Ev CALENDAR_DIR
218 environment variable to
219 .Pa \&. ,
220 or use the
221 .Fl f
222 flag.
223 .Sh SEE ALSO
224 .Xr at 1 ,
225 .Xr cpp 1 ,
226 .Xr cron 8
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.