[BACK]Return to ctime.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/ctime.3, Revision 1.62

1.62    ! kim         1: .\" $NetBSD: ctime.3,v 1.61 2019/09/02 00:24:01 sevan Exp $
1.39      jruoho      2: .\"
1.44      christos    3: .\" XXX: License missing?
1.39      jruoho      4: .\"
1.61      sevan       5: .Dd September 2, 2019
1.23      wiz         6: .Dt CTIME 3
                      7: .Os
                      8: .Sh NAME
                      9: .Nm asctime ,
                     10: .Nm asctime_r ,
                     11: .Nm ctime ,
                     12: .Nm ctime_r ,
1.36      christos   13: .Nm ctime_rz ,
1.23      wiz        14: .Nm difftime ,
                     15: .Nm gmtime ,
                     16: .Nm gmtime_r ,
                     17: .Nm localtime ,
                     18: .Nm localtime_r ,
1.36      christos   19: .Nm localtime_rz ,
                     20: .Nm mktime ,
1.53      abhinav    21: .Nm mktime_z
1.50      christos   22: .Nd convert date and time
1.23      wiz        23: .Sh LIBRARY
                     24: .Lb libc
                     25: .Sh SYNOPSIS
1.27      wiz        26: .In time.h
1.38      njoly      27: .Vt extern char *tzname[2];
1.23      wiz        28: .Ft char *
1.40      jruoho     29: .Fn asctime "const struct tm *tm"
                     30: .Ft char *
1.54      wiz        31: .Fn asctime_r "const struct tm *restrict tm" "char * restrict buf"
1.40      jruoho     32: .Ft char *
1.23      wiz        33: .Fn ctime "const time_t *clock"
                     34: .Ft char *
                     35: .Fn ctime_r "const time_t *clock"  "char *buf"
1.36      christos   36: .Ft char *
1.51      christos   37: .Fn ctime_rz "timezone_t restrict tz" "const time_t *clock"  "char *buf"
1.23      wiz        38: .Ft double
                     39: .Fn difftime "time_t time1" "time_t time0"
1.40      jruoho     40: .Ft struct tm *
                     41: .Fn gmtime "const time_t *clock"
                     42: .Ft struct tm *
                     43: .Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result"
1.23      wiz        44: .Ft struct tm *
                     45: .Fn localtime "const time_t *clock"
                     46: .Ft struct tm *
                     47: .Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result"
                     48: .Ft struct tm *
1.51      christos   49: .Fn localtime_rz "timezone_t restrict tz" "const time_t * restrict clock" "struct tm * restrict result"
1.23      wiz        50: .Ft time_t
                     51: .Fn mktime "struct tm *tm"
1.36      christos   52: .Ft time_t
1.51      christos   53: .Fn mktime_z "timezone_t restrict tz" "struct tm *restrict tm"
1.23      wiz        54: .Sh DESCRIPTION
1.40      jruoho     55: The
                     56: .Nm
                     57: family of functions provide various standard library routines
                     58: to operate with time and conversions related to time.
                     59: .Sh FUNCTIONS
                     60: .Bl -tag -width abcd
                     61: .It Fn asctime "tm"
                     62: The
                     63: .Fn asctime
                     64: function converts a time value contained in the
                     65: .Fa tm
                     66: structure to a string with the following general format:
                     67: .Bd -literal -offset indent
1.52      abhinav    68: Thu Nov 24 18:22:48 1986\en\e0
1.40      jruoho     69: .Ed
                     70: .Pp
                     71: The
                     72: .Fa tm
                     73: structure is described in
                     74: .Xr tm 3 .
                     75: .It Fn asctime_r "tm" "buf"
                     76: The
                     77: .Fn asctime_r
                     78: has the same behavior as
                     79: .Fn asctime ,
1.52      abhinav    80: but the result is stored in
1.40      jruoho     81: .Fa buf ,
                     82: which should have a size of at least 26 bytes.
                     83: .It Fn ctime "clock"
                     84: The
