boruch-baum / zdump-3- Goto Github PK

README
======
zdump3.c       - function for timezone and daylight savings info
zdump3.h       - header file
zdump.3        - man page for zdump3.c
zdtest.c       - command line program to test zdump(3)
tzif-display.c - command line program to view zoneinfo file data

create_locales.sh - compile and archive a selection of locales
locale_test.sh    - run an arbitrary command in many locales


SUMMARY
=======
This collection is presented, as a FOSS/GPL3+ project, to help
programmers work with timezone data and daylight savings time
transition information over multiple locales and timespans.


CONTENTS
========
1.0 DESCRIPTION OF THE FUNCTIONS
1.1    zdump3
1.2    zdtest
1.3    tzif-display
1.4    create_locales.sh
1.5    locale_test.sh
1.6    zdump.3
2.0 BUILD INSTRUCTIONS
2.1    zdump3
2.2    zdtest
2.3    tzif-display
2.4    create_locales.sh
2.5    locale_test.sh
2.6    zdump.3
3.0 CONTACT AUTHOR


================================
1.0 DESCRIPTION OF THE FUNCTIONS
================================


1.1    zdump3
=============
The zdump function interprets a system TZif file ( see man 5 tzfile ) for
the timezone 'tzname', and returns that file's timezone and daylight-
savings-time transition information for the time_t interval 'start' to
'end'. The data type time_t, often described in man pages as 'calendar
time', is an integer value (not an int data type) representing the number
of seconds elapsed since the "Epoch", 1970-01-01 00:00:00 +0000 (UTC).

Upon success, the function returns a 0, sets the variable *return_data
to point to a malloc()ed array of type 'zdumpinfo (see below), containing
the data found, and sets the int variable pointed to by *num_entries to
the number of elements in the zdumpinfo array. The caller must free() the
*return_data pointer.

Upon failure, the function returns a non-zero error code, sets the
variable *return_data to NULL, and sets the int variable pointed to by
*num_entries to 0.

The zdumpinfo structure contains fields for: the number of seconds
since the "Epoch" at which the information in this array element takes
effect; the time difference, in seconds, from UTC; the absolute value
of the number of seconds that the utc_offset is at variance from the
timezone's "standard time", and; a NUL-terminated character string of
the abbreviation for this variation of the timezone (eg. EST
or EDT for the timezone America/New_York).

More information is available in the included man page, zdump.3.


1.2    zdtest
=============
The zdtest program is a command line front-end to zdump.
SYNOPSIS: zdtest zonespec time_t time_t
EXAMPLE:  zdtest Europe/Paris 1293858000 1388552400
equivalent to:
          zdtest Europe/Paris \
                 $(date --date='2011-01-01 00:00:00' +%s) \
                 $(date --date='2014-01-01 00:00:00' +%s)
NOTE:     The date commands above were run in TZ=America/New_York.
OUTPUT:
number of entries found = 8
for zone: Europe/Paris, for time_t 1293858000 to 1388552400
num:   time_t      utc_offset  save_secs abbr  - local time (derived) -
 0:  1293858000       3600          0    CET    Sat Jan  1 06:00:00 2011
 1:  1301187600       7200       3600    CEST   Sun Mar 27 03:00:00 2011
 2:  1319936400       3600          0    CET    Sun Oct 30 02:00:00 2011
 3:  1332637200       7200       3600    CEST   Sun Mar 25 03:00:00 2012
 4:  1351386000       3600          0    CET    Sun Oct 28 02:00:00 2012
 5:  1364691600       7200       3600    CEST   Sun Mar 31 03:00:00 2013
 6:  1382835600       3600          0    CET    Sun Oct 27 02:00:00 2013
 7:  1396141200       7200       3600    CEST   Sun Mar 30 03:00:00 2014


1.3    tzif-display
===================
The tzif-display program is a simple presenter of the contents
of a zoneinfo file, in a human-readable format. The output is often
long, so it is recommended to pipe the output to 'less' or to some
other sensible pager.
SYNOPSIS: tzif-display /path/to/filename


1.4    create_locales.sh
========================
This shell script is not directly related to timezones. It is included
to help demonstrate the lack of localization of timezone information
in the zoneinfo database and in GNU/Linux.

This script is meant to be run with administrator privileges. It
compiles and archives a collection of sixteen locale definitions,
representing different languages, character sets, unicode character
lengths, and text direction.


1.5    locale_test.sh
=====================
This shell script is not directly related to timezones. It is included
to help demonstrate the lack of localization of timezone information
in the zoneinfo database and in GNU/Linux.

This script executes an arbitrary command in each of sixteen locales,
not coincidentally those created by the create_locales.sh script above.

Try: locale_test.sh date +%A%t%B%t%z%t%Z

Note how all information is localized, except for the timezone.


1.6    zdump.3
==============
This is the source file for the zdump3 man page.


======================
2.0 BUILD INSTRUCTIONS
======================


2.1    zdump3
=============
Compile:  gcc -c -Wall -Werror -fPIC zdump3.c
Build:    gcc -shared -o libzdump3.so zdump3.o
Run:      The man page zdump.3 includes a sample progran, and
          the file zdtest.c is also a sample program.

2.2    zdtest
=============
Pre-requisite: build zdump3 (section 2.1, above)
Compile: (presumes zdump3.h in current directory)
         gcc -c -I./ -Wall -Werror -g zdtest.c
Build:   (presumes zdump3 built in current directory)
         gcc -I./ -L./ -Wall zdtest.c -o zdtest -lzdump3
Run: (option 1)
         export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
         ./zdtest zonespec start_time end_time
Run: (option 2)
         env LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH \
         ./zdtest zonespec start_time end_time


2.3    tzif-display
===================
Compile: gcc -c -Wall -Werror -g tzif-display.c
Build:   gcc -Wall tzif-display.c -o tzif-display
Run:     ./tzif-display /full/pathname/to/tzif-file


2.4    create_locales.sh
========================
Mark as executable. On typical systems, this script will have to run
with administrator privileges.


2.5    locale_test.sh
=====================
mark as executable.


2.6    zdump.3
==============
Compile: nroff -man zdump.3
Run:     nroff -man zdump.3 |less


==================
3.0 CONTACT AUTHOR
==================
Boruch Baum <[email protected]>