localtime(), localtime64() — Convert time and correct for local time

Standards

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);

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

1. 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.
   The time zone external variables tzname, timezone, and daylight declarations remain feature test protected in time.h.
2. 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.
3. In POSIX you can supply the necessary information by using environment variables.
4. In non-POSIX applications, you can supply customized locale information by setting time zone and daylight information in LC_TOD.
5. By customizing the locale, you allow the time functions to preserve both time and date, correctly adjusting for daylight time on a given date.
6. 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.
7. Calendar time returned by the time() function begins at the epoch, which was at 00:00:00 Coordinated Universal Time (UTC), January 1, 1970.
8. 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 for a description of the fields of the tm structure.

Error Code

Description

EOVERFLOW

The result cannot be represented.

Example

⁄* 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(&ltime);                                                                
   newtime = localtime(&ltime);                                                 
   printf("The date and time is %s", asctime(newtime));                         
}                                                                               

Output

The date and time is Fri Jun 16 15:00:00 2001

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
• time.h
• 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