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

ctime.3p (5119B)


  1. '\" et
  2. .TH CTIME "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. ctime,
  12. ctime_r
  13. \(em convert a time value to a date and time string
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <time.h>
  18. .P
  19. char *ctime(const time_t *\fIclock\fP);
  20. char *ctime_r(const time_t *\fIclock\fP, char *\fIbuf\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. For
  24. \fIctime\fR():
  25. The functionality described on this reference page is aligned with the
  26. ISO\ C standard. Any conflict between the requirements described here and the
  27. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  28. .P
  29. The
  30. \fIctime\fR()
  31. function shall convert the time pointed to by
  32. .IR clock ,
  33. representing time in seconds since the Epoch, to local time in the form
  34. of a string. It shall be equivalent to:
  35. .sp
  36. .RS 4
  37. .nf
  38. asctime(localtime(clock))
  39. .fi
  40. .P
  41. .RE
  42. .P
  43. The
  44. \fIasctime\fR(),
  45. \fIctime\fR(),
  46. \fIgmtime\fR(),
  47. and
  48. \fIlocaltime\fR()
  49. functions shall return values in one of two static objects: a
  50. broken-down time structure and an array of
  51. .BR char .
  52. Execution of any of the functions may overwrite the information
  53. returned in either of these objects by any of the other functions.
  54. .P
  55. The
  56. \fIctime\fR()
  57. function need not be thread-safe.
  58. .P
  59. The
  60. \fIctime_r\fR()
  61. function shall convert the calendar time pointed to by
  62. .IR clock
  63. to local time in exactly the same form as
  64. \fIctime\fR()
  65. and put the string into the array pointed to by
  66. .IR buf
  67. (which shall be at least 26 bytes in size) and return
  68. .IR buf .
  69. .P
  70. Unlike
  71. \fIctime\fR(),
  72. the
  73. \fIctime_r\fR()
  74. function is not required to set
  75. .IR tzname .
  76. If
  77. \fIctime_r\fR()
  78. sets
  79. .IR tzname ,
  80. it shall also set
  81. .IR daylight
  82. and
  83. .IR timezone .
  84. If
  85. \fIctime_r\fR()
  86. does not set
  87. .IR tzname ,
  88. it shall not set
  89. .IR daylight
  90. and shall not set
  91. .IR timezone .
  92. .SH "RETURN VALUE"
  93. The
  94. \fIctime\fR()
  95. function shall return the pointer returned by
  96. \fIasctime\fR()
  97. with that broken-down time as an argument.
  98. .P
  99. Upon successful completion,
  100. \fIctime_r\fR()
  101. shall return a pointer to the string pointed to by
  102. .IR buf .
  103. When an error is encountered, a null pointer shall be returned.
  104. .SH ERRORS
  105. No errors are defined.
  106. .LP
  107. .IR "The following sections are informative."
  108. .SH EXAMPLES
  109. None.
  110. .SH "APPLICATION USAGE"
  111. These functions are included only for compatibility with older
  112. implementations. They have undefined behavior if the resulting string
  113. would be too long, so the use of these functions should be discouraged.
  114. On implementations that do not detect output string length overflow, it
  115. is possible to overflow the output buffers in such a way as to cause
  116. applications to fail, or possible system security violations. Also,
  117. these functions do not support localized date and time formats. To
  118. avoid these problems, applications should use
  119. \fIstrftime\fR()
  120. to generate strings from broken-down times.
  121. .P
  122. Values for the broken-down time structure can be obtained by calling
  123. \fIgmtime\fR()
  124. or
  125. \fIlocaltime\fR().
  126. .P
  127. The
  128. \fIctime_r\fR()
  129. function is thread-safe and shall return values in a user-supplied
  130. buffer instead of possibly using a static data area that may be
  131. overwritten by each call.
  132. .P
  133. Attempts to use
  134. \fIctime\fR()
  135. or
  136. \fIctime_r\fR()
  137. for times before the Epoch or for times beyond the year 9999 produce
  138. undefined results. Refer to
  139. .IR "\fIasctime\fR\^(\|)".
  140. .SH RATIONALE
  141. The standard developers decided to mark the
  142. \fIctime\fR()
  143. and
  144. \fIctime_r\fR()
  145. functions obsolescent even though they are in the ISO\ C standard due to the
  146. possibility of buffer overflow. The ISO\ C standard also provides the
  147. \fIstrftime\fR()
  148. function which can be used to avoid these problems.
  149. .SH "FUTURE DIRECTIONS"
  150. These functions may be removed in a future version.
  151. .SH "SEE ALSO"
  152. .IR "\fIasctime\fR\^(\|)",
  153. .IR "\fIclock\fR\^(\|)",
  154. .IR "\fIdifftime\fR\^(\|)",
  155. .IR "\fIgmtime\fR\^(\|)",
  156. .IR "\fIlocaltime\fR\^(\|)",
  157. .IR "\fImktime\fR\^(\|)",
  158. .IR "\fIstrftime\fR\^(\|)",
  159. .IR "\fIstrptime\fR\^(\|)",
  160. .IR "\fItime\fR\^(\|)",
  161. .IR "\fIutime\fR\^(\|)"
  162. .P
  163. The Base Definitions volume of POSIX.1\(hy2017,
  164. .IR "\fB<time.h>\fP"
  165. .\"
  166. .SH COPYRIGHT
  167. Portions of this text are reprinted and reproduced in electronic form
  168. from IEEE Std 1003.1-2017, Standard for Information Technology
  169. -- Portable Operating System Interface (POSIX), The Open Group Base
  170. Specifications Issue 7, 2018 Edition,
  171. Copyright (C) 2018 by the Institute of
  172. Electrical and Electronics Engineers, Inc and The Open Group.
  173. In the event of any discrepancy between this version and the original IEEE and
  174. The Open Group Standard, the original IEEE and The Open Group Standard
  175. is the referee document. The original Standard can be obtained online at
  176. http://www.opengroup.org/unix/online.html .
  177. .PP
  178. Any typographical or formatting errors that appear
  179. in this page are most likely
  180. to have been introduced during the conversion of the source files to
  181. man page format. To report such errors, see
  182. https://www.kernel.org/doc/man-pages/reporting_bugs.html .