1.23      wiz        85: .Fn ctime
1.40      jruoho     86: function converts a
1.38      njoly      87: .Vt time_t ,
1.33      christos   88: pointed to by
1.29      joerg      89: .Fa clock ,
1.40      jruoho     90: and returns a pointer to a string with the format described above.
1.28      mlelstv    91: Years requiring fewer than four characters are padded with leading zeroes.
                     92: For years longer than four characters, the string is of the form
1.40      jruoho     93: .Bd -literal -offset indent
1.52      abhinav    94: Thu Nov 24 18:22:48     81986\en\e0
1.40      jruoho     95: .Ed
                     96: .Pp
1.28      mlelstv    97: with five spaces before the year.
                     98: These unusual formats are designed to make it less likely that older
                     99: software that expects exactly 26 bytes of output will mistakenly output
                    100: misleading values for out-of-range years.
1.48      christos  101: .Pp
                    102: The
                    103: .Fa clock
                    104: time stamp represents the time in seconds since 1970-01-01 00:00:00
                    105: Coordinated Universal Time (UTC).
                    106: The POSIX standard says that time stamps must be nonnegative
                    107: and must ignore leap seconds.
                    108: Many implementations extend POSIX by allowing negative time stamps,
                    109: and can therefore represent time stamps that predate the
                    110: introduction of UTC and are some other flavor of Universal Time (UT).
                    111: Some implementations support leap seconds, in contradiction to POSIX.
1.40      jruoho    112: .It Fn ctime_r "clock" "buf"
                    113: The
1.33      christos  114: .Fn ctime_r
                    115: is similar to
                    116: .Fn ctime ,
1.52      abhinav   117: except it places the result of the conversion in the
1.33      christos  118: .Fa buf
1.40      jruoho    119: argument, which should be 26 or more bytes long,
                    120: instead of using a global static buffer.
                    121: .It Fn ctime_rz "tz" "clock" "buf"
                    122: The
1.36      christos  123: .Fn ctime_rz
1.40      jruoho    124: function is similar to
1.36      christos  125: .Fn ctime_r ,
                    126: but it also takes a
1.51      christos  127: .Ft "timezone_t"
1.40      jruoho    128: argument, as returned by a previous call to
1.47      apb       129: .Fn tzalloc ,
1.51      christos  130: or a
                    131: .Dv NULL
                    132: pointer denoting
1.47      apb       133: Coordinated Universal Time
1.58      wiz       134: .Pq UTC .
1.40      jruoho    135: .It Fn difftime "time1" "time2"
                    136: The
                    137: .Fn difftime
                    138: function returns the difference between two calendar times,
                    139: .Fa ( time1 No - Fa time0 ) ,
                    140: expressed in seconds.
1.51      christos  141: .Pp
                    142: The
                    143: .Fn ctime_r ,
                    144: .Fn localtime_r ,
                    145: .Fn gmtime_r ,
                    146: and
                    147: .Fn asctime_r
                    148: functions
                    149: are like their unsuffixed counterparts, except that they accept an
                    150: additional argument specifying where to store the result if successful.
                    151: .Pp
                    152: The
                    153: .Fn ctime_rz ,
                    154: .Fn localtime_rz ,
                    155: and
                    156: .Fn mktime_z
                    157: functions
                    158: are like their unsuffixed counterparts, except that they accept an
                    159: extra initial
                    160: .Ar zone
1.60      christos  161: argument specifying the timezone to be used for conversion.
1.51      christos  162: If
                    163: .Fa zone
                    164: is
                    165: .Dv NULL ,
1.56      christos  166: UT is used; otherwise,
1.51      christos  167: .Fa zone
1.52      abhinav   168: should have been allocated by
1.51      christos  169: .Fn tzalloc
                    170: and should not be freed until after all uses (e.g., by calls to
                    171: .Fn strftime )
                    172: of the filled-in
                    173: .Fn tm_zone
                    174: fields.
1.40      jruoho    175: .It Fn gmtime "clock"
                    176: The
