1
2JCTIME(3)                      libjalali Manual                      JCTIME(3)
3
4
5

NAME

7       jasctime,  jctime,  jgmtime, jlocaltime, jmktime, jasctime_r, jctime_r,
8       jgmtime_r, jlocaltime_r - transform jalali date and time to broken-down
9       jalali time or ASCII
10

SYNOPSIS

12       #include <jtime.h>
13
14       char *jasctime(const struct jtm *jtm);
15       char *jasctime_r(const struct jtm *jtm, char *buf);
16
17       char *jctime(const time_t *timep);
18       char *jctime_r(const time_t *timep, char *buf);
19
20       struct jtm *jgmtime(const time_t *timep);
21       struct jtm *jgmtime_r(const time_t *timep, struct jtm *result);
22
23       struct jtm *jlocaltime(const time_t *timep);
24       struct jtm *jlocaltime_r(const time_t *timep, struct jtm *result);
25
26       time_t jmktime(struct jtm *jtm);
27
28       #include <jalali.h>
29
30       int jalali_is_jleap(int year);
31
32       void jalali_create_time_from_secs(time_t time, struct ab_jtm* ab_jtm);
33       time_t jalali_create_secs_from_time(const struct ab_jtm* ab_jtm);
34
35       int jalali_create_date_from_days(struct jtm* jtm);
36       int jalali_create_days_from_date(struct jtm* jtm);
37
38       void jalali_get_jyear_info(struct jyinfo* jyinfo);
39
40       void jalali_get_date(int p, struct jtm* jtm);
41       int jalali_get_diff(const struct jtm* jtm);
42
43       void jalali_update(struct jtm* jtm);
44
45
46       Link with -ljalali
47
48

DESCRIPTION

