man3p/gmtime.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "GMTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" gmtime
   4 .SH NAME
   5 gmtime, gmtime_r \- convert a time value to a broken-down UTC time
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <time.h>
   9 .br
  10 .sp
  11 struct tm *gmtime(const time_t *\fP\fItimer\fP\fB);
  12 .br
  13 \fP
  14 .LP
  15 \fBstruct tm *gmtime_r(const time_t *restrict\fP \fItimer\fP\fB,
  16 .br
  17 \ \ \ \ \ \  struct tm *restrict\fP \fIresult\fP\fB); \fP
  18 \fB
  19 .br
  20 \fP
  21 .SH DESCRIPTION
  22 .LP
  23 For \fIgmtime\fP():   The functionality described on this reference
  24 page is aligned with the ISO\ C standard. Any
  25 conflict between the requirements described here and the ISO\ C standard
  26 is unintentional. This volume of
  27 IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard.
  28 .LP
  29 The \fIgmtime\fP() function shall convert the time in seconds since
  30 the Epoch pointed to by \fItimer\fP into a broken-down
  31 time, expressed as Coordinated Universal Time (UTC).
  32 .LP
  33 The
  34 relationship between a time in seconds since the Epoch used as an
  35 argument to \fIgmtime\fP() and the \fBtm\fP structure (defined
  36 in the \fI<time.h>\fP header) is that the result shall be as specified
  37 in the
  38 expression given in the definition of seconds since the Epoch (see
  39 the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
  40 Section 4.14, Seconds Since the Epoch), where the names in the structure
  41 and in
  42 the expression correspond.
  43 .LP
  44 The same relationship shall apply for \fIgmtime_r\fP().
  45 .LP
  46 The
  47 \fIgmtime\fP() function need not be reentrant. A function that is
  48 not required to be reentrant is not required to be
  49 thread-safe.
  50 .LP
  51 The \fIasctime\fP(), \fIctime\fP(),
  52 \fIgmtime\fP(), and \fIlocaltime\fP() functions shall return values
  53 in one of two
  54 static objects: a broken-down time structure and an array of type
  55 \fBchar\fP. Execution of any of the functions may overwrite the
  56 information returned in either of these objects by any of the other
  57 functions.
  58 .LP
  59 The \fIgmtime_r\fP() function shall convert the time in seconds since
  60 the Epoch pointed to by \fItimer\fP into a broken-down time
  61 expressed as Coordinated Universal Time (UTC). The broken-down time
  62 is stored in the structure referred to by \fIresult\fP. The
  63 \fIgmtime_r\fP() function shall also return the address of the same
  64 structure.
  65 .SH RETURN VALUE
  66 .LP
  67 Upon successful completion, the \fIgmtime\fP() function shall return
  68 a pointer to a \fBstruct tm\fP. If an error is detected,
  69 \fIgmtime\fP() shall return a null pointer   \ and set \fIerrno\fP
  70 to indicate the error.
  71 .LP
  72 Upon successful completion, \fIgmtime_r\fP() shall return the address
  73 of the structure pointed to by the argument \fIresult\fP.
  74 If an error is detected, \fIgmtime_r\fP() shall return a null pointer.
  75 .SH ERRORS
  76 .LP
  77 The \fIgmtime\fP() function shall fail if:
  78 .TP 7
  79 .B EOVERFLOW
  80 The result cannot be represented.
  81 .sp
  82 .LP
  83 \fIThe following sections are informative.\fP
  84 .SH EXAMPLES
  85 .LP
  86 None.
  87 .SH APPLICATION USAGE
  88 .LP
  89 The \fIgmtime_r\fP() function is thread-safe and returns values in
  90 a user-supplied buffer instead of possibly using a static
  91 data area that may be overwritten by each call.
  92 .SH RATIONALE
  93 .LP
  94 None.
  95 .SH FUTURE DIRECTIONS
  96 .LP
  97 None.
  98 .SH SEE ALSO
  99 .LP
 100 \fIasctime\fP() , \fIclock\fP() , \fIctime\fP()
 101 , \fIdifftime\fP() , \fIlocaltime\fP() , \fImktime\fP() , \fIstrftime\fP()
 102 , \fIstrptime\fP() ,
 103 \fItime\fP() , \fIutime\fP() , the Base Definitions volume of
 104 IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP
 105 .SH COPYRIGHT
 106 Portions of this text are reprinted and reproduced in electronic form
 107 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 108 -- Portable Operating System Interface (POSIX), The Open Group Base
 109 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 110 Electrical and Electronics Engineers, Inc and The Open Group. In the
 111 event of any discrepancy between this version and the original IEEE and
 112 The Open Group Standard, the original IEEE and The Open Group Standard
 113 is the referee document. The original Standard can be obtained online at
 114 http://www.opengroup.org/unix/online.html .