1.23      wiz       177: .Fn gmtime
1.40      jruoho    178: function converts to Coordinated Universal Time
1.58      wiz       179: .Pq UTC
1.40      jruoho    180: and returns a pointer to the
1.23      wiz       181: .Va tm
1.40      jruoho    182: structure described in
                    183: .Xr tm 3 .
                    184: .It Fn gmtime_r "clock" "result"
                    185: The
                    186: .Fn gmtime_r
1.52      abhinav   187: function provides the same functionality as
1.40      jruoho    188: .Fn gmtime ,
                    189: differing in that the caller must supply a buffer area
                    190: .Fa result
1.52      abhinav   191: in which the result is stored.
1.40      jruoho    192: .It Fn localtime "clock"
                    193: Also
                    194: .Fn localtime
                    195: is comparable to
                    196: .Fn gmtime .
                    197: However,
1.23      wiz       198: .Fn localtime
1.60      christos  199: corrects for the timezone and any timezone adjustments
1.1       jtc       200: (such as Daylight Saving Time in the U.S.A.).
1.23      wiz       201: After filling in the
                    202: .Va tm
1.40      jruoho    203: structure, the function sets the
1.23      wiz       204: .Fa tm_isdst Ns 'th
1.1       jtc       205: element of
1.23      wiz       206: .Fa tzname
1.1       jtc       207: to a pointer to an
1.60      christos  208: ASCII string that is the timezone abbreviation to be used with
1.23      wiz       209: .Fn localtime Ns 's
1.1       jtc       210: return value.
1.40      jruoho    211: .It Fn localtime_r "clock" "result"
                    212: As
                    213: .Fn gmtime_r ,
                    214: the
1.23      wiz       215: .Fn localtime_r
1.40      jruoho    216: takes an additional buffer
1.23      wiz       217: .Fa result
1.52      abhinav   218: as a parameter and stores the result in it.
1.40      jruoho    219: Note however that
1.23      wiz       220: .Fn localtime_r
1.19      kleink    221: does not imply initialization of the local time conversion information;
                    222: the application may need to do so by calling
1.23      wiz       223: .Xr tzset 3 .
1.40      jruoho    224: .It Fn localtime_rz "tz" "clock" "result"
                    225: The
1.36      christos  226: .Fn localtime_rz
1.40      jruoho    227: function is similar to
1.36      christos  228: .Fn localtime_r ,
                    229: but it also takes a
1.51      christos  230: .Ft "timezone_t"
1.36      christos  231: argument, returned by a previous call to
1.47      apb       232: .Fn tzalloc ,
1.51      christos  233: or a
                    234: .Dv NULL
                    235: pointer denoting Coordinated Universal Time
1.58      wiz       236: .Pq UTC .
1.40      jruoho    237: .It Fn mktime "tm"
                    238: The
1.29      joerg     239: .Fn mktime
1.40      jruoho    240: function converts the broken-down time,
                    241: expressed as local time in the
                    242: .Xr tm 3
                    243: structure, into a calendar time value with
                    244: the same encoding as that of the values returned by the