50       The jctime(), jgmtime() and jlocaltime() functions all take an argument
51       of data type time_t which represents calendar time.   When  interpreted
52       as  an absolute time value, it represents the number of seconds elapsed
53       since the Epoch,  1970-01-01  (1348-10-11  in  Jalali)  00:00:00  +0000
54       (UTC).
55
56       The jasctime() and jmktime() functions both take an argument represent‐
57       ing broken-down jalali time which is a  representation  separated  into
58       year, month, day, etc.
59
60       Broken-down jalali time is stored in the structure jtm which is defined
61       in <jtime.h> as follows:
62
63           struct jtm {
64               int tm_sec;         /* seconds */
65               int tm_min;         /* minutes */
66               int tm_hour;        /* hours */
67               int tm_mday;        /* day of the month */
68               int tm_mon;         /* month */
69               int tm_year;        /* year */
70               int tm_wday;        /* day of the week */
71               int tm_yday;        /* day in the year */
72               int tm_isdst;       /* daylight saving time */
73           };
74
75       The members of the jtm structure are:
76
77       tm_sec    The number of seconds after the minute, in the range 0 to 59.
78
79       tm_min    The number of minutes after the hour, in the range 0 to 59.
80
81       tm_hour   The number of hours past midnight, in the range 0 to 23.
82
83       tm_mday   The day of the month, in the range 1 to 31.
84
85       tm_mon    The number of months since Farvadin, in the range 0 to 11.
86
87       tm_year   Absolute year number including the century.
88
89       tm_wday   The number of days since Saturday, in the range 0 to 6.
90
91       tm_yday   The number of days since Farvadin 1, in the range 0 to 365.
92
93       tm_isdst  A flag that indicates whether  daylight  saving  time  is  in
94                 effect  at the time described.  The value is positive if day‐
95                 light saving time is in effect, zero otherwise.
96
97       Information about a certain year in jalali  system  is  stored  in  the
98       structure jyinfo in the following format:
99
100           struct jyinfo {
101               int lf;                /* leap indicator flag */
102               int y;                 /* year */
103               int r;                 /* reamining years in grand cycle */
104               int p;                 /* passed years from grand cycle*/
105               int rl;                /* remaining leap years in grand cycle */
106               int pl;                /* passed leap years in grand cycle */
107               int apl;               /* absolute passed leaps */
108           };
109
110       The members of the jyinfo structure are:
111
112       lf        A flag that indicates whether a year is leap or not.
113
114       y         Absolute year number including the century.
115
116       r         The number of remaining years in the grand cycle. (2820 years
117                 in length)
118
119       p         The number of passed years in the grand cycle.
120
121       rl        The number of remaining leap years in the grand cycle.
122
123       pl        The number of passed leap years in the grand cycle.
124
125       apl       The absolute number of passed leaps since Epoch.
126
127       Internal jalali date functions make use of passed days since UTC  Epoch
128       to  calculate  date and time. To store these information, the following
129       structure is also defined:
130
131           struct ab_jtm {
132               int ab_sec;
133               int ab_min;
134               int ab_hour;
135               int ab_days;
136           };
137
138       The members of the ab_jtm structure are as follows:
139
140       ab_sec    The number of seconds.
141
142       ab_min    The number of minutes.
143
144       ab_hour   The number of hours
145
146       ab_days   The absolute number of days since UTC Epoch. (1348-10-11)
147
148       The call jctime(t) is equivalent to jasctime(jlocaltime(t)).   It  con‐
149       verts the calendar time t into a null-terminated string of the form
150
151              "Jom Kho 06 22:59:17 1390\n"
152
153       The  abbreviations  for  the  days of the week are "Sun", "Mon", "Tue",
154       "Wed", "Thu", "Fri", and "Sat".  Farsi transliteration for the days  of
155       the  week are "Sha", "Yek", "Dos", "Ses", "Cha", "Pan", and "Jom".  The
156       abbreviations for the months are "Far",  "Ord",  "Kho",  "Tir",  "Mor",
157       "Sha",  "Meh", "Aba", "Aza", "Dey", "Bah", and "Esf".  The return value
158       points to a statically allocated string which might be  overwritten  by
159       subsequent  calls to any of the date and time functions.  The reentrant
160       version jctime_r() does the same, but stores the string in a  user-sup‐
161       plied buffer which should have room for at least 26 bytes.
162
163       The  jgmtime() function converts the calendar time timep to broken-down
164       jalali time representation, expressed  in  Coordinated  Universal  Time
165       (UTC).   The return value points to a statically allocated struct which
166       might be overwritten by subsequent calls to any of the jalali date  and
167       time functions.  The jgmtime_r() function does the same, but stores the
168       data in a user-supplied struct.  The function  acts  as  if  it  called
169       tzset(3)
170
171       The  jlocaltime()  function converts the calendar time timep to broken-
172       down jalali time representation, expressed relative to the user's spec‐
173       ified  timezone.   The  function acts as if it called tzset(3) and sets
174       the external variables tzname with information about the current  time‐
175       zone,  timezone  with the difference between Coordinated Universal Time
176       (UTC) and local standard time in seconds, and  daylight  to  a  nonzero
177       value  if  daylight  savings  time  rules apply during some part of the
178       year.  The return value points to a statically allocated  struct  which
179       might  be overwritten by subsequent calls to any of the jalali date and
180       time functions.  The jlocaltime_r() function does the same, but  stores
181       the data in a user-supplied struct.
182
183       The  jasctime() function converts the broken-down jalali time value jtm
184       into a null-terminated string with the same format  as  jctime().   The
185       return  value  points  to  a statically allocated string which might be
186       overwritten by subsequent calls to any of the date and time  functions.
187       The  jasctime_r()  function  does  the same, but stores the string in a
188       user-supplied buffer which should have room for at least 26 bytes.
189
190       The jmktime() function converts a broken-down  jalali  time  structure,
191       expressed as local time, to calendar time representation.  The function
192       ignores the values supplied by the caller in the  tm_wday  field.   The
193       value  specified in the tm_isdst field informs jmktime() whether or not
194       daylight saving time (DST) is in effect for the time  supplied  in  the
195       jtm structure: a positive value means DST is in effect; zero means that
196       DST is not in effect;
197
198       The jmktime() function modifies the fields of the jtm structure as fol‐
199       lows:  tm_wday  and  tm_yday are set to values determined from the con‐
200       tents of the other fields; if structure members are outside their valid
201       interval,  they  will be normalized (so that, for example, 40 Bahman is
202       changed into 10 Esfand); Calling jmktime() also sets the external vari‐
203       able tzname with information about the current timezone.
204
205       jmktime() function does not check the values of the jtm structure.
206
207
208       There are a number of non-standard functions also provided to work with
209       jalali date and time.
210
211
212       The jalali_is_jleap() function returns an  integer  indicating  whether
213       the  year  specified  is  leap  or  not.   It returns 1 on the event of
214       encountering a leap year, 0 otherwise.
215
216
217       The jalali_create_time_from_secs() function fills out the ab_jtm struc‐
218       ture  members based on the absolute number of seconds elapsed since UTC
219       Epoch.
220
221
222       The jalali_create_secs_from_time() function is the converse function to
223       jalali_create_time_from_secs() which returns absolute number of seconds
224       elapsed since UTC Epoch based on the supplied ab_jtm structure.
225
226
227       The jalali_create_date_from_days() function alters tm_mon  and  tm_mday
228       fields  of  the broken-down jalali time strucutre based on it's tm_yday
229       field.  It returns -1 on the  event  of  encountering  any  errors  and
230       structure fields remain untouched.
231
232
233       The jalali_create_days_from_date() function alters tm_yday field of the
234       broken-down jalali time structure based  on  it's  tm_mon  and  tm_mday
235       fields.  It  returns  -1  on  the  event of encountering any errors and
236       structure fields remain untouched.
237
238
239       The jalali_get_jyear_info() function modifies jyinfo  structure  fields
240       to  match  information  for year specified by it's y field. Information
241       regarding a year in  jalali  system  includes  leap  flag,  passed  and
242       reamining  years in the grand cycle, passed and remaining leap years in
243       the grand cycle and absolute number of passed leaps since UTC Epoch.
244
245
246       The jalali_get_date() function calculates the jalali date based on num‐
247       ber  of  days  since  UTC  epoch. It alters the broken-down jalali time
248       structure fields accordingly.
249
250
251       The  jalali_get_diff()   function   is   the   converse   function   of
252       jalali_get_date()  and  calculates  the number of days passed since UTC
253       Epoch based on a broken-down jalali time structure supplied to it.
254
255
256       The jalali_update() function updates tm_wday and tm_yday fields of  the
257       broken-down  jalali  time  structure based on it's tm_year , tm_mon and
258       tm_mday. tm_isdst, tm_gmtoff and tm_zone fields  are  set  accordingly.
259       tm_hour, tm_min and tm_sec fields remain untouched.
260
261

