libhdate, hcal and hdate Wiki
C library for Hebrew dates / times of day / solar times
Brought to you by:
boruch-baum,
kzamir
Menu
▾
▴
hdate man page (v1.8)
hdate man page (v1.8)
Although hdate v1.8 is still under development, here is a snapshot of the man page reflecting the features already coded and committed to the svn repository.
~~~~
hdate(1) libhdate documentation hdate(1)
NAME
hdate - displays Hebrew date information for a given Gregorian/Julian
date
SYNOPSIS
hdate [options] [coordinates] [timezone] [datespec]
hdate [options] [coordinates] [timezone] [julian_day|time_t]
coordinates -l [N|S]yy[.yyy] -L [E|W]xx[.xxx]
-l [N|S]yy[:mm[:ss]] -L [E|W]xx[:mm[:ss]]
timezone: -z nn[(.nn|:mm)]
-z [timezone_name] (see below)
datespec: see section ACCEPTABLE DATE FORMATS
DESCRIPTION
hdate provides the date according to the Hebrew calendar, that day's
corresponding date according to the gregorian calendar, and optionally
providess further information about that Hebrew date, including holi‐
days and astronomical-related times (see section LOCATIONS). If no
arguments are given, hdate provides information for the current date.
If a single numeric argument is given, hdate interprets it as a year,
and provides the requested information for all days of that year. If
two arguments are given, hdate interprets them as a month and a year,
and provides the requested information for all days of that month.
INPUTTING A HEBREW DATE: hdate interprets year values greater than 3000
as Hebrew dates. Numeric Hebrew months are interpreted as 1-12 for
Tishrei - Elul; 13 and 14 for Adar I and Adar II. Currently, the maxi‐
mum value hdate accepts for a Hebrew year is 6999.
INPUTTING A GREGORIAN DATE: hdate interprets year values in the range
1000 - 2999 as either gregorian, or (see section BUGS, subsection His‐
torical) julian. Numeric months are interpreted as 1-12 for January -
December.
INPUTTING A JULIAN DAY: If a single numeric argument is provided, and
that argument is in the range 1443377 <= n <= 2904342, hdate interprets
it as a "julian day number" and provides information for that Julian
day's corresponding Hebrew date. See section JULIAN DAY.
INPUTTING AN EPOCH DATE: hdate interprets a number preceded by a '@' as
a time_t value, representing the number of seconds elapsed since the
Epoch, 1970-01-01 00:00:00 +0000 (UTC). A second way to provide an
epoch date value is as a parameter to the -E (--epoch) option, without
the leading '@'.
ACCEPTABLE DATE FORMATS: Prior versions of hdate insisted on the
numeric date format [[yyyy [mm [dd]]]. hdate now accepts numeric date
elements in any easily discernable order. hdate now accepts Hebrew
month names and gregorian month names in both full and abbreviated for‐
mats, and not case-sensitive. Gregorian month names may be entered in
either your locale's language or in English. Hebrew month names may be
entered in either Hebrew characters or in many transliteration forms to
latin characters (see EXAMPLES). hdate will intelligently interpret
ambiguous numeric datespec parameters. For example, a parameter "32"
could only legitimately be a two-digit year, so hdate will, by default,
interpret it as a two-digit Hebrew year in the current (58th) century
(see option --prefer-gregorian, section CONFIG FILES, and the config
file options to change the default base years).
OPTIONS
-b --bidi output Hebrew information in Hebrew, but in reverse
--visual sequence.
-d --diaspora force diaspora readings and holidays.
--israel force Eretz Yisroel readings an holidays.
--daf-yomi
-e --emesh begin printing times-of-day at sunset or candle
--erev lighting. This is the default.
--no-emesh
--no-erev
-E --epoch print times of day in epoch format, ie. the number of
seconds elapsed since the Epoch, 1970-01-01 00:00:00
+0000 (UTC). This option will also cause --sun-hour
to display in seconds instead of hh:mm:ss.
-E --epoch time_t get information for this epoch date, instead of for
datespec.
-h --holidays print holiday name if day is a holiday, and print
custom day name if day is marked as a custom day. See
section HOLIDAYS AND CUSTOM DAYS.
-H print only if day is a holiday or a custom day, and
print the name of that holiday or custom day.
-i --ical use iCal formatted output.
-j --julian print Julian day number.
-m --menu prompt user-defined menu from config file. See there
for details and examples.
-o --omer print Sefirat Ha Omer, number of days only.
-oo 'today is n days in the omer'
-ooo the full text, with weeks and remainder days
--ba-omer full omer text, as -ooo, in Hebrew
--la-omer full omer text, as -ooo, in Hebrew
-q --quiet suppress output, available in four levels:
--quiet-alerts -q suppresses warning messages
--quiet-gregorian -qq also suppresses the gregorian date
--quiet-descriptions -qqq also suppresses data labels
--quiet-hebrew -qqqq also suppresses the Hebrew date
-r --parasha print weekly reading if day is Shabbat.
-R print only if day is a Shabbat on which the regular
weekly reading is read (ie. not a special holiday
reading), and print that weekly reading.
--sun print sunrise and sunset times.
--sunrise
--sunset
-s --shabbat-times
--shabbat print Shabbat start and end times.
--candles-lighting [nn]
--candle [nn] (17<nn<91) default is 20 minutes before sunset.
--havdalah [nn] (19<nn<91 minutes) default is 3 stars.
-S --short-format print using short format.
-t --times print day times (three verbosity levels):
--times-of-day -t first light, talit, sunrise, mid day, sunset,
--day-times first stars, three stars,
and the length of that day's sun-hour.
-tt adds end_Shema_(GR"A), end_amidah,
mincha_gedola, mincha_ketana, plag_hamincha.
-ttt adds end_Shema_(M"A).
-tttt adds erev Pesach times
Instead of using the presets, customize with:
--first-light --midday --shekia
--alot --noon --tzeit-hakochavim
--talit --chatzot --first-stars
--netz --mincha-gedola --three-stars
--shema --mincha-ketana --magen-avraham
--amidah --plag-hamincha --sun-hour
--sunrise --sunset
--erev-pesach if the day is 14 Nissan, print the following times:
--end-eating-chometz-ma --end-eating-chometz-gra
--end-owning-chometz-ma --end-owning-chometz-gra
-T --table print tabular output. All data for each requested day
--tabular will be output on a single comma-delimited line. Most
suitable for piping, or export to spreadsheets
-l --latitude [NS]yy[.yyy] decimal degrees, or [NS]yy[:mm[:ss]]
degrees, minutes, seconds. Negative values are South
-L --longitude [EW]xx[.xxx] decimal degrees, or [EW]xx[:mm[:ss]]
degrees, minutes, seconds. Negative values are West
-z --timezone either a timezone name (see section TIMEZONES) or
numeric offset +/-UTC. Notation may be in decimal
hours (hh[.hh]) or hours, minutes (hh[:mm])
--hebrew forces Hebrew to print in Hebrew characters
--yom force Hebrew prefix to Hebrew day of week
--leshabbat insert parasha between day of week and day
--leseder insert parasha between day of week and day
--not-sunset-aware
don't display next day if after sunset
--data-first display data, followed by it's description
--labels-first display data descriptions before the data itself
--prefer-hebrew how to interpret ambiguous month and year
--prefer-gregorian parameters. (eg. interpret "6 10" as "Adar 5710"
or as "June 2010"). Hebrew is the default.
NOTES
TIMEZONES
hdate accepts as timezone parameters either an absolute numeric offset
from UTC, or an official timezone name, as found on many *nix operating
systems at /usr/share/zoneinfo/zone.tab. These names are typically in
the form 'continent/city' (eg. Asia/Jerusalem); however, hdate is flex‐
ible and will accept any unique substring of a timezone name, and will
report how it interpreted your input. For example, 'jer' will be inter‐
preted as Israel time. Names use underscores in place of spaces, but
hdate will accept spaces as long as the parameter is quoted ("w y" is
acceptable for America/New_York, but so would be 'new'). When given a
timezone name, hdate will be aware of daylight savings time transitions
and will report times-of-day accordingly. When given no timezone infor‐
mation, hdate will try to find out your computer's local timezone. If
that fails, it will attempt to find your computer's UTC offset. If all
else fails, Jerusalem Standard time is used.
LOCATIONS
If you want hdate to display accurate time-of-day information, hdate
requires location and time zone information in order to make astronomi‐
cal calculations for a given date. If you don't provide any such infor‐
mation, hdate tries to find out your computer's local time zone infor‐
mation as an indicator, and picks the 'primary' city in that time zone.
If hdate can't find local time zone information, hdate tries to find
out your computer's GMT offset, and either picks from the list below
the city in that time zone offset, or defaults to the equator at the
center of that time zone offset. If hdate can't even retrieve GMT off‐
set information from your computer, it defaults to Tel-Aviv. For other
locations, use the -l -L option pair. For other timezones, use the -z
option. Co-ordinates and standard time zones for some common locations
are listed below.
The current defaults are:
tz Lat Lon tz Lat Lon
-8 Los Angeles 34.05 -118.25 2 Tel-Aviv 32 34.75
-6 Mexico City 19.43 -99.13 3.5 Tehran 35.67 51.43
-5 New York City 40.75 -74 4 Moscow 55.75 37.62
-4.5 Caracas 10.54 -66.93 5 Tashkent 41.27 69.22
-3 Buenos Aires -34.61 -58.37 5.5 Calcutta 22.57 88.36
0 London 51.5 0 8 Beijing 39.90 116.38
1 Paris 48.86 2.34 10 Sydney -33.87 151.21
Useful locations and time zones
tz Lat Lon tz Lat Lon
2 Jerusalem 31.78 35.22 8 Hong Kong 22.26 114.15
2 Haifa 32.82 34.99 -6 Chicago 41.84 -87.67
2 Beer Sheva 31.25 34.80 -3 Sao Paolo -23.52 -46.63
2 Ashdod 31.80 34.64 -5 Toronto 43.75 -79.38
2 Tiberias 40.89 35.84 1 Antwerpen 51.22 4.42
2 Eilat 29.56 34.95
HOLIDAYS AND CUSTOM DAYS
By default, if you ask hdate to display holiday names (options -h or
--holidays), hdate uses libhdate's data set of the traditional
'shulchan aruch' Hebrew holidays. hdate also creates a user-modifiable
config file, custom_days, for any other personal or national days a
user might want to mark. The config file contains detailed in-line doc‐
umentation, and allows for simple definitions of custom days by either
the Hebrew or gregorian calendar; by either calendar day of a month or
nth day of week of a month; and provides a simple method of specifying
how/whether to advance/postpone a custom day should it occur on any
undesired day of week.
JULIAN DAY
The julian day system is not directly related to the Julian calendar.
Rather, it was introduced by astronomers for scientific use to provide
a single system of dates that could be used when working with different
calendars and to unify different historical chronologies. Julian day
number (JDN) zero corresponds to January 1, 4713 BCE Greenwich noon,
according to the "julian proleptic calendar".
TABULAR OUTPUT
When invoked with option -T ( --table or --tabular ), hdate outputs the
requested data for any single day in comma-delimited format, with no
intervening spaces. The only exception is that holidays and custom_days
are delimited from each other with semi-colons, because there may be
more than one of those entries for any given day. When invoked for a
month (no dd supplied) or a year (no dd or dd supplied), data for sepa‐
rate days are new-line-delimited. The first line of tabular output is a
header line, describing each field being output, and delimited in the
same way as the data line(s). Output of the header line can be sup‐
pressed using option -qqq ( --quiet-descriptions ).
FILES
CONFIG FILES
The config files and their parent folder will be automatically created.
Each file includes its own documentation, in-line. Should you ever wish
to restore a config file to its original text, rename or delete your
current one; hdate will create a replacement automatically on its next
invocation. Both hdate and hcal make use of identically formatted cus‐
tom_days files, so you may freely copy that file from one config folder
to the other, or use a symbolic link so both programs will always use
the same custom_days information.
${XDG_CONFIG_HOME}/hdate/hdaterc_v1.8
${XDG_CONFIG_HOME}/hdate/custom_days_v1.8
If ${XDG_CONFIG_HOME} is undefined:
~/.config/hdate/hdaterc
~/.config/hdate/custom_days
BUGS
Accuracy The accuracy of the astronomically-derived data will suffer
from not accounting for environmental conditions such as ele‐
vation, horizon, temperature and air pressure.
Timezonesmu
The timezone support is currenlty primitive and lacks support
for daylight savings time transitions.
Historical
The software does not yet account for the phenomenon and com‐
plications of the "Gregorian transition" from the prior,
julian calendar, which effectively caused an instantaneous
'loss' of two weeks for all gentiles affected. Countries (eg.
Poland, Spain and Italy) began adopting the Gregorian calen‐
dar on 8 Tishrei 5343 (4 October 1582 CE), although many did
not transition until the 56th century (1752 CE, eg. UK
colonies, Sweden). Russia did not adopt the Gregorian calen‐
dar until 5678 (1918 CE) and Turkey did not until 5687
(December, 1926 CE). Many other countries made the transition
on other dates. Keep in mind that Russia invaded part of
Poland, undoing, for the interim, the Gregorian transition
for (only) that part of Poland; Also important to remember in
this regard is that Eretz Ysroel was part of the Turkish
Ottoman empire until the British mandate (5677 (1917 CE)).
Until all this is accounted for adequately by this applica‐
tion, refer to 'ncal -p' for a basic table of country transi‐
tions. However, keep in mind that European borders underwent
many changes during the 426 years in question, so the accu‐
racy of your data will depend on accurate knowledge of
whether any particular date at any specific location was
Julian or Gregorian.
EXAMPLES
1. Display data for the entire month of Adar, with a candle-lighting
custom of 29 minutes.
hdate --candles=29 adar
2. Create an iCal calendar of the holidays of year 2025.
hdate -Hi 2025
3. Print out the weekly readings and sunset/sunrise times for Eilat, on
April 2031 CE.
hdate -sR 4 2031 -l29.56 -L34.95 -z Jerusalem
Flexible date entry
tiSHREi ; yerech_haeitanim ; 1 Elul 44; 1 sep 1944; 44 oct 21 ; April ;
aPril ; ziv ; bool ; Mar-Cheshvan ; menachemav
Flexible Hebrew month transliterations
tIchriy, jechvan, xeshvan, khechvan, kisayv, teivayt, sh\'vat, addar,
adarI, "adar A", adar_2, adar-alef, adaraleph, adARBeth, nissan, eeyar,
ceevvan, taMUz, aV, elloul (and many more).
SEE ALSO
mlterm(1), hdate(1) ,hebcal(1), date(1), ncal(1), cal(1), remind(1)
AUTHORS
Boruch Baum 2011-2013. Yaacov Zamir 2005-2010.
project page: http://libhdate.sourceforge.net
hcal and hdate are part of the package libhdate, a small C/C++ library
for Hebrew dates, holidays, and reading sequences (parashiot). It uses
the source code from Amos Shapir's "hdate" package, as fixed and
patched by Nadav Har'El. The Torah reading sequence tables were con‐
tributed by Zvi Har'El.
libhdate version 1.8 2013-01-01 hdate(1)