1.23      wiz       245: .Xr time 3
1.1       jtc       246: function.
1.40      jruoho    247: The following remarks should be taken into account.
1.42      plunky    248: .Bl -bullet
1.40      jruoho    249: .It
1.1       jtc       250: The original values of the
1.23      wiz       251: .Fa tm_wday
1.1       jtc       252: and
1.23      wiz       253: .Fa tm_yday
1.1       jtc       254: components of the structure are ignored,
                    255: and the original values of the other components are not restricted
                    256: to their normal ranges.
                    257: (A positive or zero value for
1.23      wiz       258: .Fa tm_isdst
1.1       jtc       259: causes
1.23      wiz       260: .Fn mktime
1.59      christos  261: to presume initially that daylight saving time
                    262: respectively,
1.26      wiz       263: is or is not in effect for the specified time.
1.40      jruoho    264: .It
1.26      wiz       265: A negative value for
1.23      wiz       266: .Fa tm_isdst
1.1       jtc       267: causes the
1.23      wiz       268: .Fn mktime
1.59      christos  269: function to attempt to divine whether daylight saving time is in effect
1.28      mlelstv   270: for the specified time; in this case it does not use a consistent
                    271: rule and may give a different answer when later
1.40      jruoho    272: presented with the same argument.
                    273: .It
1.1       jtc       274: On successful completion, the values of the
1.23      wiz       275: .Fa tm_wday
1.1       jtc       276: and
1.23      wiz       277: .Fa tm_yday
1.1       jtc       278: components of the structure are set appropriately,
                    279: and the other components are set to represent the specified calendar time,
                    280: but with their values forced to their normal ranges; the final value of
1.23      wiz       281: .Fa tm_mday
1.1       jtc       282: is not set until
1.23      wiz       283: .Fa tm_mon
1.1       jtc       284: and
1.23      wiz       285: .Fa tm_year
1.1       jtc       286: are determined.
1.40      jruoho    287: .El
                    288: .Pp
                    289: The function returns the specified calendar time;
                    290: if the calendar time cannot be represented, it returns
1.30      christos  291: .Va "(time_t)-1" .
1.43      christos  292: This can happen either because the resulting conversion would not fit
                    293: in a
                    294: .Vt time_t
                    295: variable, or because the time specified happens to be in the daylight
                    296: savings gap and
                    297: .Fa tm_isdst
                    298: was set to
                    299: .Dv \-1 .
                    300: Other
                    301: .Fn mktime
                    302: implementations do not return an error in the second case and return
                    303: the appropriate time offset after the daylight savings gap.
                    304: There is code to mimick this behavior, but it is not enabled by default.
1.40      jruoho    305: .It Fn mktime_z "tz" "tm"
                    306: The
1.36      christos  307: .Fn mktime_z
1.40      jruoho    308: function is similar to
1.36      christos  309: .Fn mktime
                    310: but it also takes a
                    311: .Ft "const timezone_t"
                    312: argument, returned by a previous call to
1.47      apb       313: .Fn tzalloc ,
                    314: or a null pointer denoting
                    315: Coordinated Universal Time
1.58      wiz       316: .Pq UTC .
1.40      jruoho    317: .El
1.48      christos  318: .Pp
1.52      abhinav   319: Declarations of all the functions and externals, and the
1.48      christos  320: .Ft tm
                    321: structure, are in the
                    322: .In time.h
                    323: header file.
                    324: The structure (of type)
                    325: .Ft struct tm
                    326: includes the following fields:
                    327: .Bd -literal
                    328:        int tm_sec;      /* seconds (0 - 60) */
                    329:        int tm_min;      /* minutes (0 - 59) */
                    330:        int tm_hour;     /* hours (0 - 23) */
                    331:        int tm_mday;     /* day of month (1 - 31) */
                    332:        int tm_mon;      /* month of year (0 - 11) */
                    333:        int tm_year;     /* year - 1900 */
                    334:        int tm_wday;     /* day of week (Sunday = 0) */
                    335:        int tm_yday;     /* day of year (0 - 365) */
1.62    ! kim       336:        int tm_isdst;    /* is daylight saving time in effect? */
1.55      christos  337:        char *tm_zone;   /* abbreviation of timezone name (optional) */
                    338:        long tm_gmtoff;  /* offset from UT in seconds (optional) */
1.48      christos  339: .Ed
                    340: .Bl -bullet
                    341: .It
                    342: .Va tm_isdst
1.59      christos  343: is non-zero if daylight saving time is in effect.
1.48      christos  344: .It
                    345: .Va tm_gmtoff
                    346: is the offset (in seconds) of the time represented from UT,
                    347: with positive values indicating east of the Prime Meridian.
                    348: The field's name is derived from Greenwich Mean Time, a precursor of UT.
                    349: .El
1.55      christos  350: In
                    351: .Ft struct tm
                    352: the
                    353: .Fa tm_zone
                    354: and
                    355: .Fa tm_gmtoff
                    356: fields exist, and are filled in, only if arrangements to do
                    357: so were made when the library containing these functions  was
                    358: created.
                    359: Similarly, the
                    360: .Va tzname
                    361: variable is optional.
                    362: There is no guarantee that these fields and this variable will
                    363: continue to exist in this form in future releases of this code.
1.30      christos  364: .Sh RETURN VALUES
1.41      njoly     365: .Bl -bullet
1.40      jruoho    366: .It
1.30      christos  367: On success the
1.31      wiz       368: .Fn asctime
1.30      christos  369: and
1.31      wiz       370: .Fn ctime
1.30      christos  371: functions return a pointer to a static character buffer, and the
1.36      christos  372: .Fn asctime_r ,
                    373: .Fn ctime_r ,
1.30      christos  374: and
1.36      christos  375: .Fn ctime_rz
1.30      christos  376: function return a pointer to the user-supplied buffer.
                    377: On failure they all return
                    378: .Dv NULL
                    379: and no errors are defined for them.
1.40      jruoho    380: .It
1.30      christos  381: On success the
1.31      wiz       382: .Fn gmtime ,
1.30      christos  383: and
1.31      wiz       384: .Fn localtime
1.30      christos  385: functions return a pointer to a statically allocated
                    386: .Va "struct tm"
                    387: whereas the
1.36      christos  388: .Fn gmtime_r ,
                    389: .Fn localtime_r ,
1.30      christos  390: and
1.36      christos  391: .Fn localtime_rz ,
1.30      christos  392: functions return a pointer to the user-supplied
                    393: .Va "struct tm" .
                    394: On failure they all return
                    395: .Dv NULL
                    396: and the global variable
                    397: .Va errno
                    398: is set to indicate the error.
1.40      jruoho    399: .It
1.30      christos  400: The
1.31      wiz       401: .Fn mktime
1.36      christos  402: and
                    403: .Fn mktime_z
1.30      christos  404: function returns the specified time since the Epoch as a
1.38      njoly     405: .Vt time_t
1.31      wiz       406: type value.
                    407: If the time cannot be represented, then
                    408: .Fn mktime
1.36      christos  409: and
                    410: .Fn mktime_z
                    411: return
1.30      christos  412: .Va "(time_t)-1"
                    413: setting the global variable
                    414: .Va errno
                    415: to indicate the error.
1.40      jruoho    416: .It
1.36      christos  417: The
                    418: .Fn tzalloc
                    419: function returns a pointer to a
                    420: .Ft timezone_t
                    421: object or
                    422: .Dv NULL
                    423: on failure, setting
                    424: .Va errno
                    425: to indicate the error.
1.47      apb       426: It may also return
                    427: .Dv NULL
                    428: when the
                    429: .Fa name
                    430: argument is
                    431: .Dv NULL ,
                    432: and this is not an error, but a way of referring to
                    433: Coordinated Universal Time
1.58      wiz       434: .Pq UTC .
1.40      jruoho    435: .It
1.36      christos  436: .Fn tzgetzone
                    437: function returns string containing the name of the timezone given in
                    438: .Fa tz .
1.40      jruoho    439: .El
1.23      wiz       440: .Sh FILES
                    441: .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
                    442: .It Pa /etc/localtime
1.60      christos  443: local timezone file
1.23      wiz       444: .It Pa /usr/share/zoneinfo
1.60      christos  445: timezone information directory
                    446: .It Pa usr/share/zoneinfo/localtime
                    447: local timezone file
1.23      wiz       448: .It Pa /usr/share/zoneinfo/posixrules
                    449: used with POSIX-style TZ's
                    450: .It Pa /usr/share/zoneinfo/GMT
                    451: for UTC leap seconds
                    452: .El
                    453: .Pp
1.1       jtc       454: If
1.23      wiz       455: .Pa /usr/share/zoneinfo/GMT
                    456: is absent, UTC leap seconds are loaded from
                    457: .Pa /usr/share/zoneinfo/posixrules .
1.31      wiz       458: .Sh ERRORS
1.40      jruoho    459: The described functions may fail with
1.31      wiz       460: .Bl -tag -width Er
1.37      wiz       461: .It Bq Er EINVAL
1.44      christos  462: The result cannot be represented because a parameter is incorrect, or
                    463: the conversion failed because no such time exists (for example a time
                    464: in the DST gap).
1.31      wiz       465: .It Bq Er EOVERFLOW
1.44      christos  466: The result cannot be represented because the time requested is out of bounds
                    467: and the time calculation resulted in overflow.
1.31      wiz       468: .El
1.36      christos  469: .Pp
1.40      jruoho    470: All functions that return values, except their
1.36      christos  471: .Dq z
                    472: variants, can also return the same errors as
                    473: .Xr open 2
                    474: and
                    475: .Xr malloc 3 .
1.23      wiz       476: .Sh SEE ALSO
                    477: .Xr getenv 3 ,
                    478: .Xr strftime 3 ,
1.24      wiz       479: .Xr time 3 ,
1.39      jruoho    480: .Xr tm 3 ,
1.23      wiz       481: .Xr tzset 3 ,
                    482: .Xr tzfile 5
                    483: .Sh STANDARDS
                    484: The
                    485: .Fn ctime ,
                    486: .Fn difftime ,
                    487: .Fn asctime ,
                    488: .Fn localtime ,
                    489: .Fn gmtime
1.13      kleink    490: and
1.23      wiz       491: .Fn mktime
1.13      kleink    492: functions conform to
1.40      jruoho    493: .St -ansiC .
                    494: Rest of the functions conform to
                    495: .St -p1003.1-2008 .
1.61      sevan     496: .Sh HISTORY
                    497: A
                    498: .Fn ctime
                    499: function appeared in
                    500: .At v1 .
1.40      jruoho    501: .Sh CAVEATS
1.46      christos  502: The functions that do not take an explicit
                    503: .Ft timezone_t
1.52      abhinav   504: argument return values pointing to static data; the data is overwritten by
1.26      wiz       505: each call.
1.46      christos  506: For the above functions the
1.55      christos  507: .Dv tzname
                    508: variable (once set) and the
1.23      wiz       509: .Fa tm_zone
1.1       jtc       510: field of a returned
1.23      wiz       511: .Va "struct tm"
1.57      pgoyette  512: point to an array of characters that
1.55      christos  513: can be freed or overwritten by later calls to the functions
                    514: .Fn localtime ,
                    515: .Fn tzfree ,
1.58      wiz       516: and
                    517: .Fn tzset ,
1.60      christos  518: if these functions affect the timezone information that specifies the
1.55      christos  519: abbreviation in question.
                    520: The remaining functions and data are thread-safe.
1.46      christos  521: The functions that do take an explicit
                    522: .Ft timezone_t
                    523: argument and set the fields of a supplied
                    524: .Va "struct tm"
                    525: should not call
                    526: .Fn tzfree
                    527: since the
                    528: .Fa tm_zone
                    529: field of the
                    530: .Va "struct tm"
                    531: points to data allocated by
                    532: .Fn tzalloc .
1.29      joerg     533: .Pp
1.40      jruoho    534: The
1.51      christos  535: .Fn asctime ,
                    536: .Fn asctime_r ,
                    537: .Fn ctime ,
                    538: .Fn ctime_r ,
1.28      mlelstv   539: and
1.51      christos  540: .Fn ctime_rz ,
1.40      jruoho    541: functions behave strangely for years before 1000 or after 9999.
1.28      mlelstv   542: The 1989 and 1999 editions of the C Standard say
                    543: that years from \-99 through 999 are converted without
                    544: extra spaces, but this conflicts with longstanding
                    545: tradition and with this implementation.
1.51      christos  546: The 2011 edition says that the behavior
                    547: is undefined if the year is before 1000 or after 9999.
1.28      mlelstv   548: Traditional implementations of these two functions are
                    549: restricted to years in the range 1900 through 2099.
                    550: To avoid this portability mess, new programs should use
1.29      joerg     551: .Fn strftime
1.28      mlelstv   552: instead.
                    553: .\" @(#)newctime.3     8.3
                    554: .\" This file is in the public domain, so clarified as of
                    555: .\" 2009-05-17 by Arthur David Olson.

CVSweb <webmaster@jp.NetBSD.org>