Skip to content

OPENSSL_gmtime

NAME

OPENSSL_gmtime, OPENSSL_gmtime_adj, OPENSSL_gmtime_diff, OPENSSL_timegm, OPENSSL_posix_to_tm, OPENSSL_tm_to_posix - platform-agnostic OpenSSL time routines

SYNOPSIS

#include <openssl/crypto.h>

struct tm *OPENSSL_gmtime(const time_t *timer, struct tm *result);
int OPENSSL_gmtime_adj(struct tm *tm, int offset_day, long offset_sec);
int OPENSSL_gmtime_diff(int *pday, int *psec,
                       const struct tm *from, const struct tm *to);

#include <openssl/posix_time.h>
int OPENSSL_timegm(const struct tm *tm, time_t *out_time);
int OPENSSL_posix_to_tm(int64_t time, struct tm *out_tm);
int OPENSSL_tm_to_posix(struct tm t_tm, int64_t *out);

DESCRIPTION

OPENSSL_gmtime() returns the Unix/Posix time specified by timer into the provided result argument. |timer| must be a value of the number of seconds relative to 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time, without including leap seconds, and must be in the range of the year 0 to 9999 inclusively. result will be zeroed, and only the fields tm_year, tm_mon, tm_mday, tm_hour, tm_min, and tm_sec will be updated in result on success.

OPENSSL_gmtime_adj() adds the offsets in offset_day and offset_sec to tm.

OPENSSL_gmtime_diff() calculates the difference between from and to.

OPENSSL_timegm() converts a time structure in UTC time in tm to a time_t value in out_time.

OPENSSL_posix_to_tm() converts a int64_t POSIX time value in time, to a broken out time value in tm. time must be a value of the number of seconds relative to 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time, without including leap seconds, and must be in the range of the year 0 to 9999 inclusively. tm will be zeroed, and only the fields tm_year, tm_mon, tm_mday, tm_hour, tm_min, and tm_sec will be updated in tm on success.

OPENSSL_tm_to_posix() converts a time value between the years 0 and 9999 in tm to a POSIX time value in out.

NOTES

These functions are intended for use when using struct tm values converted from ASN1_TIME values. They are not intended for general purpose time conversions, and should not be used for other purposes.

When these functions use a struct tm as input, they consider only the tm_year, tm_mon, tm_mday, tm_hour, tm_min, and tm_sec fields of the structure, all other fields are ignored. Out of range values, including leap seconds, are not permitted.

OPENSSL_gmtime_adj() converts tm into a days and seconds value, adds offset_day and offset_sec to the values, and then converts back into a struct tm specified by tm.

It is an error to call OPENSSL_gmtime() with result equal to NULL. The contents of the time_t given by timer are stored into the result. Calling with timer equal to NULL means use the current time.

OPENSSL_gmtime_adj() converts tm into a days and seconds value, adds the offsets, then converts back into a struct tm specified by tm.

OPENSSL_gmtime_diff() calculates the difference between the two struct tm structures from and to. The difference in days is placed into *pday, the remaining seconds are placed to *psec. The value in *psec will be less than the number of seconds per day (86400).

RETURN VALUES

OPENSSL_gmtime() returns result on success or NULL for failure. It can fail if the input time is outside of the range of year 0 to 9999.

OPENSSL_posix_to_tm() return 1 for success or 0 on failure. It can fail if the input time is outside of the range of year 0 to 9999.

OPENSSL_timegm() and OPENSSL_tm_to_posix() return 1 for success or 0 for failure. OpenSSL_timegm() can fail it the time is not representable in a time_t, and both may fail on invalid or out of range input in the input tm.

OPENSSL_gmtime_adj() and OPENSSL_gmtime_diff() return 0 on error, and 1 on success.

BUGS

OPENSSL_gmtime() and OPENSSL_timegm() are not platform-agnostic due to possible limitations in the range of the platform time_t type. OPENSSL_posix_to_tm() and OPENSSL_tm_to_posix() provide similar functionality in a platform independent manner.

HISTORY

OPENSSL_gmtime() returns NULL on error, or result on success.

OPENSSL_gmtime(), OPENSSL_gmtime_adj() and OPENSSL_gmtime_diff() have been in OpenSSL since 1.0.0. OPENSSL_timegm(), OPENSSL_posix_to_tm() and OPENSSL_tm_to_posix() were originally from BoringSSL and have been in OpenSSL since 4.0.0

Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.