home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / std_unix / mod.std.unix.v5 / text0056.txt < prev    next >
Encoding:
Internet Message Format  |  1987-06-30  |  11.6 KB
  1. From: seismo!elsie!ado
  2. Date: Fri, 21 Feb 86 22:48:58 EST
  3.  
  4. # To unundle, sh this file
  5. echo README 1>&2
  6. cat >README <<'End of README'
  7. @(#)README    1.4
  8.  
  9. The shell archive of which this file is a part contains man pages for functions
  10. and a file format designed to deal with Daylight Savings Time variations.
  11.  
  12. The basic idea is to have a system-wide directory that contains binary files
  13. describing time zone rules; functions such as "localtime" could read such
  14. files before doing time conversions.
  15.  
  16. A manual page for a "time zone compiler" that turns text-file descriptions of
  17. time zone rules into binary files is also included, as is a sample input file
  18. for the compiler.  These would, of course, not be part of the standard;
  19. they are included here only to show that the binary files that would be used
  20. under this scheme can be readily created.
  21.  
  22. Source code for these functions and for the time zone compiler are available
  23. from seismo!elsie!ado, the person to whom to direct comments (with, perhaps,
  24. carbon copes to cbosgd!mark and seismo!philabs!linus!encore!necis!geo,
  25. who are responsible for any good ideas that show up here).
  26. End of README
  27. echo settz.3 1>&2
  28. cat >settz.3 <<'End of settz.3'
  29. .TH SETTZ 3 
  30. .SH NAME
  31. settz, newctime, newlocaltime \-  convert date and time to ASCII
  32. .SH SYNOPSIS
  33. .nf
  34. .B settz(zonename)
  35. .B char *zonename;
  36. .PP
  37. .B char *newctime(clock)
  38. .B long *clock;
  39. .PP
  40. .B
  41. #include "time.h"
  42. .PP
  43. .B struct tm *newlocaltime(clock)
  44. .B long *clock;
  45. .PP
  46. .B char *tz_abbr;
  47. .SH DESCRIPTION
  48. .I Settz
  49. sets time zone information used by
  50. .I newctime
  51. and
  52. .IR newlocaltime .
  53. If
  54. .I zonename
  55. begins with a slash,
  56. it is used as the absolute pathname of the
  57. .IR tzfile (5)-format
  58. file from which to read the time zone information;
  59. if
  60. .I zonename
  61. begins with some other character,
  62. it is used as a pathname relative to the standard time zone information
  63. directory.  A call of the form
  64. .ti +.5i
  65. .B
  66. settz("")
  67. .br
  68. causes built-in information about GMT to be used; a call of the form
  69. .ti +.5i
  70. .B
  71. settz((char *) 0)
  72. .br
  73. is treated as if it were a call of the form
  74. .ti +.5i
  75. .B
  76. settz("localtime")
  77. .PP
  78. .I Newlocaltime
  79. has the same argument and return value as
  80. .IR localtime .
  81. If
  82. .I newlocaltime
  83. is called before
  84. .I settz
  85. is called,
  86. .I newlocaltime
  87. calls
  88. .I settz
  89. with the value returned by
  90. .B
  91. getenv("TZ").
  92. .I Newlocaltime
  93. sets
  94. tz_abbr
  95. to a pointer to an 
  96. ASCII string that's the time zone abbreviation to be used with
  97. .IR newlocaltime 's
  98. return value.
  99. .PP
  100. .I Newctime
  101. returns a pointer to a string of the form
  102. .ti +.5i
  103. Sat Feb 15 15:45:51 1986 EST\\n\\0
  104. .br
  105. where the last (variable-width) field is the time zone abbreviation.
  106. .SH DIAGNOSTICS
  107. .I Settz
  108. returns zero if all seems well; it returns negative one otherwise
  109. (and sets things up so that its built-in information about GMT is used).
  110. .SH FILES
  111. /etc/tzdir    standard time zone information directory
  112. .SH "SEE ALSO"
  113. ctime(3), getenv(3), tzfile(5)
  114. .. @(#)settz.3    1.3
  115. End of settz.3
  116. echo tzfile.5 1>&2
  117. cat >tzfile.5 <<'End of tzfile.5'
  118. .TH TZFILE 5
  119. .SH NAME
  120. tzfile \- time zone information
  121. .SH SYNOPSIS
  122. .B
  123. #include "tzfile.h"
  124. .SH DESCRIPTION
  125. The time zone information files used by
  126. .IR settz (3)
  127. and
  128. .IR newlocaltime (3)
  129. have the format of the
  130. .I tzinfo
  131. structure described in the include file
  132. .B 
  133. "tzfile.h":
  134. .sp
  135. .nf
  136. .in +.5i
  137. struct tzinfo {
  138.     int    tz_timecnt;
  139.     long    tz_times[TZ_MAX_TIMES];
  140.     char    tz_types[TZ_MAX_TIMES];
  141.     struct dsinfo {
  142.         long    ds_gmtoff;
  143.         char    ds_abbr[TZ_ABBR_LEN+1];
  144.         char    ds_isdst;
  145.     }    tz_dsinfo[TZ_MAX_TYPES];
  146. };
  147. .fi
  148. .PP
  149. The
  150. .B tz_timecnt
  151. field tells how many of the
  152. .B tz_times
  153. and
  154. .B tz_types
  155. stored in the file are meaningful.
  156. Each of the meaningful
  157. .B tz_times
  158. entries is a starting time (as returned by
  159. .IR time (2));
  160. the same-indexed
  161. .B tz_types
  162. entry is the index of the
  163. .B tz_dsinfo
  164. array element that tells about how "local time" is generated starting at that
  165. time.
  166. For a file to be used by
  167. .IR settz ,
  168. its
  169. .B tz_times
  170. entries must be sorted in ascending order.
  171. .PP
  172. In the
  173. .B tz_dsinfo
  174. structures,
  175. .B ds_gmtoff
  176. gives the number of seconds that should be added to GMT;
  177. .B ds_abbr
  178. is the ASCII-NUL-terminated string used as the time zone abbreviation;
  179. and
  180. .B
  181. ds_isdst
  182. tells whether
  183. .B
  184. tm_isdst
  185. should be set by
  186. .IR newlocaltime (3).
  187. .PP
  188. .I Newlocaltime
  189. uses the first element of
  190. .B tz_dsinfo
  191. if either
  192. .B tz_timecnt
  193. is zero or
  194. .IR newlocaltime 's
  195. argument is less than
  196. .BR tz_times[0] .
  197. .SH SEE ALSO
  198. settz(3)
  199. .. @(#)tzfile.5    1.4
  200. End of tzfile.5
  201. echo tzcomp.8 1>&2
  202. cat >tzcomp.8 <<'End of tzcomp.8'
  203. .TH TZCOMP 8
  204. .SH NAME
  205. tzcomp \- time zone compiler
  206. .SH SYNOPSIS
  207. .B tzcomp
  208. [
  209. .B \-d
  210. directory ] filename ...
  211. .SH DESCRIPTION
  212. .I Tzcomp
  213. reads text from the file(s) named on the command line
  214. and creates the time zone information files specified in this input.
  215. If a
  216. .I filename
  217. is
  218. .BR ` - ',
  219. the standard input is read.
  220. .PP
  221. This option is available:
  222. .TP
  223. .B \-d directory
  224. Create time zone information files in the named directory rather than
  225. in the standard directory named below.
  226. .PP
  227. A sharp characters (#) in the input introduces a comment which extends to
  228. the end of the line the sharp character appears on.
  229. Any line which is blank (after comment stripping) is ignored.
  230. Non-blank lines are expected to be of one of three
  231. types:  rule lines, zone lines, and link lines.
  232. .PP
  233. A rule line has the form
  234. .nf
  235. .B
  236. .ti +.5i
  237. .ta \w'Rule 'u +\w'MostNA 'u +\w'FROM 'u +\w'1973 'u +\w'TYPE 'u +\w'Apr 'u +\w'lastSun 'u +\w'2:00 'u +\w'SAVE 'u
  238. .sp
  239. Rule    NAME    FROM    TO    TYPE    IN    ON    AT    SAVE    LETTER/S
  240. .sp
  241. For example:
  242. .ti +.5i
  243. .sp
  244. Rule    MostNA    1969    1973    -    Apr    lastSun    2:00    1:00    D
  245. .sp
  246. .fi
  247. The fields that make up a rule line are:
  248. .TP
  249. .B NAME
  250. Gives the (arbitrary) name of the set of rules this rule is part of.
  251. .TP
  252. .B FROM
  253. Gives the first year in which the rule applies.
  254. .TP
  255. .B TO
  256. Gives the last year in which the rule applies.
  257. The word
  258. .RB ` only '
  259. may be used to repeat the value of the
  260. .B
  261. FROM
  262. field.
  263. .TP
  264. .B TYPE
  265. Gives the type of year in which the year applies.  If
  266. .B TYPE
  267. is
  268. .B
  269. "-"
  270. then the rule is taken to apply in all years between
  271. .B FROM
  272. and
  273. .B TO
  274. inclusive.
  275. If
  276. .B TYPE
  277. is something else, then the command
  278. .B
  279. .ti +.5i
  280. years from to type
  281. .br
  282. is executed with arguments
  283. .IR from ,
  284. .IR to ,
  285. and
  286. .IR type
  287. taken from the rule line; the rule is taken to apply only in those years
  288. printed by the
  289. .I years
  290. command.
  291.  
  292. The distributed
  293. .I years
  294. command is a shell script that can handle year types
  295. .B uspres
  296. (United States presidential election years)
  297. and
  298. .B nonpres
  299. (all other years);
  300. other year types may be added by changing the script.
  301. .TP
  302. .B IN
  303. Names the month in which the rule takes effect.  Month names may be
  304. abbreviated.
  305. .TP
  306. .B ON
  307. Gives the day on which the rule takes effect.
  308. Recognized forms include:
  309. .nf
  310. .in +.5i
  311. .sp
  312. .ta \w'lastSun  'u
  313. 5    the fifth of the month
  314. lastSun    the last Sunday in the month
  315. lastMon    the last Monday in the month
  316. Sun>=8    first Sunday on or after the eighth
  317. Sun<=25    last Sunday on or before the 25th
  318. .fi
  319. .in -.5i
  320. .sp
  321. Names of days of the week may be abbreviated or spelled out in full.
  322. Note that there must be no spaces within the
  323. .B ON
  324. field 
  325. (or within any other field).
  326. .TP
  327. .B AT
  328. Gives the time of day at which the rule takes affect.
  329. Recognized forms include:
  330. .nf
  331. .in +.5i
  332. .sp
  333. .ta \w'1:28:13  'u
  334. 2    time in hours
  335. 2:00    time in hours and minutes
  336. 15:00    24-hour format time (for times after noon)
  337. 1:28:14    time in hours, minutes, and seconds
  338. .fi
  339. .in -.5i
  340. .sp
  341. .TP
  342. .B SAVE
  343. Gives the amount of time to be added to local standard time when the rule is in
  344. effect.  This field has the same format as the
  345. .B AT
  346. field.
  347. .TP
  348. .B LETTER/S
  349. Gives the "variable part" (for example, the 'S' or 'D' in "EST" or "EDT")
  350. of time zone abbreviations to be used when this rule is in effect.
  351. If this field is
  352. .B
  353. "-",
  354. the variable part is null.
  355. .PP
  356. A zone line has the form
  357. .sp
  358. .nf
  359. .ti +.5i
  360. .ta \w'Zone 'u +\w'Eastern 'u +\w'GMTOFF 'u +\w'MostNA 'u
  361. Zone    NAME    GMTOFF    RULES    FORMAT
  362. .sp
  363. For example:
  364. .sp
  365. .ti +.5i
  366. Zone    Eastern    -5:00    MostNA    E%sT
  367. .sp
  368. .fi
  369. The fields that make up a zone line are:
  370. .TP
  371. .B NAME
  372. The name of the time zone.
  373. This is the name used in creating the time zone information file for the zone.
  374. .TP
  375. .B GMTOFF
  376. The amount of time to add to GMT to get standard time in this zone.
  377. This field has the same format as the
  378. .B AT
  379. and
  380. .B SAVE
  381. fields of rule lines;
  382. begin the field with a minus sign if time must be subtracted from GMT.
  383. .TP
  384. .B RULES
  385. The name of the rule(s) that apply in the time zone.
  386. If this field contains
  387. .B
  388. "-"
  389. then standard time always applies in the time zone.
  390. .TP
  391. .B FORMAT
  392. The format for time zone abbreviations in this time zone.
  393. The pairs of characters
  394. .B
  395. "%s"
  396. is used to show where the "variable part" of the time zone abbreviation goes.
  397. .PP
  398. A link line has the form
  399. .sp
  400. .nf
  401. .ti +.5i
  402. .ta \w'Link 'u +\w'LINK-FROM 'u
  403. Link    LINK-FROM    LINK-TO
  404. .sp
  405. For example:
  406. .sp
  407. .ti +.5i
  408. Link    Eastern        EST5EDT
  409. .sp
  410. .fi
  411. The
  412. .B LINK-FROM
  413. field should appear as the
  414. .B NAME
  415. field in some zone line;
  416. the
  417. .B LINK-TO
  418. field is used as an alternate name for that zone.
  419. .PP
  420. Lines may appear in any order in the input.
  421. .SH EXAMPLE
  422. [Since a sample time zone file appears in the shell archive,
  423. this section has been omitted.]
  424. .SH FILES
  425. /etc/tzdir    standard directory used for created files
  426. .SH "SEE ALSO"
  427. settz(3), tzfile(5)
  428. .. @(#)tzcomp.8    1.4
  429. End of tzcomp.8
  430. echo tzinfo 1>&2
  431. cat >tzinfo <<'End of tzinfo'
  432. # @(#)tzinfo    1.5
  433.  
  434. # Rule    NAME    FROM    TO    TYPE    IN    ON    AT    SAVE    LETTER/S
  435. Rule    MostNA    1969    1973    -    Apr    lastSun    2:00    1:00    D
  436. Rule    MostNA    1969    1973    -    Oct    lastSun    2:00    0    S
  437. Rule    MostNA    1974    only    -    Jan    6    2:00    1:00    D
  438. Rule    MostNA    1974    only    -    Nov    24    2:00    0    S
  439. Rule    MostNA    1975    only    -    Feb    23    2:00    1:00    D
  440. Rule    MostNA    1975    only    -    Oct    26    2:00    0    S
  441. Rule    MostNA    1976    2037    -    Apr    lastSun    2:00    1:00    D
  442. Rule    MostNA    1976    2037    -    Oct    lastSun    2:00    0    S
  443.  
  444. # Almost surely wrong:
  445.  
  446. # Rule    NAME    FROM    TO    TYPE    IN    ON    AT    SAVE    LETTER/S
  447. Rule    Oz-Eur    1969    1973    -    Apr    lastSun    2:00    1:00    S
  448. Rule    Oz-Eur    1969    1973    -    Oct    lastSun    2:00    0    -
  449. Rule    Oz-Eur    1974    only    -    Jan    6    2:00    1:00    S
  450. Rule    Oz-Eur    1974    only    -    Nov    24    2:00    0    -
  451. Rule    Oz-Eur    1975    only    -    Feb    23    2:00    1:00    S
  452. Rule    Oz-Eur    1975    only    -    Oct    26    2:00    0    -
  453. Rule    Oz-Eur    1976    2037    -    Apr    lastSun    2:00    1:00    S
  454. Rule    Oz-Eur    1976    2037    -    Oct    lastSun    2:00    0    -
  455.  
  456. # New names
  457.  
  458. # Zone    NAME        GMTOFF    RULES    FORMAT
  459. Zone    Atlantic    -4:00    MostNA    A%sT
  460. Zone    Eastern        -5:00    MostNA    E%sT
  461. Zone    Central        -6:00    MostNA    C%sT
  462. Zone    Mountain    -7:00    MostNA    M%sT
  463. Zone    Pacific        -8:00    MostNA    P%sT
  464. Zone    Yukon        -9:00    MostNA    Y%sT
  465. Zone    Hawaiian    -10:00    MostNA    H%sT
  466. Zone    Newfoundland    -3:30    -    NST
  467. Zone    Japan        9:00    -    JST
  468. Zone    WET        0    Oz-Eur    WE%sT
  469. Zone    MET        1     Oz-Eur    ME%sT
  470. Zone    EET        2    Oz-Eur    EE%sT
  471. Zone    AEST        10:00    Oz-Eur    AES%sT
  472. Zone    ACST        9:30    Oz-Eur    ACS%sT
  473. Zone    AWST        8:00    -    AWST    # No Daylight Saving here?
  474.  
  475. #
  476. # A settz("") uses the code's built-in GMT without going to disk to get
  477. # the information.  Still, we want things to work if somebody does a
  478. # settz("GMT"), so. . .
  479. #
  480.  
  481. Zone    GMT        0    -    GMT
  482.  
  483. # Old names
  484.  
  485. # Link    LINK-FROM    LINK-TO
  486. Link    Eastern        EST5EDT
  487. Link    Central        CST6CDT
  488. Link    Mountain    MST7MDT
  489. Link    Pacific        PST8PDT
  490.  
  491. # "Pacific Presidential Election Time" is being contemplated in Congress
  492.  
  493. # Rule    NAME    FROM    TO    TYPE    IN    ON    AT    SAVE    LETTER/S
  494. Rule    Twilite    1969    1973    -    Apr    lastSun    2:00    1:00    D
  495. Rule    Twilite    1969    1973    -    Oct    lastSun    2:00    0    S
  496. Rule    Twilite    1974    only    -    Jan    6    2:00    1:00    D
  497. Rule    Twilite    1974    only    -    Nov    24    2:00    0    S
  498. Rule    Twilite    1975    only    -    Feb    23    2:00    1:00    D
  499. Rule    Twilite    1975    only    -    Oct    26    2:00    0    S
  500. Rule    Twilite    1976    2037    -    Apr    lastSun    2:00    1:00    D
  501. Rule    Twilite    1976    1987    -    Oct    lastSun    2:00    0    S
  502. Rule    Twilite    1988    2037    uspres    Oct    lastSun    2:00    1:00    PE
  503. Rule    Twilite    1988    2037    uspres    Nov    Sun>=7    2:00    0    S
  504. Rule    Twilite    1988    2037    nonpres    Oct    lastSun    2:00    0    S
  505.  
  506. # Zone    NAME        GMTOFF    RULES    FORMAT
  507. Zone    New-Pacific    -8:00    Twilite    P%sT
  508.  
  509. # Next really belongs in a separate file
  510.  
  511. Link    Eastern        localtime
  512. End of tzinfo
  513. exit
  514. --
  515.     UUCP: ..decvax!seismo!elsie!ado    ARPA: elsie!ado@seismo.ARPA
  516.     DEC, VAX and Elsie are Digital Equipment and Borden trademarks
  517.  
  518. Volume-Number: Volume 5, Number 57
  519.  
  520.