YouTipC Function Localtime
## C Library Function - `localtime()`
The `localtime()` function is a built-in function in the C standard library defined in the `` header file. It converts a calendar time value (of type `time_t`) into a broken-down time structure (`struct tm`), expressed relative to the user's local time zone.
---
## Declaration
The prototype for the `localtime()` function is as follows:
```c
struct tm *localtime(const time_t *timer);
```
### Parameters
* **`timer`**: A pointer to a `time_t` object that represents the calendar time (usually obtained by calling the `time()` function).
### Return Value
The function returns a pointer to a `struct tm` containing the broken-down time components adjusted for the local time zone.
If the conversion fails, the function returns `NULL`.
---
## The `struct tm` Structure
The returned pointer points to an internal static structure defined in ``. The fields of `struct tm` are defined as follows:
```c
struct tm {
int tm_sec; /* Seconds: range 0 to 59 (can be up to 60 to allow for leap seconds) */
int tm_min; /* Minutes: range 0 to 59 */
int tm_hour; /* Hours: range 0 to 23 */
int tm_mday; /* Day of the month: range 1 to 31 */
int tm_mon; /* Month: range 0 to 11 (0 = January, 11 = December) */
int tm_year; /* Year: Number of years since 1900 */
int tm_wday; /* Day of the week: range 0 to 6 (0 = Sunday, 6 = Saturday) */
int tm_yday; /* Day of the year: range 0 to 365 */
int tm_isdst; /* Daylight Saving Time flag:
> 0 if DST is in effect;
0 if DST is not in effect;
< 0 if information is unavailable */
};
```
---
## Code Example
The following example demonstrates how to use `localtime()` to retrieve, format, and print the current local date and time.
```c
#include
#include
int main()
{
time_t rawtime;
struct tm *info;
// Get the current calendar time
time(&rawtime);
// Convert the calendar time to local broken-down time
info = localtime(&rawtime);
// Print the formatted local time and date using asctime()
printf("Current local time and date: %s", asctime(info));
return 0;
}
```
### Output
When you compile and run the program, it will produce an output similar to the following:
```text
Current local time and date: Thu Aug 23 09:12:05 2012
```
---
## Important Considerations
### 1. Thread Safety and Shared Buffer
The `localtime()` function returns a pointer to a **statically allocated** `struct tm` shared by other time functions (such as `gmtime()` and `asctime()`).
* Subsequent calls to `localtime()` or other time-conversion functions will overwrite the contents of this shared structure.
* If you need to preserve the returned time values, you should copy the structure to a local variable:
```c
struct tm local_copy = *localtime(&rawtime);
```
* In multi-threaded programs, using `localtime()` can lead to race conditions. For thread-safe operations, use POSIX's `localtime_r()` or C11's `localtime_s()` (depending on your platform).
### 2. Year and Month Offsets
When extracting values manually from `struct tm`, remember the following offsets:
* **`tm_year`** represents the number of years **since 1900**. To get the actual calendar year, you must add `1900` (e.g., `info->tm_year + 1900`).
* **`tm_mon`** is 0-indexed (0 for January, 11 for December). To display the month as a standard 1-12 value, you must add `1` (e.g., `info->tm_mon + 1`).