localtime(), localtime64() — Convert time and correct for local time
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
ISO C
POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 Language Environment® |
both |
Format
#include <time.h>
struct tm *localtime(const time_t *timeval);
#define _LARGE_TIME_API
#include <time.h>
struct tm *localtime64(const time64_t *timeval);
Compile requirement: Use of localtime64() function requires the long
long data type. See z/OS XL C/C++ Language Reference for information on how to make long long available.
General description
The localtime() funtion converts the calendar time pointed to by timeval to a broken-down time expressed in local time. Calendar time is usually obtained by a call to the time() function.
The localtime64() function behaves exactly like localtime() except it will break down a time64_t value pointing to a calendar time beyond 03:14:07 UTC on January 19, 2038 with a limit of 23:59:59 UTC on December 31, 9999.
Usage notes
- This function is sensitive to time zone information which is provided
by:
- The TZ environmental variable when POSIX(ON) and TZ is correctly defined, or by the _TZ environmental variable when POSIX(OFF) and _TZ is correctly defined.
- The LC_TOD category of the current locale if POSIX(OFF) or TZ is not defined.
tzname
,timezone
, anddaylight
declarations remain feature test protected in time.h. - The ctime(), localtime(), and mktime() functions now return Coordinated Universal Time (UTC) unless
customized locale information is made available, which includes setting
the
timezone_name
variable. - In POSIX you can supply the necessary information by using environment variables.
- In non-POSIX applications, you can supply customized locale information by setting time zone and daylight information in LC_TOD.
- By customizing the locale, you allow the time functions to preserve both time and date, correctly adjusting for daylight time on a given date.
- The gmtime() and localtime() functions may use a common, statically allocated structure for the conversion. Each call to one of these functions will alter the result of the previous call.
- Calendar time returned by the time() function begins at the epoch, which was at 00:00:00 Coordinated Universal Time (UTC), January 1, 1970.
- The localtime() function converts calendar time (that is, seconds
elapsed since the epoch) to broken-down time, expressed as local time, using
time zone information provided by the TZ or _TZ environment variable
or the LC_TOD category of the current locale:
- When neither TZ nor _TZ is defined, the current locale is interrogated for time zone information. If neither TZ nor _TZ is defined and LC_TOD time zone information is not present in the current locale, a default value is applied to local time. POSIX programs simply default to Coordinated Universal Time (UTC), while non-POSIX programs establish an offset from UTC based on the setting of the system clock. For more information about customizing a time zone to work with local time, see “Customizing a time zone” in z/OS XL C/C++ Programming Guide.
Returned value
Returns a pointer to a tm structure containing the broken-down time, expressed as a local time, and corresponding to the calendar time pointed to by timeval. If the calendar time cannot be converted, localtime() returns a NULL pointer. See time.h — Time and date for a description of the fields of the tm structure.
- Error Code
- Description
- EOVERFLOW
- The result cannot be represented.
Example
CELEBL07
/* CELEBL07
This example queries the system clock and displays the local time.
*/
#include <time.h>
#include <stdio.h>
int main(void)
{
struct tm *newtime;
time_t ltime;
time(<ime);
newtime = localtime(<ime);
printf("The date and time is %s", asctime(newtime));
}
Output
This output would occur if
the local time is 3:00 p.m. June 16, 2006):
The date and time is Fri Jun 16 15:00:00 2006
Related information
- See the topic about internationalization of locales and character sets in z/OS XL C/C++ Programming Guide for a description of LC_TOD, which is a nonstandard, z/OS® XL C/C++ proprietary locale category.
- locale.h — Locale settings
- time.h — Time and date
- asctime(), asctime64() — Convert time to character string
- asctime_r(), asctime64_r() — Convert date and time to a character string
- ctime(), ctime64() — Convert time to character string
- ctime_r(), ctime64_r() — Convert time value to date and time character string
- gmtime(), gmtime64() — Convert time to broken-down UTC time
- gmtime_r(), gmtime64_r() — Convert a time value to broken-down UTC time
- localdtconv() — Date and time formatting convention inquiry
- localtime_r(), localtime64_r() — Convert time value to broken-down local time
- mktime(), mktime64() — Convert local time
- strftime() — Convert to formatted time
- time(),time64() — Determine current UTC time
- tzset() — Set the time zone