EXAMPLES

263       The following program converts a jalali date to gregorian
264       #include <stdio.h>
265       #include <stdlib.h>
266       #include <time.h>
267       #include <jalali.h>
268       #include <jtime.h>
269
270       int
271       main(int argc, char ** argv)
272       {
273           struct tm tm;
274           struct jtm jtm;
275           time_t t;
276
277           jtm.tm_year = atoi(argv[1]);
278           jtm.tm_mon = atoi(argv[2]);
279           jtm.tm_mday = atoi(argv[3]);
280
281           jalali_update(&jtm);
282           t = jmktime(&jtm);
283           localtime_r(&t, &tm);
284           printf("%d/%d/%d \n", tm.tm_year, tm.tm_mon, tm.tm_mday);
285           exit(EXIT_SUCCESS);
286       }
287
288

RETURN VALUE

290       Each  of  these  functions  returns the value described, or NULL (-1 in
291       case of jmktime()) in case an error was detected.
292

CONFORMING TO

294       C99 Standards.  These functions are provided with APIs similar to  that
295       of  POSIX.1-2001  date  and time manipulation and are NOT part of POSIX
296       standard. For thread  safety  jasctime(),  jctime(),  gmtime(),  local‐
297       time(),  and  mktime()  set of functions should nout be used. See reen‐
298       trant versions.
299
300       like POSIX.1-2008, the following functions:  jasctime(),  jasctime_r(),
301       jctime(),  and  jctime_r()  should  be considered obsolete.  Use jstrf‐
302       time(3) instead.
303

NOTES

305       The four functions jasctime(),  jctime(),  jgmtime()  and  jlocaltime()
306       return a pointer to static data and hence are not thread-safe.  Thread-
307       safe versions are jasctime_r(),  jctime_r(),  jgmtime_r()  and  jlocal‐
308       time_r()
309
310
311       libjalali version of struct jtm has additional fields
312
313              long tm_gmtoff;           /* Seconds east of UTC */
314              const char *tm_zone;      /* Timezone abbreviation */
315
316

SEE ALSO

318       jdate(1),  jcal(1), gettimeofday(2), time(2), utime(2), clock(3), diff‐
319       time(3), jstrftime(3), jstrptime(3), timegm(3), tzset(3), time(7)
320

COLOPHON

322       This page is part of release 0.2 of the libjalali man-pages
323

AUTHOR

325       Written by Ashkan Ghassemi. <ghassemi@ftml.net>
326

REPORTING BUGS

328       Report libjalali bugs to <ghassemi@ftml.net>
329
330       libjalali home page: <http://savannah.nongnu.org/projects/jcal/>
331
333       Copyright (C) 2011 Ashkan Ghassemi.
334
335       License    LGPLv3+:     GNU     LGPL     version     3     or     later
336       <http://gnu.org/licenses/lgpl.html>.   This  is  free software: you are
337       free to change and redistribute it. There is NO WARRANTY, to the extent
338       permitted by law.
339
340
341
342                                  2011-05-28                         JCTIME(3)
Impressum