tz-rs

A pure Rust reimplementation of libc functions localtime, gmtime and mktime.

This crate allows to convert between a Unix timestamp and a calendar time expressed in the proleptic gregorian calendar with a provided time zone.

Time zones are provided to the library with a POSIX TZ string which can be read from the environment.

Two formats are currently accepted for the TZ string:

• std offset[dst[offset][,start[/time],end[/time]]] providing a time zone description,
• file or :file providing the path to a TZif file, which is absolute or relative to the system timezone directory.

See also the Linux manual page of tzset(3) and the glibc documentation of the TZ environment variable.

Context

Calls to libc localtime_r and other related functions from Rust are not safe in a multithreaded application, because they may internally set the TZ environment variable with the setenv function, which is not thread-safe.

See RUSTSEC-2020-0071 and RUSTSEC-2020-0159 for more information.

Documentation

Documentation is hosted on docs.rs.

Platform support

This crate is mainly intended for UNIX platforms.

Since the time zone database files are not included in this crate, non-UNIX users can download a copy of the database on the IANA site and compile the time zone database files to a local directory.

The database files can then be read by specifying an absolute path in the TZ string:

TimeZone::from_posix_tz(format!("{local_database_dir}/usr/share/zoneinfo/Pacific/Auckland"))?;

Note that the determination of the local time zone with this crate is not supported on non-UNIX platforms.

Alternatively, a crate like tzdb can be used, which statically provides existing time zone definitions for this crate, and supports finding the local time zone for all Tier 1 platforms.

Date time formatting (equivalent of libc strftime function)

This crate doesn't provide custom date time formatting support, but the custom-format crate can be used to provide custom format specifiers to the standard library formatting macros.

Compiler support

Requires rustc 1.81+.

License

This project is licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.