diff options
Diffstat (limited to 'lib/libcalendar/calendar.3')
-rw-r--r-- | lib/libcalendar/calendar.3 | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/lib/libcalendar/calendar.3 b/lib/libcalendar/calendar.3 new file mode 100644 index 0000000000000..f86d5e34eb068 --- /dev/null +++ b/lib/libcalendar/calendar.3 @@ -0,0 +1,203 @@ +.\" Copyright (c) 1997 Wolfgang Helbig +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 29, 1997 +.Dt CALENDAR 3 +.Os +.Sh NAME +.Nm easterg , +.Nm easterog , +.Nm easteroj , +.Nm gdate , +.Nm jdate , +.Nm ndaysg , +.Nm ndaysj , +.Nm week , +.Nm weekday +.Nd Calendar arithmetic for the Christian era +.Sh LIBRARY +.Lb libcalendar +.Sh SYNOPSIS +.In calendar.h +.Ft struct date * +.Fn easterg "int year" "struct date *dt" +.Ft struct date * +.Fn easterog "int year" "struct date *dt" +.Ft struct date * +.Fn easteroj "int year" "struct date *dt" +.Ft struct date * +.Fn gdate "int nd" "struct date *dt" +.Ft struct date * +.Fn jdate "int nd" "struct date *dt" +.Ft int +.Fn ndaysg "struct date *dt" +.Ft int +.Fn ndaysj "struct date *dt" +.Ft int +.Fn week "int nd" "int *year" +.Ft int +.Fn weekday "int nd" +.Sh DESCRIPTION +These functions provide calendar arithmetic for a large range of years, +starting at March 1st, year zero (i.e., 1 B.C.) and ending way beyond +year 100000. +.Pp +Programs should be linked with +.Fl lcalendar . +.Pp +The functions +.Fn easterg , +.Fn easterog +and +.Fn easteroj +store the date of Easter Sunday into the structure pointed at by +.Fa dt +and return a pointer to this structure. +The function +.Fn easterg +assumes Gregorian Calendar (adopted by most western churches after 1582) and +the functions +.Fn easterog +and +.Fn easteroj +compute the date of Easter Sunday according to the orthodox rules +(Western churches before 1582, Greek and Russian Orthodox Church +until today). +The result returned by +.Fn easterog +is the date in Gregorian Calendar, whereas +.Fn easteroj +returns the date in Julian Calendar. +.Pp +The functions +.Fn gdate , +.Fn jdate , +.Fn ndaysg +and +.Fn ndaysj +provide conversions between the common "year, month, day" notation +of a date and the "number of days" representation, which is better suited +for calculations. +The days are numbered from March 1st year 1 B.C., starting +with zero, so the number of a day gives the number of days since March 1st, +year 1 B.C. +The conversions work for nonnegative day numbers only. +.Pp +The +.Fn gdate +and +.Fn jdate +functions +store the date corresponding to the day number +.Fa nd +into the structure pointed at by +.Fa dt +and return a pointer to this structure. +.Pp +The +.Fn ndaysg +and +.Fn ndaysj +functions +return the day number of the date pointed at by +.Fa dt . +.Pp +The +.Fn gdate +and +.Fn ndaysg +functions +assume Gregorian Calendar after October 4, 1582 and Julian Calendar before, +whereas +.Fn jdate +and +.Fn ndaysj +assume Julian Calendar throughout. +.Pp +The two calendars differ by the definition of the leap year. +The +Julian Calendar says every year that is a multiple of four is a +leap year. +The Gregorian Calendar excludes years that are multiples of +100 and not multiples of 400. +This means the years 1700, 1800, 1900, 2100 are not leap years +and the year 2000 is +a leap year. +The new rules were inaugurated on October 4, 1582 by deleting ten +days following this date. +Most catholic countries adopted the new +calendar by the end of the 16th century, whereas others stayed with +the Julian Calendar until the 20th century. +The United Kingdom and +their colonies switched on September 2, 1752. +They already had to +delete 11 days. +.Pp +The function +.Fn week +returns the number of the week which contains the day numbered +.Fa nd . +The argument +.Fa *year +is set with the year that contains (the greater part of) the week. +The weeks are numbered per year starting with week 1, which is the +first week in a year that includes more than three days of the year. +Weeks start on Monday. +This function is defined for Gregorian Calendar only. +.Pp +The function +.Fn weekday +returns the weekday (Mo = 0 ..\& Su = 6) of the day numbered +.Fa nd . +.Pp +The structure +.Fa date +is defined in +.In calendar.h . +It contains these fields: +.Bd -literal -offset indent +int y; /\(** year (0000 - ????) \(**/ +int m; /\(** month (1 - 12) \(**/ +int d; /\(** day of month (1 - 31) \(**/ +.Ed +.Pp +The year zero is written as "1 B.C." by historians and "0" by astronomers +and in this library. +.Sh SEE ALSO +.Xr ncal 1 , +.Xr strftime 3 +.Sh STANDARDS +The week number conforms to ISO 8601: 1988. +.Sh HISTORY +The +.Nm calendar +library first appeared in +.Fx 3.0 . +.Sh AUTHORS +This manual page and the library was written by +.An Wolfgang Helbig Aq Mt helbig@FreeBSD.org . +.Sh BUGS +The library was coded with great care so there are no bugs left. |