Update ASN1_TIME_to_tm's documentation

[openssl.git] / doc / man3 / ASN1_TIME_set.pod

diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index 457b7218d4ccb5d5464a0991067546e285555154..d71e4d1d56b970a36a041fd1d50d333698d94394 100644 (file)
--- a/doc/man3/ASN1_TIME_set.pod
+++ b/doc/man3/ASN1_TIME_set.pod
@@ -2,8 +2,9 @@
 
 =head1 NAME
 
-ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
-ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
+ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check,
+ASN1_TIME_set_string, ASN1_TIME_set_string_X509,
+ASN1_TIME_print, ASN1_TIME_to_tm, ASN1_TIME_diff - ASN.1 Time functions
 
 =head1 SYNOPSIS
 
@@ -11,8 +12,10 @@ ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
  ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
                           int offset_day, long offset_sec);
  int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
+ int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
  int ASN1_TIME_check(const ASN1_TIME *t);
  int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
+ int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);
 
  int ASN1_TIME_diff(int *pday, int *psec,
                     const ASN1_TIME *from, const ASN1_TIME *to);
@@ -32,7 +35,15 @@ and returned.
 
 ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time
 represented by string B<str> which must be in appropriate ASN.1 time
-format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
+format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL
+this function performs a format check on B<str> only.
+
+ASN1_TIME_set_string_X509() sets ASN1_TIME structure B<s> to the time
+represented by string B<str> which must be in appropriate time format
+that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and
+YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format
+are not allowed. If B<s> is NULL this function performs a format check
+on B<str> only.
 
 ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>.
 
@@ -42,6 +53,15 @@ format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
 structure has invalid format it prints out "Bad time value" and returns
 an error.
 
+ASN1_TIME_to_tm() converts the time B<s> to the standard B<tm> structure.
+If B<s> is NULL, then the current time is converted. The output time is GMT.
+The B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_wday>, B<tm_yday>,
+B<tm_mon> and B<tm_year> fields of B<tm> structure are set to proper values,
+whereas all other fields are set to 0. If B<tm> is NULL this function performs
+a format check on B<s> only. If B<s> is in Generalized format with franctional
+seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while
+converting B<s> to B<tm> structure.
+
 ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
 B<from> and B<to>. If B<to> represents a time later than B<from> then
 one or both (depending on the time difference) of B<*pday> and B<*psec>
@@ -85,9 +105,11 @@ Set a time structure to one hour after the current time and print it out:
 
  #include <time.h>
  #include <openssl/asn1.h>
+
  ASN1_TIME *tm;
  time_t t;
  BIO *b;
+
  t = time(NULL);
  tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
  b = BIO_new_fp(stdout, BIO_NOCLOSE);
@@ -100,22 +122,22 @@ Determine if one time is later or sooner than the current time:
  int day, sec;
 
  if (!ASN1_TIME_diff(&day, &sec, NULL, to))
-        /* Invalid time format */
+     /* Invalid time format */
 
  if (day > 0 || sec > 0)
-   printf("Later\n");
+     printf("Later\n");
  else if (day < 0 || sec < 0)
-   printf("Sooner\n");
+     printf("Sooner\n");
  else
-   printf("Same\n");
+     printf("Same\n");
 
 =head1 RETURN VALUES
 
 ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure
 or NULL if an error occurred.
 
-ASN1_TIME_set_string() returns 1 if the time value is successfully set and
-0 otherwise.
+ASN1_TIME_set_string() and ASN1_TIME_set_string_X509() return 1 if the time
+value is successfully set and 0 otherwise.
 
 ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0
 otherwise.
@@ -123,12 +145,20 @@ otherwise.
 ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if
 an error occurred (I/O error or invalid time format).
 
+ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an
+error occured (invalid time format).
+
 ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
 pass ASN1_TIME structure has invalid syntax for example.
 
+=head1 HISTORY
+
+The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.
+The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1.
+
 =head1 COPYRIGHT
 
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy