Merge from vendor branch GCC:
[dragonfly.git] / lib / libcalendar / calendar.3
1 .\" Copyright (c) 1997 Wolfgang Helbig
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD: src/lib/libcalendar/calendar.3,v 1.6.2.5 2001/12/17 10:08:28 ru Exp $
26 .\" $DragonFly: src/lib/libcalendar/calendar.3,v 1.2 2003/06/17 04:26:48 dillon Exp $
27 .\"
28 .Dd November 29, 1997
29 .Dt CALENDAR 3
30 .Os
31 .Sh NAME
32 .Nm easterg ,
33 .Nm easterog ,
34 .Nm easteroj ,
35 .Nm gdate ,
36 .Nm jdate ,
37 .Nm ndaysg ,
38 .Nm ndaysj ,
39 .Nm week ,
40 .Nm weekday
41 .Nd Calendar arithmetic for the Christian era
42 .Sh LIBRARY
43 .Lb libcalendar
44 .Sh SYNOPSIS
45 .In calendar.h
46 .Ft struct date *
47 .Fn easterg "int year" "struct date *dt"
48 .Ft struct date *
49 .Fn easterog "int year" "struct date *dt"
50 .Ft struct date *
51 .Fn easteroj "int year" "struct date *dt"
52 .Ft struct date *
53 .Fn gdate "int nd" "struct date *dt"
54 .Ft struct date *
55 .Fn jdate "int nd" "struct date *dt"
56 .Ft int
57 .Fn ndaysg "struct date *dt"
58 .Ft int
59 .Fn ndaysj "struct date *dt"
60 .Ft int
61 .Fn week "int nd" "int *year"
62 .Ft int
63 .Fn weekday "int nd"
64 .Sh DESCRIPTION
65 These functions provide calendar arithmetic for a large range of years,
66 starting at March 1st, year zero (i. e. 1 B.C.) and ending way beyond
67 year 100000.
68 .Pp
69 Programs should be linked with
70 .Fl lcalendar .
71 .Pp
72 The functions
73 .Fn easterg ,
74 .Fn easterog
75 and
76 .Fn easteroj
77 store the date of Easter Sunday into the structure pointed at by
78 .Fa dt
79 and return a pointer to this structure.
80 The function
81 .Fn easterg
82 assumes Gregorian Calendar (adopted by most western churches after 1582) and
83 the functions
84 .Fn easterog
85 and
86 .Fn easteroj
87 compute the date of Easter Sunday according to the orthodox rules
88 (Western churches before 1582, Greek and Russian Orthodox Church
89 until today).
90 The result returned by
91 .Fn easterog
92 is the date in Gregorian Calendar, whereas
93 .Fn easteroj
94 returns the date in Julian Calendar.
95 .Pp
96 The functions
97 .Fn gdate ,
98 .Fn jdate ,
99 .Fn ndaysg
100 and
101 .Fn ndaysj
102 provide conversions between the common "year, month, day" notation
103 of a date and the "number of days" representation, which is better suited
104 for calculations.
105 The days are numbered from March 1st year 1 B.C., starting
106 with zero, so the number of a day gives the number of days since March 1st,
107 year 1 B.C. The conversions work for nonnegative day numbers only.
108 .Pp
109 The
110 .Fn gdate
111 and
112 .Fn jdate
113 functions
114 store the date corresponding to the day number
115 .Fa nd
116 into the structure pointed at by
117 .Fa dt
118 and return a pointer to this structure.
119 .Pp
120 The
121 .Fn ndaysg
122 and
123 .Fn ndaysj
124 functions
125 return the day number of the date pointed at by
126 .Fa dt .
127 .Pp
128 The
129 .Fn gdate
130 and
131 .Fn ndaysg
132 functions
133 assume Gregorian Calendar after October 4, 1582 and Julian Calendar before,
134 whereas
135 .Fn jdate
136 and
137 .Fn ndaysj
138 assume Julian Calendar throughout.
139 .Pp
140 The two calendars differ by the definition of the leap year.
141 The
142 Julian Calendar says every year that is a multiple of four is a
143 leap year.
144 The Gregorian Calendar excludes years that are multiples of
145 100 and not multiples of 400.
146 This means the years 1700, 1800, 1900, 2100 are not leap years
147 and the year 2000 is
148 a leap year.
149 The new rules were inaugurated on October 4, 1582 by deleting ten
150 days following this date.
151 Most catholic countries adopted the new
152 calendar by the end of the 16th century, whereas others stayed with
153 the Julian Calendar until the 20th century.
154 The United Kingdom and
155 their colonies switched on September 2, 1752. They already had to
156 delete 11 days.
157 .Pp
158 The function
159 .Fn week
160 returns the number of the week which contains the day numbered
161 .Fa nd .
162 The argument
163 .Fa *year
164 is set with the year that contains (the greater part of) the week.
165 The weeks are numbered per year starting with week 1, which is the
166 first week in a year that includes more than three days of the year.
167 Weeks start on Monday.
168 This function is defined for Gregorian Calendar only.
169 .Pp
170 The function
171 .Fn weekday
172 returns the weekday (Mo = 0 .. Su = 6) of the day numbered
173 .Fa nd .
174 .Pp
175 The structure
176 .Fa date
177 is defined in
178 .Aq Pa calendar.h .
179 It contains these fields:
180 .Bd -literal -offset indent
181 int y;          /\(** year (0000 - ????) \(**/
182 int m;          /\(** month (1 - 12) \(**/
183 int d;          /\(** day of month (1 - 31) \(**/
184 .Ed
185 .Pp
186 The year zero is written as "1 B.C." by historians and "0" by astronomers
187 and in this library.
188 .Sh SEE ALSO
189 .Xr ncal 1 ,
190 .Xr strftime 3
191 .Sh STANDARDS
192 The week number conforms to ISO 8601: 1988.
193 .Sh HISTORY
194 The
195 .Nm calendar
196 library first appeared in
197 .Fx 3.0 .
198 .Sh AUTHORS
199 This manual page and the library was written by
200 .An Wolfgang Helbig Aq helbig@FreeBSD.org .
201 .Sh BUGS
202 The library was coded with great care so there are no bugs left.