mirror of https://github.com/mkerrisk/man-pages
201 lines
5.8 KiB
Plaintext
201 lines
5.8 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "LOCALTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" localtime
|
|
.SH NAME
|
|
localtime, localtime_r \- convert a time value to a broken-down local
|
|
time
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <time.h>
|
|
.br
|
|
.sp
|
|
struct tm *localtime(const time_t *\fP\fItimer\fP\fB);
|
|
.br
|
|
\fP
|
|
.LP
|
|
\fBstruct tm *localtime_r(const time_t *restrict\fP \fItimer\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ struct tm *restrict\fP \fIresult\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
For \fIlocaltime\fP(): The functionality described on this reference
|
|
page is aligned with the ISO\ C standard. Any
|
|
conflict between the requirements described here and the ISO\ C standard
|
|
is unintentional. This volume of
|
|
IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard.
|
|
.LP
|
|
The \fIlocaltime\fP() function shall convert the time in seconds since
|
|
the Epoch pointed to by \fItimer\fP into a broken-down
|
|
time, expressed as a local time. The function corrects for the timezone
|
|
and any seasonal time adjustments. \ Local timezone
|
|
information is used as though \fIlocaltime\fP() calls \fItzset\fP().
|
|
.LP
|
|
The relationship between a time in seconds since the Epoch used as
|
|
an argument to \fIlocaltime\fP() and the \fBtm\fP structure
|
|
(defined in the \fI<time.h>\fP header) is that the result shall be
|
|
as specified in the
|
|
expression given in the definition of seconds since the Epoch (see
|
|
the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
Section 4.14, Seconds Since the Epoch) corrected for timezone and
|
|
any seasonal
|
|
time adjustments, where the names in the structure and in the expression
|
|
correspond.
|
|
.LP
|
|
The same relationship shall apply for \fIlocaltime_r\fP().
|
|
.LP
|
|
The
|
|
\fIlocaltime\fP() function need not be reentrant. A function that
|
|
is not required to be reentrant is not required to be
|
|
thread-safe.
|
|
.LP
|
|
The \fIasctime\fP(), \fIctime\fP(), \fIgmtime\fP(), and \fIlocaltime\fP()
|
|
functions shall return values in one of two static objects:
|
|
a broken-down time structure and an array of type \fBchar\fP. Execution
|
|
of any of the functions may overwrite the information
|
|
returned in either of these objects by any of the other functions.
|
|
.LP
|
|
The \fIlocaltime_r\fP() function shall convert the time in seconds
|
|
since the Epoch pointed to by \fItimer\fP into a broken-down
|
|
time stored in the structure to which \fIresult\fP points. The \fIlocaltime_r\fP()
|
|
function shall also return a pointer to that
|
|
same structure.
|
|
.LP
|
|
Unlike \fIlocaltime\fP(), the reentrant version is not required to
|
|
set \fItzname\fP.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, the \fIlocaltime\fP() function shall return
|
|
a pointer to the broken-down time structure. If an
|
|
error is detected, \fIlocaltime\fP() shall return a null pointer
|
|
\ and set \fIerrno\fP to indicate the error.
|
|
.LP
|
|
Upon successful completion, \fIlocaltime_r\fP() shall return a pointer
|
|
to the structure pointed to by the argument \fIresult\fP.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIlocaltime\fP() function shall fail if:
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The result cannot be represented.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Getting the Local Date and Time
|
|
.LP
|
|
The following example uses the \fItime\fP() function to calculate
|
|
the time elapsed, in
|
|
seconds, since January 1, 1970 0:00 UTC (the Epoch), \fIlocaltime\fP()
|
|
to convert that value to a broken-down time, and \fIasctime\fP() to
|
|
convert the broken-down time values into a printable string.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stdio.h>
|
|
#include <time.h>
|
|
.sp
|
|
|
|
int main(void)
|
|
{
|
|
time_t result;
|
|
.sp
|
|
|
|
result = time(NULL);
|
|
printf("%s%ju secs since the Epoch\\n",
|
|
asctime(localtime(&result)),
|
|
(uintmax_t)result);
|
|
return(0);
|
|
}
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
This example writes the current time to \fIstdout\fP in a form like
|
|
this:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBWed Jun 26 10:32:15 1996
|
|
835810335 secs since the Epoch
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SS Getting the Modification Time for a File
|
|
.LP
|
|
The following example gets the modification time for a file. The \fIlocaltime\fP()
|
|
function converts the \fBtime_t\fP value of
|
|
the last modification date, obtained by a previous call to \fIstat\fP(),
|
|
into a \fBtm\fP
|
|
structure that contains the year, month, day, and so on.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <time.h>
|
|
\&...
|
|
struct stat statbuf;
|
|
\&...
|
|
tm = localtime(&statbuf.st_mtime);
|
|
\&...
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SS Timing an Event
|
|
.LP
|
|
The following example gets the current time, converts it to a string
|
|
using \fIlocaltime\fP() and \fIasctime\fP(), and prints it to standard
|
|
output using \fIfputs\fP(). It then prints the number of minutes to
|
|
an event being timed.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <time.h>
|
|
#include <stdio.h>
|
|
\&...
|
|
time_t now;
|
|
int minutes_to_event;
|
|
\&...
|
|
time(&now);
|
|
printf("The time is ");
|
|
fputs(asctime(localtime(&now)), stdout);
|
|
printf("There are still %d minutes to the event.\\n",
|
|
minutes_to_event);
|
|
\&...
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The \fIlocaltime_r\fP() function is thread-safe and returns values
|
|
in a user-supplied buffer instead of possibly using a static
|
|
data area that may be overwritten by each call.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIasctime\fP() , \fIclock\fP() , \fIctime\fP()
|
|
, \fIdifftime\fP() , \fIgetdate\fP() , \fIgmtime\fP() , \fImktime\fP()
|
|
, \fIstrftime\fP() , \fIstrptime\fP() , \fItime\fP() , \fIutime\fP()
|
|
, the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|