mirror of https://github.com/mkerrisk/man-pages
115 lines
3.9 KiB
Plaintext
115 lines
3.9 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GMTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" gmtime
|
|
.SH NAME
|
|
gmtime, gmtime_r \- convert a time value to a broken-down UTC time
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <time.h>
|
|
.br
|
|
.sp
|
|
struct tm *gmtime(const time_t *\fP\fItimer\fP\fB);
|
|
.br
|
|
\fP
|
|
.LP
|
|
\fBstruct tm *gmtime_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 \fIgmtime\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 \fIgmtime\fP() function shall convert the time in seconds since
|
|
the Epoch pointed to by \fItimer\fP into a broken-down
|
|
time, expressed as Coordinated Universal Time (UTC).
|
|
.LP
|
|
The
|
|
relationship between a time in seconds since the Epoch used as an
|
|
argument to \fIgmtime\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), where the names in the structure
|
|
and in
|
|
the expression correspond.
|
|
.LP
|
|
The same relationship shall apply for \fIgmtime_r\fP().
|
|
.LP
|
|
The
|
|
\fIgmtime\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 \fIgmtime_r\fP() function shall convert the time in seconds since
|
|
the Epoch pointed to by \fItimer\fP into a broken-down time
|
|
expressed as Coordinated Universal Time (UTC). The broken-down time
|
|
is stored in the structure referred to by \fIresult\fP. The
|
|
\fIgmtime_r\fP() function shall also return the address of the same
|
|
structure.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, the \fIgmtime\fP() function shall return
|
|
a pointer to a \fBstruct tm\fP. If an error is detected,
|
|
\fIgmtime\fP() shall return a null pointer \ and set \fIerrno\fP
|
|
to indicate the error.
|
|
.LP
|
|
Upon successful completion, \fIgmtime_r\fP() shall return the address
|
|
of the structure pointed to by the argument \fIresult\fP.
|
|
If an error is detected, \fIgmtime_r\fP() shall return a null pointer.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIgmtime\fP() function shall fail if:
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The result cannot be represented.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The \fIgmtime_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() , \fIlocaltime\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 .
|