logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

time.3p (5721B)


  1. '\" et
  2. .TH TIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. time
  12. \(em get time
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <time.h>
  17. .P
  18. time_t time(time_t *\fItloc\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The functionality described on this reference page is aligned with the
  22. ISO\ C standard. Any conflict between the requirements described here and the
  23. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  24. .P
  25. The
  26. \fItime\fR()
  27. function shall return the value of time
  28. in seconds since the Epoch.
  29. .P
  30. The
  31. .IR tloc
  32. argument points to an area where the return value is also stored. If
  33. .IR tloc
  34. is a null pointer, no value is stored.
  35. .SH "RETURN VALUE"
  36. Upon successful completion,
  37. \fItime\fR()
  38. shall return the value of time. Otherwise, (\fBtime_t\fP)\-1 shall be
  39. returned.
  40. .SH ERRORS
  41. The
  42. \fItime\fR()
  43. function may fail if:
  44. .TP
  45. .BR EOVERFLOW
  46. The number of seconds since the Epoch will not fit in an object of type
  47. .BR time_t .
  48. .LP
  49. .IR "The following sections are informative."
  50. .SH EXAMPLES
  51. .SS "Getting the Current Time"
  52. .P
  53. The following example uses the
  54. \fItime\fR()
  55. function to calculate the time elapsed, in seconds, since the Epoch,
  56. \fIlocaltime\fR()
  57. to convert that value to a broken-down time, and
  58. \fIasctime\fR()
  59. to convert the broken-down time values into a printable string.
  60. .sp
  61. .RS 4
  62. .nf
  63. #include <stdio.h>
  64. #include <time.h>
  65. .P
  66. int main(void)
  67. {
  68. time_t result;
  69. .P
  70. result = time(NULL);
  71. printf("%s%ju secs since the Epoch\en",
  72. asctime(localtime(&result)),
  73. (uintmax_t)result);
  74. return(0);
  75. }
  76. .fi
  77. .P
  78. .RE
  79. .P
  80. This example writes the current time to
  81. .IR stdout
  82. in a form like this:
  83. .sp
  84. .RS 4
  85. .nf
  86. Wed Jun 26 10:32:15 1996
  87. 835810335 secs since the Epoch
  88. .fi
  89. .P
  90. .RE
  91. .SS "Timing an Event"
  92. .P
  93. The following example gets the current time, prints it out in the
  94. user's format, and prints the number of minutes to an event being
  95. timed.
  96. .sp
  97. .RS 4
  98. .nf
  99. #include <time.h>
  100. #include <stdio.h>
  101. \&...
  102. time_t now;
  103. int minutes_to_event;
  104. \&...
  105. time(&now);
  106. minutes_to_event = ...;
  107. printf("The time is ");
  108. puts(asctime(localtime(&now)));
  109. printf("There are %d minutes to the event.\en",
  110. minutes_to_event);
  111. \&...
  112. .fi
  113. .P
  114. .RE
  115. .SH "APPLICATION USAGE"
  116. None.
  117. .SH RATIONALE
  118. The
  119. \fItime\fR()
  120. function returns a value in seconds while
  121. \fIclock_gettime\fR()
  122. and
  123. \fIgettimeofday\fR()
  124. return a
  125. .BR "struct timespec"
  126. (seconds and nanoseconds) and
  127. .BR "struct timeval"
  128. (seconds and microseconds), respectively, and are therefore capable of
  129. returning more precise times. The
  130. \fItimes\fR()
  131. function is also capable of more precision than
  132. \fItime\fR()
  133. as it returns a value in clock ticks, although it returns the elapsed time
  134. since an arbitrary point such as system boot time, not since the epoch.
  135. .P
  136. Implementations in which
  137. .BR time_t
  138. is a 32-bit signed integer (many historical implementations) fail in
  139. the year 2038. POSIX.1\(hy2008 does not address this problem. However, the use
  140. of the
  141. .BR time_t
  142. type is mandated in order to ease the eventual fix.
  143. .P
  144. On some systems the
  145. \fItime\fR()
  146. function is implemented using a system call that does not return an
  147. error condition in addition to the return value. On these systems it is
  148. impossible to differentiate between valid and invalid return values and
  149. hence overflow conditions cannot be reliably detected.
  150. .P
  151. The use of the
  152. .IR <time.h>
  153. header instead of
  154. .IR <sys/types.h>
  155. allows compatibility with the ISO\ C standard.
  156. .P
  157. Many historical implementations (including Version 7) and the 1984 /usr/group standard use
  158. .BR long
  159. instead of
  160. .BR time_t .
  161. This volume of POSIX.1\(hy2017 uses the latter type in order to agree with the ISO\ C standard.
  162. .SH "FUTURE DIRECTIONS"
  163. In a future version of this volume of POSIX.1\(hy2017,
  164. .BR time_t
  165. is likely to be required to be capable of representing times far in the
  166. future. Whether this will be mandated as a 64-bit type or a requirement
  167. that a specific date in the future be representable (for example, 10000
  168. AD) is not yet determined. Systems purchased after the approval of this volume of POSIX.1\(hy2017
  169. should be evaluated to determine whether their lifetime will extend
  170. past 2038.
  171. .SH "SEE ALSO"
  172. .IR "\fIasctime\fR\^(\|)",
  173. .IR "\fIclock\fR\^(\|)",
  174. .IR "\fIclock_getres\fR\^(\|)",
  175. .IR "\fIctime\fR\^(\|)",
  176. .IR "\fIdifftime\fR\^(\|)",
  177. .IR "\fIfutimens\fR\^(\|)",
  178. .IR "\fIgettimeofday\fR\^(\|)",
  179. .IR "\fIgmtime\fR\^(\|)",
  180. .IR "\fIlocaltime\fR\^(\|)",
  181. .IR "\fImktime\fR\^(\|)",
  182. .IR "\fIstrftime\fR\^(\|)",
  183. .IR "\fIstrptime\fR\^(\|)",
  184. .IR "\fItimes\fR\^(\|)",
  185. .IR "\fIutime\fR\^(\|)"
  186. .P
  187. The Base Definitions volume of POSIX.1\(hy2017,
  188. .IR "\fB<time.h>\fP"
  189. .\"
  190. .SH COPYRIGHT
  191. Portions of this text are reprinted and reproduced in electronic form
  192. from IEEE Std 1003.1-2017, Standard for Information Technology
  193. -- Portable Operating System Interface (POSIX), The Open Group Base
  194. Specifications Issue 7, 2018 Edition,
  195. Copyright (C) 2018 by the Institute of
  196. Electrical and Electronics Engineers, Inc and The Open Group.
  197. In the event of any discrepancy between this version and the original IEEE and
  198. The Open Group Standard, the original IEEE and The Open Group Standard
  199. is the referee document. The original Standard can be obtained online at
  200. http://www.opengroup.org/unix/online.html .
  201. .PP
  202. Any typographical or formatting errors that appear
  203. in this page are most likely
  204. to have been introduced during the conversion of the source files to
  205. man page format. To report such errors, see
  206. https://www.kernel.org/doc/man-pages/reporting_bugs.html .