localtime, localtime_r, localtime_s

From cppreference.com

Compiler support
Language
Headers
Type support
Program utilities
Variadic function support
Error handling
Dynamic memory management
Strings library
Algorithms
Numerics
Date and time utilities
Input/output support
Localization support
Concurrency support(C11)
Technical Specifications
Symbol index

[edit]

Date and time utilities

Functions
Time manipulation
difftime
time
clock
timespec_get (C11)
timespec_getres (C23)
Format conversions
asctimeasctime_s (deprecated in C23)(C11)
ctimectime_s (deprecated in C23)(C11)
strftime
wcsftime (C95)
gmtimegmtime_rgmtime_s (C23)(C11)
localtimelocaltime_rlocaltime_s (C23)(C11)
mktime
Constants
CLOCKS_PER_SEC
Types
tm
time_t
clock_t
timespec (C11)

[edit]

Defined in header`<time.h>`
structtm* localtime (consttime_t* timer);	(1)
structtm* localtime_r(consttime_t* timer,structtm* buf);	(2)	(since C23)
structtm* localtime_s(consttime_trestrict timer,structtmrestrict buf);	(3)	(since C11)

1) Converts given time since epoch (atime_t value pointed to bytimer) into calendar time, expressed in local time, in thestruct 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 storagebuf for the result.

3) Same as(1), except that the function uses user-provided storagebuf for the result and that the following errors are detected at runtime and call the currently installedconstraint handler function:

timer orbuf 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 constant1 before including<time.h>.

[edit]Parameters

timer	-	pointer to atime_t object to convert
buf	-	pointer to astructtm object to store the result

[edit]Return value

1) pointer to a static internaltm object on success, or null pointer otherwise. The structure may be shared betweengmtime,localtime, andctime and may be overwritten on each invocation.

2,3) copy of thebuf 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 functionlocaltime may not be thread-safe. TheMicrosoft CRT implementation is thread-safe.

POSIX requires thatlocaltime andlocaltime_r seterrno toEOVERFLOW if it fails because the argument is too large.

POSIX specifies that the timezone information is determined bylocaltime andlocaltime_r as if by callingtzset, which reads the environment variableTZ.

The implementation oflocaltime_s inMicrosoft CRT is incompatible with the C standard since it has reversed parameter order and returnserrno_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__structtm 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 2017local:     Fri Sep 15 14:22:05 2017Singapore: Fri Sep 15 22:22:05 2017UTC:       Fri Sep 15 14:22:05 2017local:     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

gmtimegmtime_rgmtime_s (C23)(C11)	converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) (function)[edit]
C++ documentation forlocaltime