Namespaces
Variants
Views
Actions

Difference between revisions of "c/chrono/localtime"

From cppreference.com
< c‎ | chrono
m (fmt)
 
(5 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
{{c/title| localtime | localtime_r | localtime_s}}
+
{{c/title|localtime|localtime_r|localtime_s}}
 
{{c/chrono/navbar}}
 
{{c/chrono/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | time.h }}  
+
{{dcl header|time.h}}
−
{{dcl | num=1 |
+
{{dcl|num=1|
−
struct tm *localtime  ( const time_t *timer );
+
struct tm* localtime  ( const time_t* timer );
 
}}
 
}}
−
{{dcl | num=2 | since=c23 |
+
{{dcl|num=2|since=c23|
−
struct tm *localtime_r( const time_t *timer, struct tm *buf );
+
struct tm* localtime_r( const time_t* timer, struct tm* buf );
 
}}
 
}}
−
{{dcl | num=3 | since=c11 |
+
{{dcl|num=3|since=c11|
−
errno_t localtime_s( const time_t *restrict timer, struct tm *restrict buf );
+
struct tm* localtime_s( const time_t* restrict timer, struct tm* restrict buf );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
@1@ Converts given time since epoch (a {{lc|time_t}} value pointed to by {{tt|timer}}) into calendar time, expressed in local time, in the {{rlpt|tm|struct tm}} format. The result is stored in static storage and a pointer to that static storage is returned.
+
@1@ Converts given time since epoch (a {{lc|time_t}} value pointed to by {{c|timer}}) into calendar time, expressed in local time, in the {{rlpt|tm|struct tm}} format. The result is stored in static storage and a pointer to that static storage is returned.
−
@2@ Same as {{v|1}}, except that the function uses user-provided storage {{tt|buf}} for the result.
+
@2@ Same as {{v|1}}, except that the function uses user-provided storage {{c|buf}} for the result.
−
@3@ Same as {{v|1}}, except that the function uses user-provided storage {{tt|buf}} for the result and that the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
+
@3@ Same as {{v|1}}, except that the function uses user-provided storage {{c|buf}} for the result and that the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
−
:* {{tt|timer}} or {{tt|buf}} is a null pointer
+
:* {{c|timer}} or {{c|buf}} is a null pointer
 
:{{c/ext1 availability|localtime_s}}
 
:{{c/ext1 availability|localtime_s}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | timer | pointer to a {{tt|time_t}} object to convert}}
+
{{par|timer|pointer to a {{lc|time_t}} object to convert}}
−
{{par | buf | pointer to a {{tt|struct tm}} object to store the result}}
+
{{par|buf|pointer to a {{c|struct tm}} object to store the result}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
 
@1@ pointer to a static internal {{lc|tm}} object on success, or null pointer otherwise. The structure may be shared between {{lc|gmtime}}, {{tt|localtime}}, and {{lc|ctime}} and may be overwritten on each invocation.
 
@1@ pointer to a static internal {{lc|tm}} object on success, or null pointer otherwise. The structure may be shared between {{lc|gmtime}}, {{tt|localtime}}, and {{lc|ctime}} and may be overwritten on each invocation.
−
@2-3@ copy of the {{tt|buf}} pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to local calendar time)
+
@2,3@ copy of the {{c|buf}} pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to local calendar time).
  
 
===Notes===
 
===Notes===
−
This function {{tt|localtime}} may not be thread-safe.
+
The function {{tt|localtime}} may not be thread-safe.
  
 
POSIX requires that {{tt|localtime}} and {{tt|localtime_r}} set {{lc|errno}} to {{lc|EOVERFLOW}} if it fails because the argument is too large.
 
POSIX requires that {{tt|localtime}} and {{tt|localtime_r}} set {{lc|errno}} to {{lc|EOVERFLOW}} if it fails because the argument is too large.
  
−
[http://pubs.opengroup.org/onlinepubs/9699919799/functions/localtime.html POSIX specifies] that the timezone information is determined by {{tt|localtime}} and {{tt|localtime_r}} as if by calling [http://pubs.opengroup.org/onlinepubs/9699919799/functions/tzset.html tzset], which reads the environment variable {{c|TZ}}.
+
[https://pubs.opengroup.org/onlinepubs/9699919799/functions/localtime.html POSIX specifies] that the timezone information is determined by {{tt|localtime}} and {{tt|localtime_r}} as if by calling [https://pubs.opengroup.org/onlinepubs/9699919799/functions/tzset.html {{tt|tzset}}], which reads the environment variable {{c|TZ}}.
  
−
The implementation of {{tt|localtime_s}} in [https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s?view=vs-2019 Microsoft CRT] is incompatible with the C standard since it has reversed parameter order and returns {{tt|errno_t}}.
+
The implementation of {{tt|localtime_s}} in [https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s?view=vs-2019 Microsoft CRT] is incompatible with the C standard since it has reversed parameter order and returns {{lc|errno_t}}.
  
 
===Example===
 
===Example===
Line 43: Line 43:
  
 
===References===
 
===References===
 +
{{ref std c23}}
 +
{{ref std|section=7.27.3.4|title=The localtime function|p=TBD}}
 +
{{ref std|section=K.3.8.2.4|title=The localtime_s function|p=TBD}}
 +
{{ref std end}}
 
{{ref std c17}}
 
{{ref std c17}}
−
{{ref std | section=7.27.3.4 | title=The localtime function | p=288}}
+
{{ref std|section=7.27.3.4|title=The localtime function|p=288}}
−
{{ref std | section=K.3.8.2.4 | title=The localtime_s function | p=455}}
+
{{ref std|section=K.3.8.2.4|title=The localtime_s function|p=455}}
 
{{ref std end}}
 
{{ref std end}}
 
{{ref std c11}}
 
{{ref std c11}}
−
{{ref std | section=7.27.3.4 | title=The localtime function | p=394}}
+
{{ref std|section=7.27.3.4|title=The localtime function|p=394}}
−
{{ref std | section=K.3.8.2.4 | title=The localtime_s function | p=627}}
+
{{ref std|section=K.3.8.2.4|title=The localtime_s function|p=627}}
 
{{ref std end}}
 
{{ref std end}}
 
{{ref std c99}}
 
{{ref std c99}}
−
{{ref std | section=7.23.3.4 | title=The localtime function | p=343}}
+
{{ref std|section=7.23.3.4|title=The localtime function|p=343}}
 
{{ref std end}}
 
{{ref std end}}
 
{{ref std c89}}
 
{{ref std c89}}
−
{{ref std | section=4.12.3.4 | title=The localtime function}}
+
{{ref std|section=4.12.3.4|title=The localtime function}}
 
{{ref std end}}
 
{{ref std end}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | c/chrono/dsc gmtime}}
+
{{dsc inc|c/chrono/dsc gmtime}}
−
{{dsc see cpp | cpp/chrono/c/localtime}}
+
{{dsc see cpp|cpp/chrono/c/localtime}}
 
{{dsc end}}
 
{{dsc end}}
  
 
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}
 
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}

Latest revision as of 06:22, 7 June 2024

 
C
 
Date and time utilities
Functions
Time manipulation
(C11)
(C23)
Format conversions
(deprecated in C23)(C11)
(deprecated in C23)(C11)
(C95)
(C23)(C11)
localtimelocaltime_rlocaltime_s
(C23)(C11)
Constants
Types
(C11)
 
Defined in header <time.h>
struct tm* localtime  ( const time_t* timer );
 (1)
struct tm* localtime_r( const time_t* timer, struct tm* buf );
 (2) (since C23)
struct tm* localtime_s( const time_t* restrict timer, struct tm* restrict buf );
 (3) (since C11)
1) Converts given time since epoch (a time_t value pointed to by timer) into calendar time, expressed in local time, in the struct tm format. The result is stored in static storage and a pointer to that static storage is returned.
2) Same as (1), except that the function uses user-provided storage buf for the result.
3) Same as (1), except that the function uses user-provided storage buf for the result and that the following errors are detected at runtime and call the currently installed constraint handler function:
  • timer or buf is a null pointer
