Add documentation for the OPENSSL_gmtime functions

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19257)

diff --git a/doc/build.info b/doc/build.info
index 068082df32524b77f2ea5bcc7c9b2156aeeb475a..809ffee95bb7b0edc52c7055e6aeb5cd05c66302 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -1503,6 +1503,10 @@ DEPEND[html/man3/OPENSSL_fork_prepare.html]=man3/OPENSSL_fork_prepare.pod
 GENERATE[html/man3/OPENSSL_fork_prepare.html]=man3/OPENSSL_fork_prepare.pod
 DEPEND[man/man3/OPENSSL_fork_prepare.3]=man3/OPENSSL_fork_prepare.pod
 GENERATE[man/man3/OPENSSL_fork_prepare.3]=man3/OPENSSL_fork_prepare.pod
+DEPEND[html/man3/OPENSSL_gmtime.html]=man3/OPENSSL_gmtime.pod
+GENERATE[html/man3/OPENSSL_gmtime.html]=man3/OPENSSL_gmtime.pod
+DEPEND[man/man3/OPENSSL_gmtime.3]=man3/OPENSSL_gmtime.pod
+GENERATE[man/man3/OPENSSL_gmtime.3]=man3/OPENSSL_gmtime.pod
 DEPEND[html/man3/OPENSSL_hexchar2int.html]=man3/OPENSSL_hexchar2int.pod
 GENERATE[html/man3/OPENSSL_hexchar2int.html]=man3/OPENSSL_hexchar2int.pod
 DEPEND[man/man3/OPENSSL_hexchar2int.3]=man3/OPENSSL_hexchar2int.pod
@@ -3135,6 +3139,7 @@ html/man3/OPENSSL_LH_COMPFUNC.html \
 html/man3/OPENSSL_LH_stats.html \
 html/man3/OPENSSL_config.html \
 html/man3/OPENSSL_fork_prepare.html \
+html/man3/OPENSSL_gmtime.html \
 html/man3/OPENSSL_hexchar2int.html \
 html/man3/OPENSSL_ia32cap.html \
 html/man3/OPENSSL_init_crypto.html \
@@ -3737,6 +3742,7 @@ man/man3/OPENSSL_LH_COMPFUNC.3 \
 man/man3/OPENSSL_LH_stats.3 \
 man/man3/OPENSSL_config.3 \
 man/man3/OPENSSL_fork_prepare.3 \
+man/man3/OPENSSL_gmtime.3 \
 man/man3/OPENSSL_hexchar2int.3 \
 man/man3/OPENSSL_ia32cap.3 \
 man/man3/OPENSSL_init_crypto.3 \

diff --git a/doc/man3/OPENSSL_gmtime.pod b/doc/man3/OPENSSL_gmtime.pod
new file mode 100644 (file)
index 0000000..b86557f
--- /dev/null
+++ b/doc/man3/OPENSSL_gmtime.pod
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_gmtime,
+OPENSSL_gmtime_adj,
+OPENSSL_gmtime_diff - platform-agnostic OpenSSL time routines
+
+=head1 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);
+
+=head1 DESCRIPTION
+
+OPENSSL_gmtime() returns the UTC time specified by I<timer> into the provided
+I<result> argument.
+
+OPENSSL_gmtime_adj() adds the offsets in I<offset_day> and I<offset_sec> to I<tm>.
+
+OPENSSL_gmtime_diff() calculates the difference between I<from> and I<to>.
+
+=head1 NOTES
+
+It is an error to call OPENSSL_gmtime() with I<result> equal to NULL. The
+contents of the time_t given by I<timer> are stored into the I<result>. Calling
+with I<timer> equal to NULL means use the current time.
+
+OPENSSL_gmtime_adj() converts I<tm> into a days and seconds value, adds the
+offsets, then converts back into a I<struct tm> specified by I<tm>. Leap seconds
+are not considered.
+
+OPENSSL_gmtime_diff() calculates the difference between the two I<struct tm>
+structures I<from> and I<to>. The difference in days is placed into I<*pday>,
+the remaining seconds are placed to I<*psec>. The value in I<*psec> will be less
+than the number of seconds per day (3600). Leap seconds are not considered.
+
+=head1 RETURN VALUES
+
+OPENSSL_gmtime() returns NULL on error, or I<result> on success.
+
+OPENSSL_gmtime_adj() and OPENSSL_gmtime_diff() return 0 on error, and 1 on success.
+
+=head1 HISTORY
+
+OPENSSL_gmtime(), OPENSSL_gmtime_adj() and OPENSSL_gmtime_diff() have been
+in OpenSSL since 1.0.0.
+
+=head1 COPYRIGHT
+
+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
+L<https://www.openssl.org/source/license.html>.
+
+=cut

diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 3cadb3277d386b422c8c693c08d80b917d13ee8e..be292c1b516fce729c452e2ab3872057606527c4 100644 (file)
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -808,9 +808,6 @@ OPENSSL_LH_set_down_load(3)
 OPENSSL_LH_strhash(3)
 OPENSSL_asc2uni(3)
 OPENSSL_die(3)
-OPENSSL_gmtime(3)
-OPENSSL_gmtime_adj(3)
-OPENSSL_gmtime_diff(3)
 OPENSSL_init(3)
 OPENSSL_isservice(3)
 OPENSSL_issetugid(3)