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

asctime.3p (5910B)


  1. '\" et
  2. .TH ASCTIME "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. asctime,
  12. asctime_r
  13. \(em convert date and time to a string
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <time.h>
  18. .P
  19. char *asctime(const struct tm *\fItimeptr\fP);
  20. char *asctime_r(const struct tm *restrict \fItm\fP, char *restrict \fIbuf\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. For
  24. \fIasctime\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. \fIasctime\fR()
  31. function shall convert the broken-down time in the structure pointed
  32. to by
  33. .IR timeptr
  34. into a string in the form:
  35. .sp
  36. .RS 4
  37. .nf
  38. Sun Sep 16 01:03:52 1973\en\e0
  39. .fi
  40. .P
  41. .RE
  42. .P
  43. using the equivalent of the following algorithm:
  44. .sp
  45. .RS 4
  46. .nf
  47. char *asctime(const struct tm *timeptr)
  48. {
  49. static char wday_name[7][3] = {
  50. "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
  51. };
  52. static char mon_name[12][3] = {
  53. "Jan", "Feb", "Mar", "Apr", "May", "Jun",
  54. "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
  55. };
  56. static char result[26];
  57. .P
  58. sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\en",
  59. wday_name[timeptr->tm_wday],
  60. mon_name[timeptr->tm_mon],
  61. timeptr->tm_mday, timeptr->tm_hour,
  62. timeptr->tm_min, timeptr->tm_sec,
  63. 1900 + timeptr->tm_year);
  64. return result;
  65. }
  66. .fi
  67. .P
  68. .RE
  69. .P
  70. However, the behavior is undefined if \fItimeptr\fR\->\fItm_wday\fR or
  71. \fItimeptr\fR\->\fItm_mon\fR are not within the normal ranges as
  72. defined in
  73. .IR <time.h> ,
  74. or if \fItimeptr\fR\->\fItm_year\fR exceeds
  75. {INT_MAX}\-1990,
  76. or if the above algorithm would attempt to generate more than 26 bytes
  77. of output (including the terminating null).
  78. .P
  79. The
  80. .BR tm
  81. structure is defined in the
  82. .IR <time.h>
  83. header.
  84. .P
  85. The
  86. \fIasctime\fR(),
  87. \fIctime\fR(),
  88. \fIgmtime\fR(),
  89. and
  90. \fIlocaltime\fR()
  91. functions shall return values in one of two static objects: a
  92. broken-down time structure and an array of type
  93. .BR char .
  94. Execution of any of the functions may overwrite the information
  95. returned in either of these objects by any of the other functions.
  96. .P
  97. The
  98. \fIasctime\fR()
  99. function need not be thread-safe.
  100. .P
  101. The
  102. \fIasctime_r\fR()
  103. function shall convert the broken-down time in the structure pointed to
  104. by
  105. .IR tm
  106. into a string (of the same form as that returned by
  107. \fIasctime\fR(),
  108. and with the same undefined behavior when input or output is out of
  109. range) that is placed in the user-supplied buffer pointed to by
  110. .IR buf
  111. (which shall contain at least 26 bytes) and then return
  112. .IR buf .
  113. .SH "RETURN VALUE"
  114. Upon successful completion,
  115. \fIasctime\fR()
  116. shall return a pointer to the string.
  117. If the function is unsuccessful, it shall return NULL.
  118. .P
  119. Upon successful completion,
  120. \fIasctime_r\fR()
  121. shall return a pointer to a character string containing the date and
  122. time. This string is pointed to by the argument
  123. .IR buf .
  124. If the function is unsuccessful, it shall return NULL.
  125. .SH ERRORS
  126. No errors are defined.
  127. .LP
  128. .IR "The following sections are informative."
  129. .SH EXAMPLES
  130. None.
  131. .SH "APPLICATION USAGE"
  132. These functions are included only for compatibility with older
  133. implementations. They have undefined behavior if the resulting string
  134. would be too long, so the use of these functions should be
  135. discouraged. On implementations that do not detect output string
  136. length overflow, it is possible to overflow the output buffers in such
  137. a way as to cause applications to fail, or possible system security
  138. violations. Also, these functions do not support localized date and
  139. time formats. To avoid these problems, applications should use
  140. \fIstrftime\fR()
  141. to generate strings from broken-down times.
  142. .P
  143. Values for the broken-down time structure can be obtained by calling
  144. \fIgmtime\fR()
  145. or
  146. \fIlocaltime\fR().
  147. .P
  148. The
  149. \fIasctime_r\fR()
  150. function is thread-safe and shall return values in a user-supplied
  151. buffer instead of possibly using a static data area that may be
  152. overwritten by each call.
  153. .SH RATIONALE
  154. The standard developers decided to mark the
  155. \fIasctime\fR()
  156. and
  157. \fIasctime_r\fR()
  158. functions obsolescent even though
  159. \fIasctime\fR()
  160. is in the ISO\ C standard due to the possibility of buffer overflow. The ISO\ C standard
  161. also provides the
  162. \fIstrftime\fR()
  163. function which can be used to avoid these problems.
  164. .SH "FUTURE DIRECTIONS"
  165. These functions may be removed in a future version.
  166. .SH "SEE ALSO"
  167. .IR "\fIclock\fR\^(\|)",
  168. .IR "\fIctime\fR\^(\|)",
  169. .IR "\fIdifftime\fR\^(\|)",
  170. .IR "\fIgmtime\fR\^(\|)",
  171. .IR "\fIlocaltime\fR\^(\|)",
  172. .IR "\fImktime\fR\^(\|)",
  173. .IR "\fIstrftime\fR\^(\|)",
  174. .IR "\fIstrptime\fR\^(\|)",
  175. .IR "\fItime\fR\^(\|)",
  176. .IR "\fIutime\fR\^(\|)"
  177. .P
  178. The Base Definitions volume of POSIX.1\(hy2017,
  179. .IR "\fB<time.h>\fP"
  180. .\"
  181. .SH COPYRIGHT
  182. Portions of this text are reprinted and reproduced in electronic form
  183. from IEEE Std 1003.1-2017, Standard for Information Technology
  184. -- Portable Operating System Interface (POSIX), The Open Group Base
  185. Specifications Issue 7, 2018 Edition,
  186. Copyright (C) 2018 by the Institute of
  187. Electrical and Electronics Engineers, Inc and The Open Group.
  188. In the event of any discrepancy between this version and the original IEEE and
  189. The Open Group Standard, the original IEEE and The Open Group Standard
  190. is the referee document. The original Standard can be obtained online at
  191. http://www.opengroup.org/unix/online.html .
  192. .PP
  193. Any typographical or formatting errors that appear
  194. in this page are most likely
  195. to have been introduced during the conversion of the source files to
  196. man page format. To report such errors, see
  197. https://www.kernel.org/doc/man-pages/reporting_bugs.html .