As with all bounds-checked functions, localtime_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <time.h>.

Contents

[edit] Parameters

timer - pointer to a time_t object to convert
buf - pointer to a struct tm object to store the result

[edit] Return value

1) pointer to a static internal tm object on success, or null pointer otherwise. The structure may be shared between gmtime, localtime, and ctime and may be overwritten on each invocation.
2,3) copy of the buf pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to local calendar time).

[edit] Notes

The function localtime may not be thread-safe.

POSIX requires that localtime and localtime_r set errno to EOVERFLOW if it fails because the argument is too large.

POSIX specifies that the timezone information is determined by localtime and localtime_r as if by calling tzset, which reads the environment variable TZ.

The implementation of localtime_s in Microsoft CRT is incompatible with the C standard since it has reversed parameter order and returns errno_t.

[edit] Example

Run this code
#define __STDC_WANT_LIB_EXT1__ 1
#define _XOPEN_SOURCE // for putenv
#include <stdio.h>
#include <stdlib.h>   // for putenv
#include <time.h>
 
int main(void)
{
    time_t t = time(NULL);
    printf("UTC:       %s", asctime(gmtime(&t)));
    printf("local:     %s", asctime(localtime(&t)));
    // POSIX-specific
    putenv("TZ=Asia/Singapore");
    printf("Singapore: %s", asctime(localtime(&t)));
 
#ifdef __STDC_LIB_EXT1__
    struct tm buf;
    char str[26];
    asctime_s(str, sizeof str, gmtime_s(&t, &buf));
    printf("UTC:       %s", str);
    asctime_s(str, sizeof str, localtime_s(&t, &buf));
    printf("local:     %s", str);
#endif
}

Possible output: 

UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017
Singapore: Fri Sep 15 22:22:05 2017
UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017

[edit] References

  • C23 standard (ISO/IEC 9899:2024):
  • 7.27.3.4 The localtime function (p: TBD)
  • K.3.8.2.4 The localtime_s function (p: TBD)
  • C17 standard (ISO/IEC 9899:2018):
  • 7.27.3.4 The localtime function (p: 288)
  • K.3.8.2.4 The localtime_s function (p: 455)
  • C11 standard (ISO/IEC 9899:2011):
  • 7.27.3.4 The localtime function (p: 394)
  • K.3.8.2.4 The localtime_s function (p: 627)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.23.3.4 The localtime function (p: 343)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.12.3.4 The localtime function

[edit] See also

(C23)(C11)
 converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC)
(function) [edit]
C++ documentation for localtime
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=c/chrono/localtime&oldid=172291"